@lightdash/query-sdk 3.96.1 → 3.97.0

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'],

package/dist/generated/sdkVersion.d.ts

@@ -1 +1 @@
-export declare const SDK_VERSION = "3.96.1";
+export declare const SDK_VERSION = "3.97.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.97.0';

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/query-sdk",
-  "version": "3.96.1",
+  "version": "3.97.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.97.0",
     "@types/node": "22.13.1",
     "@types/react": "19.3.0",
     "@types/react-dom": "19.3.0",