QYRA_CORS_ALLOWED_DOMAINS=https://domain-where-you-are-going-to-use-the-sdk.com

npm install @qyra/sdk
# or
pnpm add @qyra/sdk
# or
yarn add @qyra/sdk

import "@qyra/sdk/sdk.css";

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

type DashboardProps = {
  // Required
  instanceUrl: string;              // Your Qyra instance URL
  token: string | Promise<string>;  // JWT (can be async)

  // Optional
  theme?: 'light' | 'dark';         // Force light or dark color scheme
  styles?: {
    backgroundColor?: string;       // Background color or 'transparent'
    fontFamily?: string;            // Font family for all text
  };
  filters?: SdkFilter[];            // Apply filters programmatically
  paletteUuid?: string;             // Color palette UUID for custom theming
  contentOverrides?: LanguageMap;   // Translate your content (names, titles, markdown)
  uiOverrides?: SdkUiOverrides;     // Translate Qyra UI strings (filters, menus, buttons)
  isEditMode?: boolean;             // Render the dashboard in edit mode (requires writeActions JWT)
  onEditModeChange?: (
    isEditMode: boolean,
  ) => void;                        // Callback when the embed enters or leaves edit mode
  onExplore?: (options: {
    chart: SavedChart
  }) => void;                       // Callback when user navigates to explore
};

import Qyra from '@qyra/sdk';

function MyDashboard() {
  return (
    <Qyra.Dashboard
      instanceUrl="https://app.qyraflow.com"
      token={generateToken()} // Server-side function
    />
  );
}

import Qyra, { FilterOperator } from '@qyra/sdk';

<Qyra.Dashboard
  instanceUrl="https://app.qyraflow.com"
  token={token}
  filters={[
    {
      model: 'orders',
      field: 'status',
      operator: FilterOperator.EQUALS,
      value: 'completed',
    },
    {
      model: 'orders',
      field: 'created_date',
      operator: FilterOperator.IN_BETWEEN,
      value: ['2024-01-01', '2024-12-31'],
    },
  ]}
/>

<Qyra.Dashboard
  instanceUrl="https://app.qyraflow.com"
  token={token}
  styles={{
    backgroundColor: '#f5f5f5',
    fontFamily: 'Inter, sans-serif',
  }}
/>

<Qyra.Dashboard
  instanceUrl="https://app.qyraflow.com"
  token={generateToken({ canExplore: true })}
  onExplore={({ chart }) => {
    console.log('User exploring chart:', chart.name);
    // Track analytics, show help guides, etc.
  }}
/>

import Qyra from '@qyra/sdk';
import { useState } from 'react';

function EditableDashboard() {
  const [isEditMode, setIsEditMode] = useState(false);

  return (
    <>
      {!isEditMode && (
        <button onClick={() => setIsEditMode(true)}>Edit dashboard</button>
      )}
      <Qyra.Dashboard
        instanceUrl="https://app.qyraflow.com"
        token={generateToken()} // JWT must include writeActions
        isEditMode={isEditMode}
        onEditModeChange={setIsEditMode}
      />
    </>
  );
}

type DashboardBuilderProps = {
  // Required
  instanceUrl: string;              // Your Qyra instance URL
  token: string | Promise<string>;  // JWT with writeActions claim

  // Optional
  theme?: 'light' | 'dark';
  styles?: {
    backgroundColor?: string;
    fontFamily?: string;
  };
  filters?: SdkFilter[];
  paletteUuid?: string;
  contentOverrides?: LanguageMap;
  uiOverrides?: SdkUiOverrides;
  isEditMode?: boolean;             // Render the new dashboard in edit mode
  onEditModeChange?: (
    isEditMode: boolean,
  ) => void;                        // Callback when the embed enters or leaves edit mode
  onDashboardReady?: (
    dashboard: EmbedDashboard,
  ) => void;                        // Called once the empty dashboard has been created
  onExplore?: (options: {
    chart: SavedChart
  }) => void;
};

import Qyra from '@qyra/sdk';
import { useEffect, useState } from 'react';

