@lightdash/query-sdk 3.96.1 → 3.98.0

package/dist/apiTransport.d.ts

@@ -8,6 +8,7 @@
  *    → returns results when status is 'ready'
  */
 import type { Column, LightdashClientConfig, Transport } from './types';
+import { type SpaceChartsResult } from './types';
 /**
  * A function that performs HTTP requests and returns parsed JSON results.
  * The default implementation uses `Authorization: ApiKey` header.
@@ -24,10 +25,32 @@ export declare const createFieldQualifier: (exploreName: string, baseTable: stri
 export type ExploreBaseTableResolver = (exploreName: string) => Promise<string | null>;
 export type ApiTransportOptions = {
     resolveExploreBaseTable: ExploreBaseTableResolver | null;
+    /** Omitted/null = the transport reports the capability unavailable. */
+    listSpaceCharts?: SpaceChartsResolver | null;
 };
 export declare const createApiExploreBaseTableResolver: (fetchFn: FetchAdapter, projectUuid: string) => ExploreBaseTableResolver;
 /** Asks the host (app bridge or CLI preview proxy) via its virtual route. */
 export declare const createHostExploreBaseTableResolver: (fetchFn: FetchAdapter) => ExploreBaseTableResolver;
+/** Lists the saved charts the viewer can see in a space (slug or uuid). */
+export type SpaceChartsResolver = (space: string) => Promise<SpaceChartsResult>;
+/**
+ * Thrown when the transport has the capability but the running host does not
+ * (a current SDK bundle on an older Lightdash). `useSpaceCharts` maps it to
+ * `available: false` instead of an error, so galleries hide cleanly.
+ */
+export declare class SpaceChartsUnsupportedError extends Error {
+    constructor();
+}
+/** Normalize an untrusted body into a `SpaceChartsResult`. */
+export declare const normalizeSpaceChartsResult: (value: unknown) => SpaceChartsResult;
+/** Asks the host (app bridge or CLI preview proxy) via its virtual route. */
+export declare const createHostSpaceChartsResolver: (fetchFn: FetchAdapter) => SpaceChartsResolver;
+/**
+ * Resolves against the real API (local dev with a PAT): the spaces list to
+ * match the slug/uuid, then the space detail for its chart summaries — the
+ * same two calls the host makes when answering the virtual route.
+ */
+export declare const createApiSpaceChartsResolver: (fetchFn: FetchAdapter, projectUuid: string) => SpaceChartsResolver;
 /**
  * Thrown for a non-2xx response. `status` lets hosts tell a recoverable
  * 429 (rate limited, retry later) from a real failure.

package/dist/apiTransport.js

@@ -8,7 +8,7 @@
  *    → returns results when status is 'ready'
  */
 import { AppStateError } from './appState';
-import { VIZ_DRILL_DOWN_PATH, VIZ_POINT_MENU_PATH, VIZ_UNDERLYING_DATA_OPEN_PATH, VIZ_UNDERLYING_DATA_PATH, VIZ_SUBTOTALS_PATH, EXPLORE_BASE_TABLE_PATH, } from './types';
+import { VIZ_DRILL_DOWN_PATH, VIZ_POINT_MENU_PATH, VIZ_UNDERLYING_DATA_OPEN_PATH, VIZ_UNDERLYING_DATA_PATH, VIZ_SUBTOTALS_PATH, EXPLORE_BASE_TABLE_PATH, SPACE_CHARTS_PATH, } from './types';
 // Mirrors the explorer's `useInfiniteQueryResults` polling rhythm so the
 // SDK behaves like a normal Lightdash chart: 500-row pages, exponential
 // backoff starting at 250ms, capped at 1000ms.
@@ -98,6 +98,92 @@ export const createHostExploreBaseTableResolver = (fetchFn) => async (exploreNam
     const result = await fetchFn('POST', EXPLORE_BASE_TABLE_PATH, body);
     return toBaseTable(result?.baseTable);
 };
