@lightdash/query-sdk 0.2675.3 → 0.2676.0

package/dist/apiTransport.d.ts

@@ -7,5 +7,20 @@
  * 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;
+import type { Column, LightdashClientConfig, Transport } from './types';
+/**
+ * A function that performs HTTP requests and returns parsed JSON results.
+ * The default implementation uses `Authorization: ApiKey` header.
+ * Supply a custom adapter to use session cookies or other auth mechanisms.
+ */
+export type FetchAdapter = <T>(method: string, path: string, body?: unknown) => Promise<T>;
+export declare function mapColumnType(type: string): Column['type'];
+/**
+ * Creates a transport that executes queries via the Lightdash REST API.
+ *
+ * @param config - Client configuration (projectUuid is required; apiKey/baseUrl
+ *   are used by the default fetch adapter but ignored when a custom adapter is provided)
+ * @param adapter - Optional custom fetch adapter. When omitted, uses the default
+ *   adapter that authenticates via `Authorization: ApiKey` header.
+ */
+export declare function createApiTransport(config: LightdashClientConfig, adapter?: FetchAdapter): Transport;

package/dist/apiTransport.js

@@ -33,36 +33,36 @@ function buildApiFilters(filters) {
         },
     };
 }
-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;
+function createDefaultFetchAdapter(config) {
+    return async (method, path, body) => {
+        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}`);
         }
-        throw new Error(`Lightdash API error (${res.status}): ${message}`);
-    }
-    const json = (await res.json());
-    return json.results;
+        const json = (await res.json());
+        return json.results;
+    };
 }
-function mapColumnType(type) {
+export function mapColumnType(type) {
     if (/timestamp/i.test(type))
         return 'timestamp';
     if (/date/i.test(type))
@@ -73,7 +73,16 @@ function mapColumnType(type) {
         return 'boolean';
     return 'string';
 }
-export function createApiTransport(config) {
+/**
+ * Creates a transport that executes queries via the Lightdash REST API.
+ *
+ * @param config - Client configuration (projectUuid is required; apiKey/baseUrl
+ *   are used by the default fetch adapter but ignored when a custom adapter is provided)
+ * @param adapter - Optional custom fetch adapter. When omitted, uses the default
+ *   adapter that authenticates via `Authorization: ApiKey` header.
+ */
+export function createApiTransport(config, adapter) {
+    const fetchFn = adapter ?? createDefaultFetchAdapter(config);
     return {
         async executeQuery(query) {
             const table = query.exploreName;
@@ -103,12 +112,12 @@ export function createApiTransport(config) {
                     tableCalculations: [],
                 },
             };
-            const execResult = await apiFetch(config, 'POST', `/api/v2/projects/${config.projectUuid}/query/metric-query`, body);
+            const execResult = await fetchFn('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}`);
+                const pollResult = await fetchFn('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
@@ -192,7 +201,7 @@ export function createApiTransport(config) {
             throw new Error('Query timed out waiting for results');
         },
         async getUser() {
-            const user = await apiFetch(config, 'GET', '/api/v1/user');
+            const user = await fetchFn('GET', '/api/v1/user');
             return {
                 name: `${user.firstName} ${user.lastName}`.trim(),
                 email: user.email,

package/dist/client.d.ts

@@ -2,15 +2,7 @@
  * 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',
- *   })
+ *   const lightdash = createClient()  // auto-detects from environment
  */
 import { QueryBuilder } from './query';
 import type { LightdashClientConfig, LightdashUser, Transport } from './types';
@@ -20,17 +12,14 @@ export declare class LightdashClient {
     readonly auth: {
         getUser: () => Promise<LightdashUser>;
     };
-    constructor(config: LightdashClientConfig, transport?: Transport);
+    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()
+ * Create a Lightdash client. Auto-detects the transport from the environment:
  *
- * With explicit config (used when token comes from parent frame):
- *   const lightdash = createClient({ apiKey, baseUrl, projectUuid })
+ * 1. Hash fragment #transport=postMessage → postMessage bridge (Lightdash iframe)
+ * 2. Env vars (VITE_LIGHTDASH_* or LIGHTDASH_*) → direct API calls (local dev)
  */
-export declare function createClient(config?: LightdashClientConfig): LightdashClient;
+export declare function createClient(): LightdashClient;

package/dist/client.js

@@ -2,22 +2,15 @@
  * 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',
- *   })
+ *   const lightdash = createClient()  // auto-detects from environment
  */
 import { createApiTransport } from './apiTransport';