function MyDashboardBuilder() {
  const [isEditMode, setIsEditMode] = useState(false);
  const [isReady, setIsReady] = useState(false);

  return (
    <>
      {isReady && !isEditMode && (
        <button onClick={() => setIsEditMode(true)}>Edit dashboard</button>
      )}
      <Qyra.DashboardBuilder
        instanceUrl="https://app.qyraflow.com"
        token={generateToken()} // JWT must include writeActions
        isEditMode={isEditMode}
        onEditModeChange={setIsEditMode}
        onDashboardReady={() => setIsReady(true)}
      />
    </>
  );
}

type ChartProps = {
  // Required
  instanceUrl: string;              // Your Qyra instance URL
  id: string;                       // Chart UUID (savedQueryUuid)
  token: string | Promise<string>;  // JWT with type: 'chart'

  // Optional
  theme?: 'light' | 'dark';         // Force light or dark color scheme
  styles?: {
    backgroundColor?: string;       // Background color or 'transparent'
    fontFamily?: string;            // Font family for all text
  };
  contentOverrides?: LanguageMap;   // Translate your content (names, titles, markdown)
  uiOverrides?: SdkUiOverrides;     // Translate Qyra UI strings (filters, menus, buttons)
};

import Qyra from '@qyra/sdk';

function MyChart() {
  return (
    <Qyra.Chart
      instanceUrl="https://app.qyraflow.com"
      id="your-chart-uuid"
      token={generateChartToken()} // Server-side function
    />
  );
}

<Qyra.Chart
  instanceUrl="https://app.qyraflow.com"
  id="your-chart-uuid"
  token={token}
  styles={{
    backgroundColor: 'white',
    fontFamily: 'Helvetica, Arial, sans-serif',
  }}
/>

// Backend API endpoint
import jwt from 'jsonwebtoken';

export function generateChartToken(chartId) {
  return jwt.sign({
    content: {
      type: 'chart',
      contentId: chartId,  // savedQueryUuid
      canExportCsv: true,
      canExportImages: false,
      canViewUnderlyingData: true,
    },
  }, process.env.QYRA_EMBED_SECRET, { expiresIn: '24h' });
}

type ExploreProps = {
  // Required
  instanceUrl: string;              // Your Qyra instance URL
  token: string | Promise<string>;  // JWT with canExplore: true

  // Optional
  theme?: 'light' | 'dark';         // Force light or dark color scheme
  styles?: {
    backgroundColor?: string;       // Background color or 'transparent'
    fontFamily?: string;            // Font family for all text
  };
  contentOverrides?: LanguageMap;   // Translate your content (names, titles, markdown)
  uiOverrides?: SdkUiOverrides;     // Translate Qyra UI strings (filters, menus, buttons)
};

import Qyra from '@qyra/sdk';

function MyExplore() {
  return (
    <Qyra.Explore
      instanceUrl="https://app.qyraflow.com"
      token={generateExploreToken()} // Must include canExplore: true
    />
  );
}

<Qyra.Explore
  instanceUrl="https://app.qyraflow.com"
  token={token}
  styles={{
    backgroundColor: '#f9f9f9',
    fontFamily: 'Inter, sans-serif',
  }}
/>

// Backend API endpoint
import jwt from 'jsonwebtoken';

export function generateExploreToken() {
  return jwt.sign({
    content: {
      type: 'dashboard',  // Can use dashboard type
      dashboardUuid: 'starting-dashboard-uuid',
      canExplore: true,   // Required for explore access
      canExportCsv: true,
      canExportImages: true,
    },
  }, process.env.QYRA_EMBED_SECRET, { expiresIn: '4h' });
}

type AiAgentProps = {
  // Required
  instanceUrl: string;              // Your Qyra instance URL
  agentUuid: string;                // Agent to embed (must match the JWT)
  token: string | Promise<string>;  // JWT with content.type: 'aiAgent'

  // Optional
  threadUuid?: string;              // Open a specific thread on load
  onThreadChange?: (options: { threadUuid: string }) => void; // Fires when the embed opens or creates a thread
  theme?: 'light' | 'dark';
  styles?: {
    backgroundColor?: string;
  };
};

