@lightdash/query-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2021-present Telescope Technology Limited (trading as “Lightdash”)
+
+Portions of this software are licensed as follows:
+
+* All content that resides under the "packages/backend/src/ee" directory of this repository, if that directory exists, is licensed under the license defined in "packages/backend/src/ee/LICENSE".
+* All third party components incorporated into the Lightdash Software are licensed under the original license provided by the owner of the applicable component.
+* Content outside of the above mentioned directories or restrictions above is available under the "MIT" license as defined below.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,134 @@
+# @lightdash/query-sdk
+
+A React SDK for building custom data apps against the Lightdash semantic layer.
+
+## Quick start
+
+```tsx
+import {
+    createClient,
+    LightdashProvider,
+    useLightdash,
+} from '@lightdash/query-sdk';
+
+const lightdash = createClient();
+
+function App() {
+    return (
+        <LightdashProvider client={lightdash}>
+            <Dashboard />
+        </LightdashProvider>
+    );
+}
+
+function Dashboard() {
+    const { data, loading, error } = useLightdash(
+        lightdash
+            .model('orders')
+            .dimensions(['customer_segment'])
+            .metrics(['total_revenue', 'order_count'])
+            .filters([
+                {
+                    field: 'order_date',
+                    operator: 'inThePast',
+                    value: 90,
+                    unit: 'days',
+                },
+            ])
+            .sorts([{ field: 'total_revenue', direction: 'desc' }])
+            .limit(10),
+    );
+
+    if (loading) return <p>Loading...</p>;
+    if (error) return <p>Error: {error.message}</p>;
+
+    return (
+        <ul>
+            {data.map((row, i) => (
+                <li key={i}>
+                    {row.customer_segment}: {row.total_revenue}
+                </li>
+            ))}
+        </ul>
+    );
+}
+```
+
+Result rows are flat objects with raw typed values (numbers are numbers, strings are strings).
+
+## Authentication
+
+The SDK reads credentials from env vars. For Vite projects, add a `.env` file:
+
+```
+VITE_LIGHTDASH_API_KEY=your-pat-token
+VITE_LIGHTDASH_URL=https://app.lightdash.cloud
+VITE_LIGHTDASH_PROJECT_UUID=your-project-uuid
+```
+
+For Node/E2B environments, use unprefixed names (`LIGHTDASH_API_KEY`, etc.).
+
+Calling `createClient()` with no arguments reads from env vars. You can also pass config explicitly:
+
+```ts
+const lightdash = createClient({
+    apiKey: token,
+    baseUrl: 'https://app.lightdash.cloud',
+    projectUuid: 'uuid',
+});
+```
+
+## Query builder
+
+Queries are built with a chainable, immutable API. Field names use short names (e.g. `driver_name`), and the SDK qualifies them automatically for the API.
+
+```ts
+lightdash
+    .model('orders')
+    .dimensions(['customer_name', 'order_date'])
+    .metrics(['total_revenue', 'order_count'])
+    .filters([
+        { field: 'status', operator: 'equals', value: 'completed' },
+        { field: 'amount', operator: 'greaterThan', value: 1000 },
+        { field: 'order_date', operator: 'inThePast', value: 90, unit: 'days' },
+    ])
+    .sorts([{ field: 'total_revenue', direction: 'desc' }])
+    .limit(100);
+```
+
+Supported filter operators: `equals`, `notEquals`, `greaterThan`, `lessThan`, `greaterThanOrEqual`, `lessThanOrEqual`, `inThePast`, `notInThePast`, `inTheNext`, `inTheCurrent`, `notInTheCurrent`, `inBetween`, `notInBetween`, `isNull`, `notNull`, `startsWith`, `endsWith`, `include`, `doesNotInclude`.
+
+## Results
+
+`useLightdash(query)` returns:
+
+| Field     | Type            | Description                                                      |
+| --------- | --------------- | ---------------------------------------------------------------- |
+| `data`    | `Row[]`         | Array of flat objects. Numbers are numbers, strings are strings. |
+| `loading` | `boolean`       | True while the query is running.                                 |
+| `error`   | `Error \| null` | Error if the query failed.                                       |
+| `refetch` | `() => void`    | Re-run the query.                                                |
+
+## User context
+
+```ts
+const user = await lightdash.auth.getUser();
+// { name: 'John Doe', email: '...', role: 'admin', orgId: '...', attributes: {} }
+```
+
+## How it works
+
+1. `createClient()` sets up auth and the API transport
+2. `<LightdashProvider>` makes the transport available to hooks via React context
+3. `useLightdash(query)` posts to the async metric query endpoint, polls for results, and returns flat rows
+4. Field IDs are auto-qualified (`driver_name` becomes `fct_race_results_driver_name` for the API)
+
+## Development
+
+```bash
+pnpm -F query-sdk typecheck    # type check
+pnpm -F query-sdk lint          # lint
+pnpm -F query-sdk fix-format    # format with oxfmt
+```
+
+See `example/` for a working F1 dashboard demo.