+import { createPostMessageTransport } from './postMessageTransport';
 import { QueryBuilder } from './query';
 export class LightdashClient {
     constructor(config, transport) {
         this.config = config;
-        this.transport = transport ?? createApiTransport(config);
+        this.transport = transport;
         this.auth = {
             getUser: () => this.transport.getUser(),
         };
@@ -31,14 +24,10 @@ export class LightdashClient {
  * 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
+ *   VITE_LIGHTDASH_API_KEY, VITE_LIGHTDASH_URL, VITE_LIGHTDASH_PROJECT_UUID
  *
  * Node/E2B (runtime):
- *   LIGHTDASH_API_KEY=pat_xxx
- *   LIGHTDASH_URL=https://app.lightdash.cloud
- *   LIGHTDASH_PROJECT_UUID=uuid
+ *   LIGHTDASH_API_KEY, LIGHTDASH_URL, LIGHTDASH_PROJECT_UUID
  */
 function configFromEnv() {
     // Vite statically replaces import.meta.env.VITE_X at build time.
@@ -60,19 +49,25 @@ function configFromEnv() {
     return { apiKey, baseUrl, projectUuid, useProxy };
 }
 /**
- * Create a Lightdash client.
- *
- * With no args, reads from env vars:
- *   const lightdash = createClient()
+ * Create a Lightdash client. Auto-detects the transport from the environment:
  *
- * With explicit config (used when token comes from parent frame):
- *   const lightdash = createClient({ apiKey, baseUrl, projectUuid })
+ * 1. Hash fragment #transport=postMessage → postMessage bridge (Lightdash iframe)
+ * 2. Env vars (VITE_LIGHTDASH_* or LIGHTDASH_*) → direct API calls (local dev)
  */
-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');
+export function createClient() {
+    // 1. postMessage transport (iframe hosted by Lightdash parent)
+    if (typeof window !== 'undefined' && window.location.hash) {
+        const params = new URLSearchParams(window.location.hash.replace(/^#/, ''));
+        if (params.get('transport') === 'postMessage') {
+            const projectUuid = params.get('projectUuid') ?? '';
+            return new LightdashClient({ apiKey: '', baseUrl: '', projectUuid }, createPostMessageTransport({ targetWindow: window.parent, projectUuid }));
+        }
+    }
+    // 2. Env vars → API transport
+    const config = configFromEnv();
+    if (!config) {
+        throw new Error('Missing Lightdash client config. ' +
+            'Set env vars: VITE_LIGHTDASH_API_KEY, VITE_LIGHTDASH_URL, VITE_LIGHTDASH_PROJECT_UUID');
     }
-    return new LightdashClient(resolved);
+    return new LightdashClient(config, createApiTransport(config));
 }

package/dist/index.d.ts

@@ -2,4 +2,7 @@ export { query } from './query';
 export { createClient, LightdashClient } from './client';
 export { useLightdash } from './useLightdash';
 export { LightdashProvider, useLightdashClient } from './LightdashProvider';
-export type { Column, Filter, FilterOperator, FilterValue, FormatFunction, LightdashClientConfig, LightdashUser, Row, Sort, UnitOfTime, } from './types';
+export { createApiTransport, type FetchAdapter } from './apiTransport';
+export { createPostMessageTransport } from './postMessageTransport';
+export type { Column, Filter, FilterOperator, FilterValue, FormatFunction, LightdashClientConfig, LightdashUser, QueryDefinition, QueryResult, Row, Sort, Transport, UnitOfTime, } from './types';
+export type { SdkFetchRequest, SdkFetchResponse, SdkReadyMessage, } from './postMessageTransport';

package/dist/index.js

@@ -6,3 +6,6 @@ export { createClient, LightdashClient } from './client';
 export { useLightdash } from './useLightdash';
 // Provider
 export { LightdashProvider, useLightdashClient } from './LightdashProvider';
+// Transports
+export { createApiTransport } from './apiTransport';
+export { createPostMessageTransport } from './postMessageTransport';

package/dist/postMessageTransport.d.ts

@@ -0,0 +1,41 @@
+/**
+ * postMessage transport — routes HTTP requests through the parent window
+ * via postMessage instead of calling the API directly.
+ *
+ * Used when the SDK runs inside a sandboxed iframe (sandbox="allow-scripts")
+ * that cannot make direct API calls. The parent receives fetch requests,
+ * executes them with its own session cookies, and sends the raw API
+ * response back. All query logic (field qualification, polling, result
+ * mapping) stays in the SDK's apiTransport.
+ */
+import type { Transport } from './types';
+export type SdkFetchRequest = {
+    type: 'lightdash:sdk:fetch';
+    id: string;
+    method: string;
+    path: string;
+    body?: unknown;
+};
+export type SdkFetchResponse = {
+    type: 'lightdash:sdk:fetch-response';
+    id: string;
+    result?: unknown;
+    error?: string;
+};
+export type SdkReadyMessage = {
+    type: 'lightdash:sdk:ready';
+};
+type PostMessageTransportConfig = {
+    targetWindow: Window;
+    projectUuid: string;
+    timeoutMs?: number;
+};
+/**
+ * Creates a Transport that routes all API calls through the parent window
+ * via postMessage. The parent acts as a fetch proxy using session cookies.
+ *
+ * All query logic (field qualification, polling, result mapping) is handled
+ * by the SDK's apiTransport — the postMessage layer is just the HTTP adapter.
+ */
+export declare function createPostMessageTransport(config: PostMessageTransportConfig): Transport;
+export {};

package/dist/postMessageTransport.js

@@ -0,0 +1,91 @@
+/**
+ * postMessage transport — routes HTTP requests through the parent window
+ * via postMessage instead of calling the API directly.
+ *
+ * Used when the SDK runs inside a sandboxed iframe (sandbox="allow-scripts")
+ * that cannot make direct API calls. The parent receives fetch requests,
+ * executes them with its own session cookies, and sends the raw API
+ * response back. All query logic (field qualification, polling, result
+ * mapping) stays in the SDK's apiTransport.
+ */
+import { createApiTransport } from './apiTransport';
+const DEFAULT_TIMEOUT_MS = 120000;
+const READY_TIMEOUT_MS = 10000;
+/**
+ * Creates a FetchAdapter that sends HTTP requests to the parent window
+ * via postMessage and waits for responses.
+ */
+function createPostMessageFetchAdapter(config) {
+    const { targetWindow, timeoutMs = DEFAULT_TIMEOUT_MS } = config;
+    const pending = new Map();
+    let readyResolve = null;
+    const readyPromise = new Promise((resolve) => {
+        readyResolve = resolve;
+    });
+    const readyTimer = setTimeout(() => {
+        readyResolve?.();
+    }, READY_TIMEOUT_MS);
+    window.addEventListener('message', (event) => {
+        const { data } = event;
+        if (!data || typeof data !== 'object' || typeof data.type !== 'string') {
+            return;
+        }
+        if (data.type === 'lightdash:sdk:ready') {
+            clearTimeout(readyTimer);
+            readyResolve?.();
+            readyResolve = null;
+            return;
+        }
+        if (data.type === 'lightdash:sdk:fetch-response') {
+            const msg = data;
+            const req = pending.get(msg.id);
+            if (!req)
+                return;
+            clearTimeout(req.timer);
+            pending.delete(msg.id);
+            if (msg.error) {
+                req.reject(new Error(msg.error));
+            }
+            else {
+                req.resolve(msg.result);
+            }
+        }
+    });
+    return async (method, path, body) => {
+        await readyPromise;
+        const id = crypto.randomUUID();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                pending.delete(id);
+                reject(new Error(`SDK fetch timed out after ${timeoutMs}ms: ${method} ${path}`));
+            }, timeoutMs);
+            pending.set(id, {
+                resolve: resolve,
+                reject,
+                timer,
+            });
+            const message = {
+                type: 'lightdash:sdk:fetch',
+                id,
+                method,
+                path,
+                body,
+            };
+            targetWindow.postMessage(message, '*');
+        });
+    };
+}
+/**
+ * Creates a Transport that routes all API calls through the parent window
+ * via postMessage. The parent acts as a fetch proxy using session cookies.
+ *
+ * All query logic (field qualification, polling, result mapping) is handled
+ * by the SDK's apiTransport — the postMessage layer is just the HTTP adapter.
+ */
+export function createPostMessageTransport(config) {
+    const adapter = createPostMessageFetchAdapter({
+        targetWindow: config.targetWindow,
+        timeoutMs: config.timeoutMs,
+    });
+    return createApiTransport({ apiKey: '', baseUrl: '', projectUuid: config.projectUuid }, adapter);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/query-sdk",
-  "version": "0.2675.3",
+  "version": "0.2676.0",
   "private": false,
   "type": "module",
   "description": "SDK for building custom data apps against the Lightdash semantic layer",