import Qyra from '@qyra/sdk';

function MyAiAgent() {
  return (
    <Qyra.AiAgent
      instanceUrl="https://app.qyraflow.com"
      agentUuid="your-agent-uuid"
      token={generateAiAgentToken()} // Server-side function
    />
  );
}

<Qyra.AiAgent
  instanceUrl="https://app.qyraflow.com"
  agentUuid="your-agent-uuid"
  threadUuid="thread-uuid"
  token={token}
/>

import Qyra from '@qyra/sdk';
import { useState } from 'react';

const STORAGE_KEY = 'acme-shop:qyra-ai-thread';

function ShopInsightsAgent({ token }: { token: string }) {
  const [threadUuid, setThreadUuid] = useState<string | undefined>(
    () => localStorage.getItem(STORAGE_KEY) ?? undefined,
  );

  return (
    <Qyra.AiAgent
      instanceUrl="https://app.qyraflow.com"
      agentUuid="agent-shop-insights"
      token={token}
      threadUuid={threadUuid}
      onThreadChange={({ threadUuid: nextThreadUuid }) => {
        setThreadUuid(nextThreadUuid);
        localStorage.setItem(STORAGE_KEY, nextThreadUuid);
      }}
    />
  );
}

// Backend API endpoint
import jwt from 'jsonwebtoken';

export function generateAiAgentToken() {
  return jwt.sign({
    content: {
      type: 'aiAgent',
      projectUuid: 'your-project-uuid',
      agentUuid: 'your-agent-uuid',
    },
    writeActions: {
      serviceAccountUserUuid: 'service-account-user-uuid',
      spaceUuid: 'destination-space-uuid',
    },
    userAttributes: {
      tenant_id: 'tenant-abc',
    },
  }, process.env.QYRA_EMBED_SECRET, { expiresIn: '1h' });
}

type MetricsCatalogProps = {
  // Required
  instanceUrl: string;              // Your Qyra instance URL
  token: string | Promise<string>;  // JWT with content.type: 'metricsCatalog'

  // Optional
  theme?: 'light' | 'dark';         // Force light or dark color scheme
  styles?: {
    backgroundColor?: string;       // Background color or 'transparent'
    fontFamily?: string;            // Font family for all text
  };
};

import Qyra from '@qyra/sdk';

function MyMetricsCatalog() {
  return (
    <Qyra.MetricsCatalog
      instanceUrl="https://app.qyraflow.com"
      token={generateMetricsCatalogToken()} // Server-side function
    />
  );
}

// Backend API endpoint
import jwt from 'jsonwebtoken';

export function generateMetricsCatalogToken() {
  return jwt.sign({
    content: {
      type: 'metricsCatalog',
      projectUuid: 'your-project-uuid',
      canExplore: true,
    },
    writeActions: {
      serviceAccountUserUuid: 'service-account-user-uuid',
      spaceUuid: 'destination-space-uuid',
    },
    userAttributes: {
      tenant_id: 'tenant-abc',
    },
  }, process.env.QYRA_EMBED_SECRET, { expiresIn: '1h' });
}

import jwt from 'jsonwebtoken';

export function generateContentCatalogToken() {
  return jwt.sign(
    {
      content: {
        type: 'apiAccess',
        projectUuid: 'your-project-uuid',
        serviceAccountUserUuid: 'service-account-user-uuid',
      },
      user: {
        externalId: 'customer-user-123',
        email: 'customer@example.com',
      },
      userAttributes: {
        tenant_id: 'tenant-abc',
      },
    },
    process.env.QYRA_EMBED_SECRET,
    { expiresIn: '1h' },
  );
}

import Qyra from '@qyra/sdk';

