@lightdash/query-sdk 0.3486.1 → 0.3487.0

package/dist/features.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Static registry of SDK capabilities, reported to the Lightdash host via the
+ * `lightdash:sdk:manifest` message so the host can detect apps built on an
+ * older SDK and offer an upgrade.
+ *
+ * Adding an SDK capability requires an entry here — features.test.ts fails if
+ * a `lightdash:*:available` message exists without a matching key. Keys are
+ * stable identifiers; label/description feed the host's "What's new" UI.
+ */
+export type SdkFeature = {
+    key: string;
+    label: string;
+    description: string;
+    /** Agent-facing note on the app-code wiring the feature needs before the
+     *  host can use it (absent = zero wiring; it activates automatically once
+     *  the bundle runs on a current SDK). Never rendered in user-facing UI. */
+    wiring?: string;
+};
+export declare const SDK_FEATURES: SdkFeature[];
+export declare const SDK_FEATURE_KEYS: string[];
+export declare const SDK_MANIFEST_MESSAGE_TYPE = "lightdash:sdk:manifest";
+/**
+ * Sent from the app iframe to the Lightdash host: once when the postMessage
+ * transport is created, and again each time the host announces
+ * `lightdash:sdk:ready` (covers either side mounting first).
+ */
+export type SdkManifestMessage = {
+    type: typeof SDK_MANIFEST_MESSAGE_TYPE;
+    sdkVersion: string;
+    features: string[];
+};

package/dist/features.js

@@ -0,0 +1,64 @@
+/**
+ * Static registry of SDK capabilities, reported to the Lightdash host via the
+ * `lightdash:sdk:manifest` message so the host can detect apps built on an
+ * older SDK and offer an upgrade.
+ *
+ * Adding an SDK capability requires an entry here — features.test.ts fails if
+ * a `lightdash:*:available` message exists without a matching key. Keys are
+ * stable identifiers; label/description feed the host's "What's new" UI.
+ */
+export const SDK_FEATURES = [
+    {
+        key: 'query',
+        label: 'Semantic layer queries',
+        description: 'Run metric and dimension queries against the Lightdash semantic layer.',
+    },
+    {
+        key: 'saved-chart',
+        label: 'Saved chart queries',
+        description: 'Fetch results from existing saved charts instead of ad-hoc queries.',
+    },
+    {
+        key: 'drill-down',
+        label: 'Drill-down helper',
+        description: 'Derive drill-down queries from a clicked result row to build explore-style interactions.',
+    },
+    {
+        key: 'inspect',
+        label: 'Element inspection',
+        description: 'Lets the Lightdash editor highlight and select app elements to reference them in prompts.',
+    },
+    {
+        key: 'lineage',
+        label: 'Inspect data',
+        description: 'Click any chart to trace it back to the query and fields behind it, from the Inspect data button in the editor.',
+        wiring: "Spread the `lineage` props returned by useLightdash onto each query-bound block's root element; without these stamps the host's Inspect data button stays disabled.",
+    },
+    {
+        key: 'screenshot',
+        label: 'In-app screenshots',
+        description: 'Lets the host rasterize the app to an image for thumbnails and scheduled deliveries.',
+    },
+    {
+        key: 'external-fetch',
+        label: 'External data fetch',
+        description: 'Fetch approved external HTTP data sources through the Lightdash proxy.',
+    },
+    {
+        key: 'gsheet-export',
+        label: 'Google Sheets export',
+        description: 'Export tabular results from the app straight to Google Sheets.',
+    },
+    {
+        key: 'url-state',
+        label: 'Shareable URL state',
+        description: 'Sync in-app state to the page URL so app views can be shared and restored.',
+    },
+    {
+        key: 'viz-context',
+        label: 'Dashboard visualization context',
+        description: 'Receive query context when app visualizations are embedded in dashboards.',
+    },
+];
+export const SDK_FEATURE_KEYS = SDK_FEATURES.map((f) => f.key);
+export const SDK_MANIFEST_MESSAGE_TYPE = 'lightdash:sdk:manifest';

package/dist/generated/sdkVersion.d.ts

@@ -0,0 +1 @@
+export declare const SDK_VERSION = "0.3487.0";

package/dist/generated/sdkVersion.js

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

package/dist/index.d.ts

@@ -6,6 +6,7 @@ export { useLightdash } from './useLightdash';
 export { LightdashProvider, useLightdashClient } from './LightdashProvider';
 export { createApiTransport, type FetchAdapter } from './apiTransport';
 export { createPostMessageTransport } from './postMessageTransport';
+export { SDK_FEATURES, SDK_FEATURE_KEYS, SDK_MANIFEST_MESSAGE_TYPE, type SdkFeature, type SdkManifestMessage, } from './features';
 export type { AdditionalMetric, Column, CustomDimension, DownloadResultsFileType, DownloadResultsLimit, DownloadResultsOptions, DownloadResultsResult, DownloadResultsValues, DownloadUnderlyingDataOptions, ExternalFetchMethod, ExternalFetchOptions, ExternalFetchResult, Filter, FilterOperator, FilterValue, FormatFunction, LightdashClientConfig, LightdashUser, MetricType, QueryDefinition, QueryResult, Row, Sort, TableCalculation, Transport, UnitOfTime, UnderlyingDataOptions, UnderlyingDataResult, } from './types';
 export type { SdkExternalFetchRequest, SdkExternalFetchResponse, SdkFetchRequest, SdkFetchResponse, SdkReadyMessage, SdkScreenshotAvailableMessage, SdkScreenshotRequest, SdkScreenshotResponse, SdkGsheetExportRequest, SdkGsheetExportResponse, SdkGsheetExportColumn, SdkGsheetExportColumnType, SdkGsheetExportRow, } from './postMessageTransport';
 export type { InspectAvailableMessage, InspectSelectedMessage, } from './inspector';