+/**
+ * Thrown when the transport has the capability but the running host does not
+ * (a current SDK bundle on an older Lightdash). `useSpaceCharts` maps it to
+ * `available: false` instead of an error, so galleries hide cleanly.
+ */
+export class SpaceChartsUnsupportedError extends Error {
+    constructor() {
+        super('Space charts listing is not supported by this Lightdash host');
+        this.name = 'SpaceChartsUnsupportedError';
+    }
+}
+const EMPTY_SPACE_CHARTS = { space: null, charts: [] };
+const toNullableString = (value) => typeof value === 'string' && value.length > 0 ? value : null;
+/** Normalize an untrusted body into a `SpaceChartsResult`. */
+export const normalizeSpaceChartsResult = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return EMPTY_SPACE_CHARTS;
+    const { space, charts } = value;
+    let spaceInfo = null;
+    if (typeof space === 'object' && space !== null) {
+        const { uuid, name, slug } = space;
+        if (typeof uuid === 'string' &&
+            typeof name === 'string' &&
+            typeof slug === 'string') {
+            spaceInfo = { uuid, name, slug };
+        }
+    }
+    const chartList = (Array.isArray(charts) ? charts : []).flatMap((chart) => {
+        if (typeof chart !== 'object' || chart === null)
+            return [];
+        const entry = chart;
+        if (typeof entry.uuid !== 'string' || typeof entry.name !== 'string') {
+            return [];
+        }
+        return [
+            {
+                uuid: entry.uuid,
+                name: entry.name,
+                description: toNullableString(entry.description),
+                chartKind: toNullableString(entry.chartKind),
+                slug: toNullableString(entry.slug),
+                updatedAt: toNullableString(entry.updatedAt),
+            },
+        ];
+    });
+    return { space: spaceInfo, charts: chartList };
+};
+/** Asks the host (app bridge or CLI preview proxy) via its virtual route. */
+export const createHostSpaceChartsResolver = (fetchFn) => async (space) => {
+    const body = { space };
+    const result = await fetchFn('POST', SPACE_CHARTS_PATH, body);
+    return normalizeSpaceChartsResult(result);
+};
+/**
+ * Resolves against the real API (local dev with a PAT): the spaces list to
+ * match the slug/uuid, then the space detail for its chart summaries — the
+ * same two calls the host makes when answering the virtual route.
+ */
+export const createApiSpaceChartsResolver = (fetchFn, projectUuid) => async (space) => {
+    try {
+        const spaces = await fetchFn('GET', `/api/v1/projects/${projectUuid}/spaces`);
+        const match = (Array.isArray(spaces) ? spaces : []).find((entry) => {
+            if (typeof entry !== 'object' || entry === null)
+                return false;
+            const { uuid, slug } = entry;
+            return uuid === space || slug === space;
+        });
+        if (typeof match?.uuid !== 'string')
+            return EMPTY_SPACE_CHARTS;
+        const detail = await fetchFn('GET', `/api/v1/projects/${projectUuid}/spaces/${match.uuid}`);
+        if (typeof detail !== 'object' || detail === null)
+            return EMPTY_SPACE_CHARTS;
+        return normalizeSpaceChartsResult({
+            space: detail,
+            charts: detail.queries,
+        });
+    }
+    catch (e) {
+        // Same face as the host route: no access answers like not found.
+        if (e instanceof LightdashApiError &&
+            (e.status === 403 || e.status === 404)) {
+            return EMPTY_SPACE_CHARTS;
+        }
+        throw e;
+    }
+};
 function buildUnderlyingDataFilters(query, row, qualify) {
     const sourceFilters = buildApiFilters(query.filters.map((f) => ({
         ...f,
@@ -564,14 +650,21 @@ export function createApiTransport(config, adapter, options) {
     // endpoint, so only the default adapter looks base tables up by default.
     // Behind a dev proxy (CLI preview) the proxy answers the host route.
     let defaultResolver = null;
+    let defaultSpaceCharts = null;
     if (adapter === undefined) {
         defaultResolver = config.useProxy
             ? createHostExploreBaseTableResolver(fetchFn)
             : createApiExploreBaseTableResolver(fetchFn, config.projectUuid);
+        defaultSpaceCharts = config.useProxy
+            ? createHostSpaceChartsResolver(fetchFn)
+            : createApiSpaceChartsResolver(fetchFn, config.projectUuid);
     }
     const resolveExploreBaseTable = options === undefined
         ? defaultResolver
         : options.resolveExploreBaseTable;
+    const listSpaceCharts = options === undefined
+        ? defaultSpaceCharts
+        : (options.listSpaceCharts ?? null);
     const baseTableByExplore = new Map();
     const getFieldQualifier = async (query) => {
         const { exploreName } = query;
@@ -879,5 +972,8 @@ export function createApiTransport(config, adapter, options) {
         async openVizPointMenu(intent) {
             return fetchFn('POST', VIZ_POINT_MENU_PATH, intent);
         },
+        // Left absent (not a thrower) when no resolver exists, so
+        // `useSpaceCharts().available` honestly reports the capability.
+        ...(listSpaceCharts ? { listSpaceCharts } : {}),
     };
 }

package/dist/features.js

@@ -169,6 +169,13 @@ export const SDK_FEATURES = [
         description: 'Author-written guidance for the AI analysis — language and formatting rules (e.g. British English, amounts in EUR) and a line or two of domain vocabulary — applied to every summary the app shows.',
         wiring: "Pass the guidance where the app renders its view-level analysis: useInsights({ instructions: '<guidance>' }), or the instructions prop on the shipped InsightsSummary component. One string per app; keep it to a few short sentences.",
     },
+    {
+        key: 'analysis-on-load',
+        appliesTo: ['data_app'],
+        label: 'AI analysis on load',
+        description: 'Run the AI analysis as soon as the app loads, without the viewer clicking Analyse. A stored analysis of the same rows is reused.',
+        wiring: 'Only when the user asks for it: set the analyseOnLoad prop on the shipped InsightsSummary component, or useInsights({ analyseOnLoad: true }) in a custom block. One value per app.',
+    },
     {
         key: 'ai-prompt',
         appliesTo: ['data_app'],
@@ -218,6 +225,13 @@ export const SDK_FEATURES = [
         description: "Result columns carry the semantic layer's url link patterns, so values with configured links render as links, matching dashboards.",
         wiring: 'In cell renderers (tables, underlying-data dialogs), call resolveColumnUrls({ column, row, columns, format }) and render the value as a link when it returns entries, styled visibly as a link.',
     },
+    {
+        key: 'space-charts',
+        appliesTo: ['data_app'],
+        label: 'List charts in a space',
+        description: 'List the saved charts in a Lightdash space at runtime, so chart galleries update as charts are saved — limited to spaces the viewer can already access.',
+        wiring: "Call useSpaceCharts('<space slug or uuid>') where the app needs the list, render from its charts array (uuid, name, description, chartKind), and pass chart.uuid to savedChart(...) to show one. Check available first — it stays false on hosts without the capability.",
+    },
 ];
 export const SDK_FEATURE_KEYS = SDK_FEATURES.map((f) => f.key);
 /**

package/dist/generated/sdkVersion.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "3.96.1";
+export declare const SDK_VERSION = "3.98.0";

package/dist/generated/sdkVersion.js

@@ -1,2 +1,2 @@
 // Generated by scripts/generateSdkVersion.mjs (prebuild) — do not edit.
-export const SDK_VERSION = '3.96.1';
+export const SDK_VERSION = '3.98.0';

package/dist/hostContext.d.ts

@@ -1,11 +1,23 @@
 /**
- * Identity the host rides on its `lightdash:sdk:ready` handshake: the app
- * uuid this bundle is deployed as. Absent for older hosts and for bundles run
- * outside Lightdash (CLI preview), where app-scoped host features stay off.
+ * Identity and capabilities the host rides on its `lightdash:sdk:ready`
+ * handshake: the app uuid this bundle is deployed as, and which negotiated
+ * host features exist (`spaceCharts`). Absent for older hosts and for
+ * bundles run outside Lightdash (CLI preview), where host-negotiated
+ * features stay off.
  */
 type HostContext = {
     appUuid: string | null;
+    /** Host answers the space-charts virtual route. False for older hosts. */
+    spaceCharts: boolean;
+    /** A ready handshake has been seen at all. */
+    ready: boolean;
 };
+/**
+ * Resolves once a ready handshake has been seen, or after `timeoutMs` —
+ * mirrors the fetch adapter's readiness gate so capability checks don't
+ * hang on hosts that never handshake.
+ */
+export declare function waitForHostContext(timeoutMs: number): Promise<HostContext>;
 /** Called by `createPostMessageTransport()`; one listener per bundle. */
 export declare function mountHostContext(targetWindow: Window): () => void;
 export declare function useHostAppUuid(): string | null;

package/dist/hostContext.js

@@ -1,18 +1,31 @@
 /**
- * Identity the host rides on its `lightdash:sdk:ready` handshake: the app
- * uuid this bundle is deployed as. Absent for older hosts and for bundles run
- * outside Lightdash (CLI preview), where app-scoped host features stay off.
+ * Identity and capabilities the host rides on its `lightdash:sdk:ready`
+ * handshake: the app uuid this bundle is deployed as, and which negotiated
+ * host features exist (`spaceCharts`). Absent for older hosts and for
+ * bundles run outside Lightdash (CLI preview), where host-negotiated
+ * features stay off.
  */
 import { useSyncExternalStore } from 'react';
 const SDK_READY_MESSAGE = 'lightdash:sdk:ready';
-const EMPTY_CONTEXT = { appUuid: null };
+const EMPTY_CONTEXT = {
+    appUuid: null,
+    spaceCharts: false,
+    ready: false,
+};
 let value = EMPTY_CONTEXT;
 const listeners = new Set();
+let readyResolvers = [];
 const set = (next) => {
-    if (next.appUuid === value.appUuid)
+    if (next.appUuid === value.appUuid &&
+        next.spaceCharts === value.spaceCharts &&
+        next.ready === value.ready)
         return;
     value = next;
     listeners.forEach((listener) => listener());
+    if (next.ready) {
+        readyResolvers.forEach((resolve) => resolve());
+        readyResolvers = [];
+    }
 };
 const subscribe = (listener) => {
     listeners.add(listener);
@@ -20,6 +33,22 @@ const subscribe = (listener) => {
         listeners.delete(listener);
     };
 };
+/**
+ * Resolves once a ready handshake has been seen, or after `timeoutMs` —
+ * mirrors the fetch adapter's readiness gate so capability checks don't
+ * hang on hosts that never handshake.
+ */
+export function waitForHostContext(timeoutMs) {
+    if (value.ready)
+        return Promise.resolve(value);
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => resolve(value), timeoutMs);
+        readyResolvers.push(() => {
+            clearTimeout(timer);
+            resolve(value);
+        });
+    });
+}
 let activeCleanup = null;
 /** Called by `createPostMessageTransport()`; one listener per bundle. */
 export function mountHostContext(targetWindow) {
@@ -33,6 +62,8 @@ export function mountHostContext(targetWindow) {
             return;
         set({
             appUuid: typeof data.appUuid === 'string' ? data.appUuid : null,
+            spaceCharts: data.spaceCharts === true,
+            ready: true,
         });
     };
     activeCleanup?.();
@@ -54,4 +85,5 @@ export function peekHostContext() {
 }
 export function resetHostContext() {
     value = EMPTY_CONTEXT;
+    readyResolvers = [];
 }

package/dist/index.d.ts

@@ -4,7 +4,7 @@ export { drillDown } from './drillDown';
 export { createClient, LightdashClient } from './client';
 export { useLightdash } from './useLightdash';
 export { LightdashProvider, useLightdashClient } from './LightdashProvider';
-export { createApiTransport, LightdashApiError, type FetchAdapter, } from './apiTransport';
+export { createApiTransport, LightdashApiError, SpaceChartsUnsupportedError, type FetchAdapter, } from './apiTransport';
 export { createPostMessageTransport } from './postMessageTransport';
 export { resolveColumnUrls, type ResolvedColumnUrl } from './columnUrls';
 export { SDK_FEATURES, SDK_FEATURE_KEYS, SDK_FIXES, SDK_FIX_KEYS, SDK_FEATURE_TARGETS, SDK_MANIFEST_MESSAGE_TYPE, type SdkFeature, type SdkFeatureTarget, type SdkFix, type SdkManifestMessage, } from './features';
@@ -28,6 +28,9 @@ export type { AppStateAuthor, AppStateErrorCode, AppStateErrorPayload, AppStateH
 export type { SdkAppStateOp, SdkAppStateRequest, SdkAppStateResponse, } from './postMessageTransport';
 export { useAiPrompt } from './aiPrompt';
 export type { AiPrompt, AiPromptOptions, AiPromptSource } from './aiPrompt';
+export { useSpaceCharts } from './spaceCharts';
+export type { SpaceCharts } from './spaceCharts';
+export type { SpaceChartsResult, SpaceChartSummary } from './types';
 export { useInsights } from './insights';
 export type { Insight, InsightInvestigation, InsightSeverity, InsightsPayload, InsightsStatus, QueryInsights, ViewInsights, ViewInsightsOptions, } from './insights';
 export { createGradientColorScale } from './gradientColorScale';

package/dist/index.js

@@ -10,7 +10,7 @@ export { useLightdash } from './useLightdash';
 // Provider
 export { LightdashProvider, useLightdashClient } from './LightdashProvider';
 // Transports
-export { createApiTransport, LightdashApiError, } from './apiTransport';
+export { createApiTransport, LightdashApiError, SpaceChartsUnsupportedError, } from './apiTransport';
 export { createPostMessageTransport } from './postMessageTransport';
 export { resolveColumnUrls } from './columnUrls';
 // Feature manifest (also exported via the "./features" subpath for hosts)
@@ -32,6 +32,8 @@ export { useUrlState } from './urlState';
 export { AppStateError, useAppState, useSharedAppState, matchesDefaultShape, } from './appState';
 // Free-form AI prompts over loaded results (data apps)
 export { useAiPrompt } from './aiPrompt';
+// List the saved charts the viewer can see in a space (data apps)
+export { useSpaceCharts } from './spaceCharts';
 // AI analysis pushed by the host (data apps)
 export { useInsights } from './insights';
 export { createGradientColorScale } from './gradientColorScale';

package/dist/insights.d.ts

@@ -69,6 +69,8 @@ export type InsightsRequestMessage = {
     /** Author guidance the host forwards to the analysis model, set via
      *  `useInsights({ instructions })`. One string per app. */
     instructions?: string;
+    /** Set via `useInsights({ analyseOnLoad })`; absent = not declared. */
+    analyseOnLoad?: boolean;
 };
 export type InsightAction = {
     action: 'analyse';
@@ -98,6 +100,8 @@ export declare const EMPTY_INSIGHTS: InsightsPayload;
 export declare const parseInsightsPayload: (value: unknown) => InsightsPayload | null;
 /** Module-internal (exported for tests); `useInsights({ instructions })` wraps it. */
 export declare const setInsightInstructions: (value: string | undefined) => void;
+/** Module-internal (exported for tests); `useInsights({ analyseOnLoad })` wraps it. */
+export declare const setInsightAnalyseOnLoad: (value: boolean | undefined) => void;
 /**
  * Listen for the host's analysis and ask for the current one now. Called by
  * `createClient()` on the postMessage transport. One listener per bundle.
@@ -119,6 +123,9 @@ export type ViewInsightsOptions = {
      *  line or two of domain vocabulary. One string per app (the last value
      *  set wins); the host caps its length. */
     instructions?: string;
+    /** Analyse the view as soon as its queries settle, without a click.
+     *  A stored analysis of the same rows is reused. One value per app. */
+    analyseOnLoad?: boolean;
 };
 export type ViewInsights = InsightsPayload & {
     /** Ask the host to analyse the current view (or re-analyse when stale). */
@@ -155,6 +162,7 @@ export declare function useHostAiAvailable(): boolean;
  *
  *   const view = useInsights();               // executive summary + every anomaly
  *   const view = useInsights({ instructions: 'Use British English.' });
+ *   const view = useInsights({ analyseOnLoad: true });
  *   const orders = useLightdash(ordersQuery);
  *   const insights = useInsights(orders);     // anomalies on this chart's rows
  *

package/dist/insights.js

@@ -128,12 +128,17 @@ let activeCleanup = null;
 let inUse = false;
 // App-wide author guidance for the analysis model; last writer wins.
 let authorInstructions = null;
+// App-wide analyse-on-load choice; null = not declared, last writer wins.
+let authorAnalyseOnLoad = null;
 const requestMessage = () => ({
     type: INSIGHTS_REQUEST_MESSAGE,
     ...(inUse ? { inUse: true } : {}),
     ...(authorInstructions !== null
         ? { instructions: authorInstructions }
         : {}),
+    ...(authorAnalyseOnLoad !== null
+        ? { analyseOnLoad: authorAnalyseOnLoad }
+        : {}),
 });
 const markInUse = () => {
     if (inUse)
@@ -149,6 +154,14 @@ export const setInsightInstructions = (value) => {
     authorInstructions = next;
     hostWindow?.postMessage(requestMessage(), '*');
 };
+/** Module-internal (exported for tests); `useInsights({ analyseOnLoad })` wraps it. */
+export const setInsightAnalyseOnLoad = (value) => {
+    const next = value ?? null;
+    if (next === authorAnalyseOnLoad)
+        return;
+    authorAnalyseOnLoad = next;
+    hostWindow?.postMessage(requestMessage(), '*');
+};
 const createStore = () => {
     let payload = EMPTY_INSIGHTS;
     const listeners = new Set();
@@ -304,6 +317,22 @@ export function useInsights(sourceOrOptions) {
         declaredInstructionsRef.current = true;
         setInsightInstructions(instructions);
     }, [instructions]);
+    const analyseOnLoad = source === undefined
+        ? sourceOrOptions
+            ?.analyseOnLoad
+        : undefined;
+    const declaredAnalyseOnLoadRef = useRef(false);
+    useEffect(() => {
+        if (analyseOnLoad === undefined) {
+            if (!declaredAnalyseOnLoadRef.current)
+                return;
+            declaredAnalyseOnLoadRef.current = false;
+            setInsightAnalyseOnLoad(undefined);
+            return;
+        }
+        declaredAnalyseOnLoadRef.current = true;
+        setInsightAnalyseOnLoad(analyseOnLoad);
+    }, [analyseOnLoad]);
     const payload = useInsightsPayload();
     const investigate = useCallback((anomalyId) => postInsightAction({ action: 'investigate', anomalyId }), []);
     const canContinue = payload.canContinue;
@@ -360,6 +389,7 @@ export function resetInsightsState() {
     hostWindow = null;
     inUse = false;
     authorInstructions = null;
+    authorAnalyseOnLoad = null;
     mounted.clear();
     flushScheduled = false;
 }

package/dist/postMessageTransport.js

@@ -8,10 +8,10 @@
  * response back. All query logic (field qualification, polling, result
  * mapping) stays in the SDK's apiTransport.
  */
-import { createApiTransport, createHostExploreBaseTableResolver, } from './apiTransport';
+import { createApiTransport, createHostExploreBaseTableResolver, createHostSpaceChartsResolver, SpaceChartsUnsupportedError, } from './apiTransport';
 import { AppStateError } from './appState';
 import { mountDeliveryRender } from './deliveryRender';
-import { mountHostContext } from './hostContext';
+import { mountHostContext, waitForHostContext } from './hostContext';
 import { announceSdkManifest } from './manifest';
 import { mountRuntimeErrorObserver } from './runtimeErrors';
 const DEFAULT_TIMEOUT_MS = 120000;
@@ -280,6 +280,17 @@ export function createPostMessageTransport(config) {
     });
     const httpTransport = createApiTransport({ apiKey: '', baseUrl: '', projectUuid: config.projectUuid }, adapter, {
         resolveExploreBaseTable: createHostExploreBaseTableResolver(adapter),
+        // Negotiated on the ready handshake: only hosts that announce
+        // `spaceCharts: true` answer the virtual route. On an older host
+        // the typed rejection makes `useSpaceCharts` report
+        // `available: false` instead of surfacing a blocked-route error.
+        listSpaceCharts: async (space) => {
+            const host = await waitForHostContext(READY_TIMEOUT_MS);
+            if (!host.spaceCharts) {
+                throw new SpaceChartsUnsupportedError();
+            }
+            return createHostSpaceChartsResolver(adapter)(space);
+        },
     });
     const externalFetch = createPostMessageExternalFetch({
         targetWindow: config.targetWindow,

package/dist/spaceCharts.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `useSpaceCharts('<space slug or uuid>')` — the saved charts the viewer can
+ * see in a space, resolved at runtime with the viewer's own credentials. The
+ * list reflects existing space permissions: a space the viewer can't access
+ * answers exactly like one that doesn't exist (`space: null`, no charts).
+ *
+ * Feed an entry's `uuid` into `savedChart(...)` to render it.
+ */
+import { type SpaceChartSummary } from './types';
+export type SpaceCharts = {
+    /** False on a transport or host without the capability. On an older
+     *  host this starts true and settles to false after the first lookup. */
+    available: boolean;
+    /** Null while loading, on error, or when the space isn't accessible. */
+    space: {
+        uuid: string;
+        name: string;
+        slug: string;
+    } | null;
+    charts: SpaceChartSummary[];
+    loading: boolean;
+    error: Error | null;
+    /** Re-fetch the list, e.g. after the viewer saved a chart elsewhere. */
+    refresh: () => void;
+};
+export declare function useSpaceCharts(space: string): SpaceCharts;

package/dist/spaceCharts.js

@@ -0,0 +1,82 @@
+/**
+ * `useSpaceCharts('<space slug or uuid>')` — the saved charts the viewer can
+ * see in a space, resolved at runtime with the viewer's own credentials. The
+ * list reflects existing space permissions: a space the viewer can't access
+ * answers exactly like one that doesn't exist (`space: null`, no charts).
+ *
+ * Feed an entry's `uuid` into `savedChart(...)` to render it.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useTransport } from './LightdashProvider';
+const EMPTY_RESULT = { space: null, charts: [] };
+// Instanceof is unreliable across the bundle boundary; match by name.
+const isUnsupportedError = (e) => e instanceof Error &&
+    (e.name === 'SpaceChartsUnsupportedError' ||
+        // Older mediators reject the unknown route instead of negotiating:
+        // the bridge with `Blocked: POST /__sdk/space-charts`, the CLI
+        // preview proxy with "... is not a data-app SDK route ...".
+        /\/__sdk\/space-charts/.test(e.message));
+export function useSpaceCharts(space) {
+    const transport = useTransport();
+    const listSpaceCharts = transport.listSpaceCharts;
+    // Hosts that predate the capability reject the first lookup with a
+    // typed/blocked error; that settles availability to false for good.
+    const [hostUnsupported, setHostUnsupported] = useState(false);
+    const available = listSpaceCharts !== undefined && !hostUnsupported;
+    const [result, setResult] = useState(EMPTY_RESULT);
+    const [loading, setLoading] = useState(available);
+    const [error, setError] = useState(null);
+    const [fetchCount, setFetchCount] = useState(0);
+    // Drops responses from superseded fetches (space change, refresh, unmount).
+    const fetchSeq = useRef(0);
+    useEffect(() => {
+        if (!listSpaceCharts || hostUnsupported || space.trim().length === 0) {
+            setResult(EMPTY_RESULT);
+            setLoading(false);
+            setError(space.trim().length === 0 && available
+                ? new Error('useSpaceCharts: pass a space slug or uuid')
+                : null);
+            return undefined;
+        }
+        fetchSeq.current += 1;
+        const seq = fetchSeq.current;
+        setLoading(true);
+        setError(null);
+        listSpaceCharts(space.trim())
+            .then((value) => {
+            if (fetchSeq.current !== seq)
+                return;
+            setResult(value);
+            setLoading(false);
+        })
+            .catch((e) => {
+            if (fetchSeq.current !== seq)
+                return;
+            setResult(EMPTY_RESULT);
+            if (isUnsupportedError(e)) {
+                // Not an error state: the host simply doesn't have the
+                // feature. `available` flips to false and stays there.
+                setHostUnsupported(true);
+                setError(null);
+            }
+            else {
+                setError(e instanceof Error ? e : new Error(String(e)));
+            }
+            setLoading(false);
+        });
+        return () => {
+            // Invalidate in-flight responses for the unmount/re-run.
+            if (fetchSeq.current === seq)
+                fetchSeq.current += 1;
+        };
+    }, [listSpaceCharts, hostUnsupported, space, fetchCount, available]);
+    const refresh = useCallback(() => setFetchCount((n) => n + 1), []);
+    return {
+        available,
+        space: result.space,
+        charts: result.charts,
+        loading,
+        error,
+        refresh,
+    };
+}

package/dist/types.d.ts

@@ -299,6 +299,36 @@ export type ExploreBaseTableRequest = {
 export type ExploreBaseTableResult = {
     baseTable: string | null;
 };
+/**
+ * Host-answered virtual route returning the saved charts in a space.
+ * Duplicated from `@lightdash/common` (`APP_SDK_SPACE_CHARTS_PATH`) — this
+ * package must not depend on common. The bridge and the CLI preview proxy
+ * answer it with the viewer's own credentials; the backend has no such route.
+ */
+export declare const SPACE_CHARTS_PATH = "/__sdk/space-charts";
+export type SpaceChartsRequest = {
+    space: string;
+};
+/** One saved chart in a space, as listed by `useSpaceCharts`. */
+export type SpaceChartSummary = {
+    uuid: string;
+    name: string;
+    description: string | null;
+    /** e.g. `line`, `vertical_bar`, `table` — null on older charts. */
+    chartKind: string | null;
+    slug: string | null;
+    /** ISO timestamp of the chart's last save. */
+    updatedAt: string | null;
+};
+export type SpaceChartsResult = {
+    /** Null when the space doesn't exist or the viewer can't access it. */
+    space: {
+        uuid: string;
+        name: string;
+        slug: string;
+    } | null;
+    charts: SpaceChartSummary[];
+};
 export type LightdashClientConfig = {
     /** Lightdash instance URL */
     baseUrl: string;
@@ -474,4 +504,10 @@ export type Transport = {
      * `useAiPrompt().available` is false when absent.
      */
     aiPrompt?: (request: AiPromptRequest) => Promise<AiPromptResult>;
+    /**
+     * List the saved charts the viewer can see in a space (by slug or uuid).
+     * Optional so custom transports predating the capability stay valid —
+     * `useSpaceCharts().available` is false when absent.
+     */
+    listSpaceCharts?: (space: string) => Promise<SpaceChartsResult>;
 };

package/dist/types.js

@@ -41,3 +41,10 @@ export const VIZ_POINT_MENU_PATH = '/__sdk/viz/point-menu';
  * the backend has no such route.
  */
 export const EXPLORE_BASE_TABLE_PATH = '/__sdk/explore-base-table';
+/**
+ * Host-answered virtual route returning the saved charts in a space.
+ * Duplicated from `@lightdash/common` (`APP_SDK_SPACE_CHARTS_PATH`) — this
+ * package must not depend on common. The bridge and the CLI preview proxy
+ * answer it with the viewer's own credentials; the backend has no such route.
+ */
+export const SPACE_CHARTS_PATH = '/__sdk/space-charts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/query-sdk",
-  "version": "3.96.1",
+  "version": "3.98.0",
   "private": false,
   "description": "SDK for building custom data apps against the Lightdash semantic layer",
   "license": "MIT",
@@ -26,7 +26,7 @@
     }
   },
   "devDependencies": {
-    "@lightdash/common": "3.96.1",
+    "@lightdash/common": "3.98.0",
     "@types/node": "22.13.1",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",