function ContentCatalog({
  instanceUrl,
  projectUuid,
  token,
  spaceUuid,
}: {
  instanceUrl: string;
  projectUuid: string;
  token: string;
  spaceUuid: string;
}) {
  const { data, error, isLoading, refetch } = Qyra.useQyraContent(
    {
      instanceUrl,
      projectUuid,
      auth: {
        type: 'embedToken',
        token,
      },
    },
    {
      spaceUuids: [spaceUuid],
      contentTypes: ['dashboard', 'chart'],
      page: 1,
      pageSize: 50,
      sortBy: 'name',
      sortDirection: 'asc',
    },
  );

  if (isLoading) return <p>Loading content...</p>;
  if (error) return <p>Unable to load content</p>;

  return (
    <div>
      <button type="button" onClick={() => refetch()}>
        Refresh
      </button>

      {data?.data.map((item) => (
        <button key={item.uuid} type="button">
          {item.name}
        </button>
      ))}
    </div>
  );
}

type ListContentOptions = {
  projectUuids?: string[];
  spaceUuids?: string[];
  parentSpaceUuid?: string;
  contentTypes?: Array<'space' | 'dashboard' | 'chart' | 'data_app'>;
  page?: number;
  pageSize?: number;
  search?: string;
  sortBy?: 'name' | 'space_name' | 'last_updated_at';
  sortDirection?: 'asc' | 'desc';
};

type ListAiAgentThreadsOptions = {
  agentUuid: string;      // The agent whose threads should be listed
  projectUuid?: string;   // Falls back to the projectUuid on QyraApiClientConfig
};

type QyraAiAgentThreadResults = QyraAiAgentThread[];

// One entry per thread the embed user can see. Full shape lives in
// @qyra/common's ApiAiAgentThreadSummaryListResponse; the useful fields
// for building thread history UIs are:
type QyraAiAgentThread = {
  uuid: string;
  title?: string;
  firstMessage: { message: string };
  // ...additional metadata such as timestamps
};

import Qyra, {
  useQyraAiAgentThreads,
  type QyraApiClientConfig,
} from '@qyra/sdk';
import { useState } from 'react';

const STORAGE_KEY = 'acme-shop:qyra-ai-thread';

function ShopInsightsAgentWithHistory({
  token,
  projectUuid,
  agentUuid,
}: {
  token: string;
  projectUuid: string;
  agentUuid: string;
}) {
  const apiConfig: QyraApiClientConfig = {
    instanceUrl: 'https://app.qyraflow.com',
    projectUuid,
    auth: { type: 'embedToken', token },
  };

  const threads = Qyra.useQyraAiAgentThreads(apiConfig, {
    agentUuid,
    projectUuid,
  });

  const [threadUuid, setThreadUuid] = useState<string | undefined>(
    () => localStorage.getItem(STORAGE_KEY) ?? undefined,
  );

  return (
    <div style={{ display: 'grid', gridTemplateColumns: '280px 1fr' }}>
      <aside>
        <button type="button" onClick={() => setThreadUuid(undefined)}>
          New thread
        </button>

        {threads.isLoading && <p>Loading history…</p>}
        {threads.data?.map((thread) => (
          <button
            key={thread.uuid}
            type="button"
            onClick={() => setThreadUuid(thread.uuid)}
          >
            {thread.title ?? thread.firstMessage.message}
          </button>
        ))}
      </aside>

      <Qyra.AiAgent
        instanceUrl="https://app.qyraflow.com"
        token={token}
        agentUuid={agentUuid}
        threadUuid={threadUuid}
        onThreadChange={({ threadUuid: nextThreadUuid }) => {
          setThreadUuid(nextThreadUuid);
          localStorage.setItem(STORAGE_KEY, nextThreadUuid);
          // Refresh the sidebar so new threads show up immediately.
          threads.refetch();
        }}
      />
    </div>
  );
}

// server/api/embed-token.ts
import jwt from 'jsonwebtoken';

export async function generateEmbedToken(req, res) {
  // Authenticate user
  const userId = req.user.id;
  const user = await getUserFromDatabase(userId);

  // Generate token with user-specific attributes
  const token = jwt.sign({
    content: {
      type: 'dashboard',
      dashboardUuid: 'your-dashboard-uuid',
      dashboardFiltersInteractivity: {
        enabled: 'all',
      },
      canExportCsv: true,
      canExplore: true,
    },
    userAttributes: {
      tenant_id: user.tenantId,  // Row-level filtering
    },
    user: {
      externalId: user.id,
      email: user.email,
    },
  }, process.env.QYRA_EMBED_SECRET, { expiresIn: '1h' });

  res.json({ token });
}