package/dist/index.js

@@ -12,6 +12,8 @@ export { LightdashProvider, useLightdashClient } from './LightdashProvider';
 // Transports
 export { createApiTransport } from './apiTransport';
 export { createPostMessageTransport } from './postMessageTransport';
+// Feature manifest (also exported via the "./features" subpath for hosts)
+export { SDK_FEATURES, SDK_FEATURE_KEYS, SDK_MANIFEST_MESSAGE_TYPE, } from './features';
 // Google Sheets export (data apps)
 export { exportToSheets } from './exportToSheets';
 // Data app viz render context (host-pushed rows + field mapping)

package/dist/manifest.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Announce this bundle's SDK capabilities to the host: immediately, and again
+ * whenever the host posts `lightdash:sdk:ready` — whichever side mounts first,
+ * the host ends up with a manifest. The host dedupes repeats.
+ *
+ * One listener per bundle: the manifest is module-constant, so re-creating the
+ * transport re-posts instead of stacking duplicate listeners. Returns a
+ * cleanup that unregisters the listener.
+ */
+export declare function announceSdkManifest(targetWindow: Window): () => void;

package/dist/manifest.js

@@ -0,0 +1,43 @@
+import { SDK_FEATURE_KEYS, SDK_MANIFEST_MESSAGE_TYPE, } from './features';
+import { SDK_VERSION } from './generated/sdkVersion';
+let activeCleanup = null;
+/**
+ * Announce this bundle's SDK capabilities to the host: immediately, and again
+ * whenever the host posts `lightdash:sdk:ready` — whichever side mounts first,
+ * the host ends up with a manifest. The host dedupes repeats.
+ *
+ * One listener per bundle: the manifest is module-constant, so re-creating the
+ * transport re-posts instead of stacking duplicate listeners. Returns a
+ * cleanup that unregisters the listener.
+ */
+export function announceSdkManifest(targetWindow) {
+    if (typeof window === 'undefined')
+        return () => { };
+    const message = {
+        type: SDK_MANIFEST_MESSAGE_TYPE,
+        sdkVersion: SDK_VERSION,
+        features: SDK_FEATURE_KEYS,
+    };
+    // Bundles are served from the host page's own origin, and location.origin
+    // is URL-derived so it survives the sandboxed (opaque-origin) iframe.
+    const { origin } = window.location;
+    const targetOrigin = origin && origin !== 'null' ? origin : '*';
+    const post = () => targetWindow.postMessage(message, targetOrigin);
+    activeCleanup?.();
+    const handler = (event) => {
+        if (event.source !== targetWindow)
+            return;
+        const type = event.data?.type;
+        if (type === 'lightdash:sdk:ready')
+            post();
+    };
+    window.addEventListener('message', handler);
+    const cleanup = () => {
+        window.removeEventListener('message', handler);
+        if (activeCleanup === cleanup)
+            activeCleanup = null;
+    };
+    activeCleanup = cleanup;
+    post();
+    return cleanup;
+}

package/dist/postMessageTransport.js

@@ -9,6 +9,7 @@
  * mapping) stays in the SDK's apiTransport.
  */
 import { createApiTransport } from './apiTransport';
+import { announceSdkManifest } from './manifest';
 const DEFAULT_TIMEOUT_MS = 120000;
 const READY_TIMEOUT_MS = 10000;
 /**
@@ -162,6 +163,8 @@ function createPostMessageExternalFetch(config) {
  * by the SDK's apiTransport — the postMessage layer is just the HTTP adapter.
  */
 export function createPostMessageTransport(config) {
+    // Report this bundle's SDK capabilities so the host can offer upgrades.
+    announceSdkManifest(config.targetWindow);
     const adapter = createPostMessageFetchAdapter({
         targetWindow: config.targetWindow,
         timeoutMs: config.timeoutMs,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/query-sdk",
-  "version": "0.3486.1",
+  "version": "0.3487.0",
   "private": false,
   "type": "module",
   "description": "SDK for building custom data apps against the Lightdash semantic layer",
@@ -19,12 +19,17 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./features": {
+      "types": "./dist/features.d.ts",
+      "import": "./dist/features.js"
     }
   },
   "peerDependencies": {
     "react": "^18.x || ^19.x"
   },
   "devDependencies": {
+    "@types/node": "22.13.1",
     "@types/react": "19.2.2",
     "jsdom": "26.1.0",
     "typescript": "npm:@typescript/typescript6@6.0.1",
@@ -32,11 +37,13 @@
     "vitest": "4.1.6"
   },
   "scripts": {
+    "prebuild": "node ./scripts/generateSdkVersion.mjs",
     "build": "tsc6 --project tsconfig.build.json",
     "build:fast": "tsc --project tsconfig.build.fast.json",
     "typecheck": "tsc6 --noEmit",
     "typecheck:fast": "tsc --project tsconfig.fast.json --noEmit",
     "lint": "eslint src/",
+    "pretest": "node ./scripts/generateSdkVersion.mjs",
     "test": "vitest run",
     "format": "oxfmt ./src --check",
     "fix-format": "oxfmt ./src",