package/dist/LightdashProvider.d.ts

@@ -0,0 +1,23 @@
+/**
+ * React context provider for the Lightdash client.
+ *
+ * Usage:
+ *   const lightdash = createClient({ apiKey, baseUrl, projectUuid })
+ *   <LightdashProvider client={lightdash}>
+ */
+import { type ReactNode } from 'react';
+import { type LightdashClient } from './client';
+import type { Transport } from './types';
+export declare function useTransport(): Transport;
+export declare function useLightdashClient(): LightdashClient | null;
+type LightdashProviderProps = {
+    children: ReactNode;
+} & ({
+    client: LightdashClient;
+    transport?: never;
+} | {
+    transport: Transport;
+    client?: never;
+});
+export declare function LightdashProvider({ children, ...props }: LightdashProviderProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/LightdashProvider.js

@@ -0,0 +1,35 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * React context provider for the Lightdash client.
+ *
+ * Usage:
+ *   const lightdash = createClient({ apiKey, baseUrl, projectUuid })
+ *   <LightdashProvider client={lightdash}>
+ */
+import { createContext, useContext, useMemo } from 'react';
+const LightdashContext = createContext(null);
+export function useTransport() {
+    const ctx = useContext(LightdashContext);
+    if (!ctx) {
+        throw new Error('useLightdash must be used inside <LightdashProvider>. ' +
+            'Wrap your app in <LightdashProvider client={...}>.');
+    }
+    return ctx.transport;
+}
+export function useLightdashClient() {
+    const ctx = useContext(LightdashContext);
+    return ctx?.client ?? null;
+}
+export function LightdashProvider({ children, ...props }) {
+    const client = ('client' in props ? props.client : null) ?? null;
+    const transport = client?.transport ??
+        ('transport' in props ? props.transport : null) ??
+        null;
+    const value = useMemo(() => {
+        if (!transport) {
+            throw new Error('LightdashProvider requires either a client or transport prop.');
+        }
+        return { client, transport };
+    }, [client, transport]);
+    return (_jsx(LightdashContext.Provider, { value: value, children: children }));
+}

package/dist/apiTransport.d.ts

@@ -0,0 +1,11 @@
+/**
+ * API transport — executes queries against the real Lightdash async metrics endpoint.
+ *
+ * Flow:
+ * 1. POST /api/v2/projects/{projectUuid}/query/metric-query
+ *    → returns { queryUuid }
+ * 2. Poll GET /api/v2/projects/{projectUuid}/query/{queryUuid}
+ *    → returns results when status is 'ready'
+ */
+import type { LightdashClientConfig, Transport } from './types';
+export declare function createApiTransport(config: LightdashClientConfig): Transport;

package/dist/apiTransport.js

@@ -0,0 +1,205 @@
+/**
+ * API transport — executes queries against the real Lightdash async metrics endpoint.
+ *
+ * Flow:
+ * 1. POST /api/v2/projects/{projectUuid}/query/metric-query
+ *    → returns { queryUuid }
+ * 2. Poll GET /api/v2/projects/{projectUuid}/query/{queryUuid}
+ *    → returns results when status is 'ready'
+ */
+const POLL_INTERVAL_MS = 500;
+const MAX_POLL_ATTEMPTS = 120; // 60 seconds max
+/**
+ * Convert SDK filter definitions into the Lightdash API filter format.
+ * The API expects { dimensions: { id, and: [...rules] } }
+ */
+function buildApiFilters(filters) {
+    if (filters.length === 0) {
+        return {};
+    }
+    // For now, all filters are AND-ed on dimensions.
+    // TODO: support metric filters and OR groups
+    const rules = filters.map((f, i) => ({
+        id: `sdk-filter-${i}`,
+        target: { fieldId: f.fieldId },
+        operator: f.operator,
+        values: f.values,
+        ...(f.settings ? { settings: f.settings } : {}),
+    }));
+    return {
+        dimensions: {
+            id: 'sdk-root',
+            and: rules,
+        },
+    };
+}
+async function apiFetch(config, method, path, body) {
+    // Use relative paths when a proxy is available (dev server),
+    // or the full base URL when calling the API directly (production).
+    const useProxy = config.useProxy ?? false;
+    const baseUrl = useProxy ? '' : config.baseUrl.replace(/\/$/, '');
+    const url = `${baseUrl}${path}`;
+    const res = await fetch(url, {
+        method,
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `ApiKey ${config.apiKey}`,
+        },
+        ...(body ? { body: JSON.stringify(body) } : {}),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        let message;
+        try {
+            const parsed = JSON.parse(text);
+            message = parsed.error?.message ?? parsed.message ?? text;
+        }
+        catch {
+            message = text;
+        }
+        throw new Error(`Lightdash API error (${res.status}): ${message}`);
+    }
+    const json = (await res.json());
+    return json.results;
+}
+function mapColumnType(type) {
+    if (/timestamp/i.test(type))
+        return 'timestamp';
+    if (/date/i.test(type))
+        return 'date';
+    if (/number|int|float|average|count|sum|min|max|median|percentile/i.test(type))
+        return 'number';
+    if (/boolean/i.test(type))
+        return 'boolean';
+    return 'string';
+}
+export function createApiTransport(config) {
+    return {
+        async executeQuery(query) {
+            const table = query.exploreName;
+            // Lightdash field IDs are `{table}_{column}`.
+            // The SDK lets users write short names like 'driver_name'
+            // and we qualify them to 'fct_race_results_driver_name'.
+            const qualify = (fieldId) => fieldId.startsWith(`${table}_`)
+                ? fieldId
+                : `${table}_${fieldId}`;
+            const qualifiedDims = query.dimensions.map(qualify);
+            const qualifiedMetrics = query.metrics.map(qualify);
+            // Step 1: Execute async query
+            const body = {
+                query: {
+                    exploreName: table,
+                    dimensions: qualifiedDims,
+                    metrics: qualifiedMetrics,
+                    filters: buildApiFilters(query.filters.map((f) => ({
+                        ...f,
+                        fieldId: qualify(f.fieldId),
+                    }))),
+                    sorts: query.sorts.map((s) => ({
+                        fieldId: qualify(s.fieldId),
+                        descending: s.descending,
+                    })),
+                    limit: query.limit,
+                    tableCalculations: [],
+                },
+            };
+            const execResult = await apiFetch(config, 'POST', `/api/v2/projects/${config.projectUuid}/query/metric-query`, body);
+            const { queryUuid, fields } = execResult;
+            // Step 2: Poll for results
+            let attempts = 0;
+            while (attempts < MAX_POLL_ATTEMPTS) {
+                const pollResult = await apiFetch(config, 'GET', `/api/v2/projects/${config.projectUuid}/query/${queryUuid}`);
+                if (pollResult.status === 'ready') {
+                    // Build a mapping from qualified → short field names
+                    // so app code uses row.driver_name, not row.fct_race_results_driver_name
+                    const allShort = [...query.dimensions, ...query.metrics];
+                    const allQualified = [
+                        ...qualifiedDims,
+                        ...qualifiedMetrics,
+                    ];
+                    const qualifiedToShort = new Map();
+                    for (let i = 0; i < allShort.length; i++) {
+                        qualifiedToShort.set(allQualified[i], allShort[i]);
+                    }
+                    // Map columns from field metadata
+                    const columns = allQualified.map((qFieldId) => {
+                        const shortName = qualifiedToShort.get(qFieldId) ?? qFieldId;
+                        const fieldMeta = fields[qFieldId];
+                        const colMeta = pollResult.columns[qFieldId];
+                        return {
+                            name: shortName,
+                            label: fieldMeta?.label ?? shortName,
+                            type: mapColumnType(colMeta?.type ?? fieldMeta?.type ?? 'string'),
+                        };
+                    });
+                    // Map rows: extract raw values, keep formatted for format()
+                    const formattedCache = new Map();
+                    const rows = pollResult.rows.map((apiRow) => {
+                        const row = {};
+                        for (const qFieldId of allQualified) {
+                            const shortName = qualifiedToShort.get(qFieldId) ?? qFieldId;
+                            const cell = apiRow[qFieldId];
+                            if (!cell) {
+                                row[shortName] = null;
+                                continue;
+                            }
+                            const { raw, formatted } = cell.value;
+                            // Store formatted value for the format() function
+                            if (!formattedCache.has(shortName)) {
+                                formattedCache.set(shortName, new Map());
+                            }
+                            formattedCache.get(shortName).set(raw, formatted);
+                            // Convert raw to typed value
+                            if (raw === null || raw === undefined) {
+                                row[shortName] = null;
+                            }
+                            else if (typeof raw === 'number') {
+                                row[shortName] = raw;
+                            }
+                            else if (typeof raw === 'boolean') {
+                                row[shortName] = raw;
+                            }
+                            else {
+                                row[shortName] = String(raw);
+                            }
+                        }
+                        return row;
+                    });
+                    const format = (row, fieldId) => {
+                        const rawVal = row[fieldId];
+                        const cache = formattedCache.get(fieldId);
+                        if (cache) {
+                            const formatted = cache.get(rawVal);
+                            if (formatted !== undefined)
+                                return formatted;
+                        }
+                        return String(rawVal ?? '');
+                    };
+                    return { rows, columns, format };
+                }
+                if (pollResult.status === 'error' ||
+                    pollResult.status === 'expired') {
+                    throw new Error(`Query failed: ${pollResult.error ?? 'unknown error'}`);
+                }
+                if (pollResult.status === 'cancelled') {
+                    throw new Error('Query was cancelled');
+                }
+                // Still running — wait and retry
+                // eslint-disable-next-line no-promise-executor-return
+                await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+                attempts++;
+            }
+            throw new Error('Query timed out waiting for results');
+        },
+        async getUser() {
+            const user = await apiFetch(config, 'GET', '/api/v1/user');
+            return {
+                name: `${user.firstName} ${user.lastName}`.trim(),
+                email: user.email,
+                role: user.role,
+                orgId: user.organizationUuid,
+                attributes: user.userAttributes ?? {},
+            };
+        },
+    };
+}

package/dist/client.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Lightdash client.
+ *
+ * Usage:
+ *   // Auto-configure from env vars (Vite reads .env automatically)
+ *   const lightdash = createClient()
+ *
+ *   // Or explicit config
+ *   const lightdash = createClient({
+ *     apiKey: 'pat_xxx',
+ *     baseUrl: 'https://app.lightdash.cloud',
+ *     projectUuid: 'uuid',
+ *   })
+ */
+import { QueryBuilder } from './query';
+import type { LightdashClientConfig, LightdashUser, Transport } from './types';
+export declare class LightdashClient {
+    readonly config: LightdashClientConfig;
+    readonly transport: Transport;
+    readonly auth: {
+        getUser: () => Promise<LightdashUser>;
+    };
+    constructor(config: LightdashClientConfig, transport?: Transport);
+    /** Start building a query against a model */
+    model(exploreName: string): QueryBuilder;
+}
+/**
+ * Create a Lightdash client.
+ *
+ * With no args, reads from env vars:
+ *   const lightdash = createClient()
+ *
+ * With explicit config (used when token comes from parent frame):
+ *   const lightdash = createClient({ apiKey, baseUrl, projectUuid })
+ */
+export declare function createClient(config?: LightdashClientConfig): LightdashClient;

package/dist/client.js

@@ -0,0 +1,78 @@
+/**
+ * Lightdash client.
+ *
+ * Usage:
+ *   // Auto-configure from env vars (Vite reads .env automatically)
+ *   const lightdash = createClient()
+ *
+ *   // Or explicit config
+ *   const lightdash = createClient({
+ *     apiKey: 'pat_xxx',
+ *     baseUrl: 'https://app.lightdash.cloud',
+ *     projectUuid: 'uuid',
+ *   })
+ */
+import { createApiTransport } from './apiTransport';
+import { QueryBuilder } from './query';
+export class LightdashClient {
+    constructor(config, transport) {
+        this.config = config;
+        this.transport = transport ?? createApiTransport(config);
+        this.auth = {
+            getUser: () => this.transport.getUser(),
+        };
+    }
+    /** Start building a query against a model */
+    model(exploreName) {
+        return new QueryBuilder(exploreName);
+    }
+}
+/**
+ * Resolve config from env vars.
+ *
+ * Vite (.env file, statically replaced at build time):
+ *   VITE_LIGHTDASH_API_KEY=pat_xxx
+ *   VITE_LIGHTDASH_URL=https://app.lightdash.cloud
+ *   VITE_LIGHTDASH_PROJECT_UUID=uuid
+ *
+ * Node/E2B (runtime):
+ *   LIGHTDASH_API_KEY=pat_xxx
+ *   LIGHTDASH_URL=https://app.lightdash.cloud
+ *   LIGHTDASH_PROJECT_UUID=uuid
+ */
+function configFromEnv() {
+    // Vite statically replaces import.meta.env.VITE_X at build time.
+    // These must be written out in full -- dynamic access won't work.
+    const apiKey = import.meta.env?.VITE_LIGHTDASH_API_KEY ??
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        globalThis.process?.env?.LIGHTDASH_API_KEY;
+    const baseUrl = import.meta.env?.VITE_LIGHTDASH_URL ??
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        globalThis.process?.env?.LIGHTDASH_URL;
+    const projectUuid = import.meta.env?.VITE_LIGHTDASH_PROJECT_UUID ??
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        globalThis.process?.env?.LIGHTDASH_PROJECT_UUID;
+    if (!apiKey || !baseUrl || !projectUuid)
+        return null;
+    // Auto-enable proxy when running on a different origin (dev server)
+    const useProxy = typeof window !== 'undefined' &&
+        window.location.origin !== new URL(baseUrl).origin;
+    return { apiKey, baseUrl, projectUuid, useProxy };
+}
+/**
+ * Create a Lightdash client.
+ *
+ * With no args, reads from env vars:
+ *   const lightdash = createClient()
+ *
+ * With explicit config (used when token comes from parent frame):
+ *   const lightdash = createClient({ apiKey, baseUrl, projectUuid })
+ */
+export function createClient(config) {
+    const resolved = config ?? configFromEnv();
+    if (!resolved) {
+        throw new Error('Missing Lightdash client config. Either pass { apiKey, baseUrl, projectUuid } ' +
+            'or set env vars: VITE_LIGHTDASH_API_KEY, VITE_LIGHTDASH_URL, VITE_LIGHTDASH_PROJECT_UUID');
+    }
+    return new LightdashClient(resolved);
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createClient, LightdashClient } from './client';
+export { useLightdash } from './useLightdash';
+export { LightdashProvider } from './LightdashProvider';
+export type { Filter, FilterOperator, FilterValue, LightdashClientConfig, LightdashUser, Row, Sort, UnitOfTime, } from './types';

package/dist/index.js

@@ -0,0 +1,6 @@
+// Client
+export { createClient, LightdashClient } from './client';
+// React hook
+export { useLightdash } from './useLightdash';
+// Provider
+export { LightdashProvider } from './LightdashProvider';

package/dist/query.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Chainable query builder.
+ *
+ * Usage:
+ *   lightdash
+ *     .model('orders')
+ *     .dimensions(['customer_segment', 'order_date'])
+ *     .metrics(['total_revenue', 'order_count'])
+ *     .filters([{ field: 'order_date', operator: 'inThePast', value: 90, unit: 'days' }])
+ *     .sorts([{ field: 'total_revenue', direction: 'desc' }])
+ *     .limit(100)
+ *
+ * The builder is immutable -- each method returns a new instance.
+ */
+import type { Filter, InternalFilterDefinition, QueryDefinition, Sort } from './types';
+export declare class QueryBuilder {
+    private readonly _explore;
+    private readonly _dimensions;
+    private readonly _metrics;
+    private readonly _filters;
+    private readonly _sorts;
+    private readonly _limit;
+    constructor(explore: string, dimensions?: string[], metrics?: string[], filters?: InternalFilterDefinition[], sorts?: {
+        fieldId: string;
+        descending: boolean;
+    }[], limit?: number);
+    /** Set dimension fields (GROUP BY columns) */
+    dimensions(fields: string[]): QueryBuilder;
+    /** Set metric fields (aggregations) */
+    metrics(fields: string[]): QueryBuilder;
+    /** Add filters */
+    filters(filters: Filter[]): QueryBuilder;
+    /** Add sorts */
+    sorts(sorts: Sort[]): QueryBuilder;
+    /** Set the maximum number of rows to return (default: 500) */
+    limit(n: number): QueryBuilder;
+    /** Convert to a plain QueryDefinition object */
+    build(): QueryDefinition;
+}

package/dist/query.js

@@ -0,0 +1,76 @@
+/**
+ * Chainable query builder.
+ *
+ * Usage:
+ *   lightdash
+ *     .model('orders')
+ *     .dimensions(['customer_segment', 'order_date'])
+ *     .metrics(['total_revenue', 'order_count'])
+ *     .filters([{ field: 'order_date', operator: 'inThePast', value: 90, unit: 'days' }])
+ *     .sorts([{ field: 'total_revenue', direction: 'desc' }])
+ *     .limit(100)
+ *
+ * The builder is immutable -- each method returns a new instance.
+ */
+export class QueryBuilder {
+    constructor(explore, dimensions = [], metrics = [], filters = [], sorts = [], limit = 500) {
+        this._explore = explore;
+        this._dimensions = dimensions;
+        this._metrics = metrics;
+        this._filters = filters;
+        this._sorts = sorts;
+        this._limit = limit;
+    }
+    /** Set dimension fields (GROUP BY columns) */
+    dimensions(fields) {
+        return new QueryBuilder(this._explore, [...this._dimensions, ...fields], this._metrics, this._filters, this._sorts, this._limit);
+    }
+    /** Set metric fields (aggregations) */
+    metrics(fields) {
+        return new QueryBuilder(this._explore, this._dimensions, [...this._metrics, ...fields], this._filters, this._sorts, this._limit);
+    }
+    /** Add filters */
+    filters(filters) {
+        const converted = filters.map((f) => {
+            const values = [];
+            if (f.value !== undefined) {
+                if (Array.isArray(f.value)) {
+                    values.push(...f.value);
+                }
+                else {
+                    values.push(f.value);
+                }
+            }
+            return {
+                fieldId: f.field,
+                operator: f.operator,
+                values,
+                settings: f.unit ? { unitOfTime: f.unit } : null,
+            };
+        });
+        return new QueryBuilder(this._explore, this._dimensions, this._metrics, [...this._filters, ...converted], this._sorts, this._limit);
+    }
+    /** Add sorts */
+    sorts(sorts) {
+        const converted = sorts.map((s) => ({
+            fieldId: s.field,
+            descending: s.direction === 'desc',
+        }));
+        return new QueryBuilder(this._explore, this._dimensions, this._metrics, this._filters, [...this._sorts, ...converted], this._limit);
+    }
+    /** Set the maximum number of rows to return (default: 500) */
+    limit(n) {
+        return new QueryBuilder(this._explore, this._dimensions, this._metrics, this._filters, this._sorts, n);
+    }
+    /** Convert to a plain QueryDefinition object */
+    build() {
+        return {
+            exploreName: this._explore,
+            dimensions: this._dimensions,
+            metrics: this._metrics,
+            filters: this._filters,
+            sorts: this._sorts,
+            limit: this._limit,
+        };
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Core types for the Lightdash SDK.
+ */
+export type UnitOfTime = 'days' | 'weeks' | 'months' | 'quarters' | 'years';
+export type FilterValue = string | number | boolean;
+export type FilterOperator = 'equals' | 'notEquals' | 'greaterThan' | 'greaterThanOrEqual' | 'lessThan' | 'lessThanOrEqual' | 'isNull' | 'notNull' | 'startsWith' | 'endsWith' | 'include' | 'doesNotInclude' | 'inThePast' | 'notInThePast' | 'inTheNext' | 'inTheCurrent' | 'notInTheCurrent' | 'inBetween' | 'notInBetween';
+export type Filter = {
+    field: string;
+    operator: FilterOperator;
+    value?: FilterValue | FilterValue[];
+    unit?: UnitOfTime;
+};
+export type Sort = {
+    field: string;
+    direction: 'asc' | 'desc';
+};
+export type InternalFilterDefinition = {
+    fieldId: string;
+    operator: string;
+    values: FilterValue[];
+    settings: {
+        unitOfTime: UnitOfTime;
+    } | null;
+};
+export type QueryDefinition = {
+    exploreName: string;
+    dimensions: string[];
+    metrics: string[];
+    filters: InternalFilterDefinition[];
+    sorts: {
+        fieldId: string;
+        descending: boolean;
+    }[];
+    limit: number;
+};
+export type ColumnType = 'string' | 'number' | 'date' | 'timestamp' | 'boolean';
+export type Column = {
+    name: string;
+    label: string;
+    type: ColumnType;
+};
+export type Row = Record<string, string | number | boolean | null>;
+export type FormatFunction = (row: Row, fieldId: string) => string;
+export type QueryResult = {
+    rows: Row[];
+    columns: Column[];
+    format: FormatFunction;
+};
+export type LightdashClientConfig = {
+    /** Lightdash instance URL */
+    baseUrl: string;
+    /** Project UUID */
+    projectUuid: string;
+    /** API key (PAT or scoped token) */
+    apiKey: string;
+    /** Use relative /api paths instead of baseUrl (for dev proxy setups) */
+    useProxy?: boolean;
+};
+export type LightdashUser = {
+    name: string;
+    email: string;
+    role: string;
+    orgId: string;
+    attributes: Record<string, string>;
+};
+export type Transport = {
+    executeQuery: (query: QueryDefinition) => Promise<QueryResult>;
+    getUser: () => Promise<LightdashUser>;
+};

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Core types for the Lightdash SDK.
+ */
+export {};

package/dist/useLightdash.d.ts

@@ -0,0 +1,28 @@
+/**
+ * React hook for executing a Lightdash query.
+ *
+ * Usage:
+ *   const { data, loading, error } = useLightdash(
+ *     lightdash
+ *       .model('orders')
+ *       .metrics(['total_revenue'])
+ *       .dimensions(['customer_segment'])
+ *   )
+ *
+ *   // data is an array of flat objects:
+ *   // [{ customer_segment: 'Enterprise', total_revenue: 124000 }]
+ */
+import type { QueryBuilder } from './query';
+import type { Row } from './types';
+type UseLightdashResult = {
+    /** Result rows as flat objects. Numbers are numbers, strings are strings. */
+    data: Row[];
+    /** True while the query is executing */
+    loading: boolean;
+    /** Error if the query failed, null otherwise */
+    error: Error | null;
+    /** Re-run the query */
+    refetch: () => void;
+};
+export declare function useLightdash(query: QueryBuilder): UseLightdashResult;
+export {};

package/dist/useLightdash.js

@@ -0,0 +1,52 @@
+/**
+ * React hook for executing a Lightdash query.
+ *
+ * Usage:
+ *   const { data, loading, error } = useLightdash(
+ *     lightdash
+ *       .model('orders')
+ *       .metrics(['total_revenue'])
+ *       .dimensions(['customer_segment'])
+ *   )
+ *
+ *   // data is an array of flat objects:
+ *   // [{ customer_segment: 'Enterprise', total_revenue: 124000 }]
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { useTransport } from './LightdashProvider';
+export function useLightdash(query) {
+    const transport = useTransport();
+    const [data, setData] = useState([]);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const [fetchCount, setFetchCount] = useState(0);
+    const queryKey = useMemo(() => JSON.stringify(query.build()), [query]);
+    const refetch = useCallback(() => {
+        setFetchCount((c) => c + 1);
+    }, []);
+    useEffect(() => {
+        let cancelled = false;
+        setLoading(true);
+        setError(null);
+        const definition = query.build();
+        transport
+            .executeQuery(definition)
+            .then((res) => {
+            if (!cancelled) {
+                setData(res.rows);
+                setLoading(false);
+            }
+        })
+            .catch((err) => {
+            if (!cancelled) {
+                setError(err instanceof Error ? err : new Error(String(err)));
+                setLoading(false);
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+        // queryKey tracks query identity. query is intentionally omitted.
+    }, [queryKey, transport, fetchCount]); // eslint-disable-line
+    return { data, loading, error, refetch };
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@lightdash/query-sdk",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "SDK for building custom data apps against the Lightdash semantic layer",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "react": "^18.x || ^19.x"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.2",
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src/",
+    "format": "oxfmt ./src --check",
+    "fix-format": "oxfmt ./src",
+    "release": "pnpm publish --no-git-checks --access public"
+  }
+}