import Qyra from '@qyra/sdk';
import { useState, useEffect } from 'react';

function EmbeddedDashboard() {
  const [token, setToken] = useState<string | null>(null);

  useEffect(() => {
    // Fetch token from your backend
    fetch('/api/embed-token')
      .then(res => res.json())
      .then(data => setToken(data.token));
  }, []);

  if (!token) return <div>Loading...</div>;

  return (
    <Qyra.Dashboard
      instanceUrl="https://app.qyraflow.com"
      token={token}
    />
  );
}

styles?: {
  fontFamily?: string;       // Sets all fonts within the component
  backgroundColor?: string;  // Sets the background color or 'transparent'
}

<Qyra.Dashboard
  instanceUrl={qyraUrl}
  token={qyraToken}
  styles={{
    fontFamily: 'Inter, sans-serif',
  }}
/>

<Qyra.Dashboard
  instanceUrl={qyraUrl}
  token={qyraToken}
  styles={{
    backgroundColor: 'transparent',
  }}
/>

<Qyra.Dashboard
  instanceUrl={qyraUrl}
  token={qyraToken}
  styles={{
    backgroundColor: '#f5f5f5',
    fontFamily: 'Helvetica, Arial, sans-serif',
  }}
/>

.ld-dashboard-filters {
  gap: 1rem;
}

.ld-dashboard-filter-dropdown {
  font-size: 1rem;
  min-width: 380px;
}

<Qyra.Dashboard
  instanceUrl={qyraUrl}
  token={qyraToken}
  theme="dark"
/>

import Qyra from '@qyra/sdk';
import { useState } from 'react';

function EmbeddedDashboard() {
  const [theme, setTheme] = useState<'light' | 'dark'>('light');

  return (
    <Qyra.Dashboard
      instanceUrl={qyraUrl}
      token={qyraToken}
      theme={theme}
    />
  );
}

<Qyra.Dashboard
  instanceUrl={qyraUrl}
  token={qyraToken}
  theme="dark"
  styles={{
    backgroundColor: '#0b0b0f', // Overrides the default dark background
  }}
/>

<Qyra.Dashboard
  instanceUrl="https://app.qyraflow.com"
  token={token}
  paletteUuid="your-palette-uuid"
/>

type SdkFilter = {
  model: string;             // The model the dimension is part of
  field: string;             // The name of the dimension to filter by
  operator: FilterOperator;  // The filter operator (enum)
  value: unknown | unknown[]; // The value(s) to filter against
};

<Qyra.Dashboard
  instanceUrl={qyraUrl}
  token={qyraToken}
  filters={[
    {
      model: 'dbt_users',
      field: 'browser',
      operator: FilterOperator.INCLUDE,
      value: ['chrome', 'safari'],
    },
  ]}
/>

<Qyra.Dashboard
  instanceUrl={qyraUrl}
  token={qyraToken}
  filters={[
    {
      model: 'dbt_users',
      field: 'created_date_week',
      operator: FilterOperator.IN_BETWEEN,
      value: ['2024-08', '2024-10'],
    },
    {
      model: 'dbt_users',
      field: 'browser',
      operator: FilterOperator.INCLUDE,
      value: ['chrome', 'safari'],
    },
    {
      model: 'orders',
      field: 'status',
      operator: FilterOperator.EQUALS,
      value: 'completed',
    },
  ]}
/>

import Qyra, { FilterOperator } from '@qyra/sdk';

qyra download --language-map

dashboard:
  sdk-dash:
    name: SDK dashboard demo
    description: "A dashboard demonstrating SDK features"
    filters:
      labels:
        Completed orders: Completed orders
        Order period: Order period
    tiles:
      - type: markdown
        properties:
          title: SDK demo dashboard
          content: >-
            This dashboard contains various tile types for showing SDK
            features.
      - type: saved_chart
        properties:
          title: "How do payment methods vary across different amount ranges?"

import i18n from 'i18next';

<Qyra.Dashboard
  instanceUrl={qyraUrl}
  token={qyraToken}
  contentOverrides={i18n.getResourceBundle(
    i18n.language,      // Specify language
    'demo-dashboard',   // Specify namespace
  )}
/>

import i18next from 'i18next';
import { initReactI18next } from 'react-i18next';
import Locize from 'i18next-locize-backend';

i18next
  .use(Locize)  // Add Locize backend
  .use(initReactI18next)  // Bind react-i18next
  .init({
    // Locize configuration
    backend: {
      projectId: 'your-locize-project-id',
      apiKey: 'your-api-key',
      referenceLng: 'en',
    },
    lng: 'en',
    fallbackLng: 'en',
    interpolation: {
      escapeValue: false,
    },
  });

import Qyra, { type SdkUiOverrides } from '@qyra/sdk';

const frenchUi: SdkUiOverrides = {
  'filters.addFilter': 'Ajouter un filtre',
  'filters.apply': 'Appliquer',
  'filters.operators.equals': 'est',
  'filters.operators.inThePast': 'au cours des derniers',
  'filters.unitsOfTime.days.plural': 'jours',
  'filters.unitsOfTime.days.completedPlural': 'jours révolus',
  'dateZoom.defaultZoom': 'Zoom par défaut',
  'tileMenu.downloadData': 'Télécharger les données',
};

<Qyra.Dashboard
  instanceUrl={instanceUrl}
  token={token}
  contentOverrides={frenchLanguageMap} // your content
  uiOverrides={frenchUi}               // Qyra's UI
/>;

// locales/fr/translation.json → { "uiOverrides": { "filters.apply": "Appliquer", ... } }
const uiOverrides = i18n.getResourceBundle(i18n.language, 'translation')?.uiOverrides;

<Qyra.Dashboard ... uiOverrides={uiOverrides} key={i18n.language} />;

// server.js
import express from 'express';
import jwt from 'jsonwebtoken';
import cors from 'cors';

const app = express();
app.use(cors());

app.get('/api/dashboard-token', authenticateUser, async (req, res) => {
  const user = await getUserFromDatabase(req.user.id);

  const token = jwt.sign({
    content: {
      type: 'dashboard',
      dashboardUuid: 'abc-123-def-456',
      dashboardFiltersInteractivity: { enabled: 'all' },
      parameterInteractivity: { enabled: true },
      canExportCsv: true,
      canExportImages: true,
      canExplore: true,
      canViewUnderlyingData: true,
    },
    userAttributes: {
      tenant_id: user.tenantId,
      region: user.region,
    },
    user: {
      externalId: user.id,
      email: user.email,
    },
  }, process.env.QYRA_EMBED_SECRET, { expiresIn: '2h' });

  res.json({ token, projectUuid: process.env.QYRA_PROJECT_UUID });
});

app.listen(3000);

// Dashboard.tsx
import { useState, useEffect } from 'react';
import Qyra, { FilterOperator } from '@qyra/sdk';

export function EmbeddedDashboard() {
  const [token, setToken] = useState<string | null>(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    fetch('/api/dashboard-token')
      .then(res => res.json())
      .then(data => {
        setToken(data.token);
        setLoading(false);
      })
      .catch(err => {
        console.error('Failed to load token:', err);
        setLoading(false);
      });
  }, []);

  if (loading) return <div>Loading analytics...</div>;
  if (!token) return <div>Failed to load dashboard</div>;

  return (
    <div style={{ height: '100vh', width: '100%' }}>
      <Qyra.Dashboard
        instanceUrl="https://app.qyraflow.com"
        token={token}
        filters={[
          {
            model: 'orders',
            field: 'status',
            operator: FilterOperator.EQUALS,
            value: 'completed',
          },
        ]}
        styles={{
          backgroundColor: 'transparent',
          fontFamily: 'Inter, -apple-system, sans-serif',
        }}
        onExplore={({ chart }) => {
          console.log('User exploring:', chart.name);
          // Track analytics event
        }}
      />
    </div>
  );
}