reveal-sdk-node-ai 1.2.1-rc.1 → 1.3.0

package/index.d.ts

@@ -80,6 +80,14 @@ export interface AIRequestJson {
     /** The stable engine intent that produced this call (e.g. 'generation-build-report'). */
     intent: string;
     userContext: AIUserContextJson | null;
+    /**
+     * Present only when a message has a stable prefix: one entry per message (same order as `messages`), the number of
+     * leading characters of its `content` (UTF-16 code units, as JavaScript's `length` counts) that stay the same from one
+     * request to the next (a prompt's instructions and schema), or null. A hint for services with explicit prompt caching,
+     * which can mark that prefix as a cache point; ignore it otherwise. Kept out of the messages, which can be passed to an
+     * LLM client as they are.
+     */
+    stablePrefixLengths?: (number | null)[];
 }
 
 /** What a custom AI provider callback returns (v2 contract). */
@@ -113,11 +121,21 @@ export interface AIUsageRecordJson {
     inputTokens?: number | null;
     outputTokens?: number | null;
     totalTokens?: number | null;
+    /** Tokens spent on internal reasoning; null when the provider reported none. */
+    reasoningTokens?: number | null;
+    /** Input tokens served from the provider's prompt cache; null when the provider reported none. */
+    cachedInputTokens?: number | null;
     durationMs: number;
     finishReason?: 'Stop' | 'Length' | 'ContentFilter' | 'Other' | null;
     succeeded: boolean;
     /** 'provider_error' | 'timeout' | 'cancelled' | 'denied' when succeeded is false. */
     errorCode?: string | null;
+    /** The stage of a multi-step feature (e.g. 'DefineWidgets' in dashboard generation); null outside one. */
+    stage?: string | null;
+    /** Within `stage`: 1 for its first call, 2 and up for repair calls. */
+    attempt?: number | null;
+    /** The top-level operation this call ran under, when it differs from `operationId` (e.g. datasource ranking during a generation). */
+    parentOperationId?: string | null;
 }
 
 /** What `quotaGate` receives before every gated AI call. The user's identity and any
@@ -192,7 +210,8 @@ export interface MetadataManagerCallbacks {
     getDatasourceList?: (userContext: any) => Promise<any[]>;
     getMetadata?: (userContext: any, datasourceId: string, datasourceItemId: string | null, database: string, tables: string[], currentModel?: string | null) => Promise<any>;
     getMetadataIndex?: (userContext: any, datasourceId: string, datasourceItemId?: string | null) => Promise<any>;
-    getTableSummaries?: (userContext: any, datasourceId: string, datasourceItemId: string | null, database: string, currentModel?: string | null) => Promise<Array<{ name: string; description?: string | null }>>;
+    /** `alias` (optional) is the friendly table name the AI is shown instead of `name`. */
+    getTableSummaries?: (userContext: any, datasourceId: string, datasourceItemId: string | null, database: string, currentModel?: string | null) => Promise<Array<{ name: string; alias?: string | null; description?: string | null }>>;
     deleteMetadata?: (userContext: any, datasourceId: string, datasourceItemId?: string | null) => Promise<void>;
     getProgress?: (userContext: any, datasourceId: string, datasourceItemId?: string | null) => Promise<any>;
     hasMetadata?: (userContext: any, datasourceId: string, datasourceItemId?: string | null) => Promise<boolean>;
@@ -202,21 +221,88 @@ export interface MetadataManagerCallbacks {
     upsertFieldOverride?: (userContext: any, datasourceId: string, datasourceItemId: string | null, database: string, table: string, fieldName: string, fieldOverride: any) => Promise<void>;
     deleteFieldOverride?: (userContext: any, datasourceId: string, datasourceItemId: string | null, database: string, table: string, fieldName: string) => Promise<boolean>;
     upsertTableDescription?: (userContext: any, datasourceId: string, datasourceItemId: string | null, database: string, table: string, description: string | null, appliesTo?: string[] | null) => Promise<void>;
-    getRuntimeOverrides?: (userContext: any, datasourceId?: string | null, datasourceItemId?: string | null) => Promise<any | null>;
+    /** The plugin passes the user context again as the first argument after `userContext` (`userContextArg`). */
+    getRuntimeOverrides?: (userContext: any, userContextArg: any, datasourceId?: string | null, datasourceItemId?: string | null) => Promise<any | null>;
     getFullMetadata?: (userContext: any, datasourceId: string, datasourceItemId?: string | null) => Promise<any | null>;
-    rankDatasourcesForPrompt?: (userContext: any, userPrompt: string, maxResults?: number) => Promise<any>;
+    /**
+     * Ranks the catalog datasources against a prompt. The dashboard generator uses it to shortlist the
+     * datasources a chat request without `datasourceId` is built from (see `RevealAIPluginOptions` for which
+     * datasources the AI may then see). Optional: when it is missing, the
+     * plugin ranks with the same built-in ranker as the C# SDK, reading this manager's
+     * `getDatasourceList`, `getMetadataIndex` and `getMetadata`. It calls `getMetadata` with no
+     * `currentModel`, so it ranks on what that handler returns for the request's user context
+     * (overrides and any model filtering included), and leaves out a datasource whose index is
+     * missing or fails to load. Implement it only to rank with your own logic; when it fails, the AI
+     * is shown every datasource instead. A stub that returns no candidates also leaves the AI with
+     * every datasource: delete it to get the built-in ranker. The plugin passes the user context
+     * again after `userPrompt` (`userContextArg`).
+     *
+     * Resolve to `{ candidates: [{ datasourceId, datasourceItemId?, score, rationale?, relevantTables? }] }`,
+     * or `{ candidates: [], error }` on failure:
+     * - `datasourceId` / `datasourceItemId`: the catalog entry's `Id` / `ItemId` exactly (omit the
+     *   item id when the entry has none); a candidate that matches no entry is ignored.
+     * - `score`: 0..1; the shortlist is ordered by it.
+     * - `relevantTables`: "database.table", with the real names as the metadata index lists them,
+     *   not their aliases (e.g. `'NorthwindCloud.dbo.Orders'`). The AI is shown each table's alias;
+     *   an entry without its database is shown as is.
+     */
+    rankDatasourcesForPrompt?: (userContext: any, userPrompt: string, userContextArg: any, maxResults: number) => Promise<any>;
+}
+
+/**
+ * One field (column) definition in the metadata catalog. Mirrors the C# `FieldSchema`.
+ * `Alias` is shown to the AI INSTEAD of `Name`; `expression` / `expressionType` / `dataType`
+ * define a virtual (calculated) field.
+ */
+export interface FieldSchemaJson {
+    Name: string;
+    Alias?: string | null;
+    Description?: string | null;
+    expression?: string | null;
+    expressionType?: 'CalculatedField' | 'PostCalculatedField';
+    dataType?: string | null;
+}
+
+/**
+ * One table (or cube) definition in the metadata catalog. Mirrors the C# `TableSchema`.
+ * `Alias` is the friendly name the AI is shown instead of `Name` (the SDK maps the AI's
+ * answer back to the real name).
+ */
+export interface TableSchemaJson {
+    Name: string;
+    Alias?: string | null;
+    Description?: string | null;
+    Fields?: FieldSchemaJson[] | null;
+}
+
+/**
+ * One database (or XMLA catalog) definition in the metadata catalog. Mirrors the C#
+ * `DatabaseSchema`. `Name` accepts a single name or an array of names sharing the same
+ * configuration; `Alias` / `Description` then apply to each of them. `DiscoveryMode`
+ * 'Restricted' exposes only the listed tables.
+ */
+export interface DatabaseSchemaJson {
+    Name: string | string[];
+    Alias?: string | null;
+    Description?: string | null;
+    DiscoveryMode?: 'Default' | 'Restricted';
+    Tables?: TableSchemaJson[] | null;
 }
 
 /**
  * One datasource definition in the metadata catalog. Property names match the C#
  * `DatasourceSchema` (PascalCase); `Provider` is a Reveal provider enum name (e.g.
- * 'SQLServer', 'PostgreSQL', 'MySQL', 'REST').
+ * 'SQLServer', 'PostgreSQL', 'MySQL', 'REST'). `Alias` is the friendly name the AI is
+ * shown instead of `Id` in ranking / selection prompts (useful when ids are opaque);
+ * `Description` is printed next to it.
  */
 export interface DatasourceSchemaJson {
     Id: string;
     ItemId?: string | null;
     Provider: string;
-    Databases?: any[] | null;
+    Alias?: string | null;
+    Description?: string | null;
+    Databases?: DatabaseSchemaJson[] | null;
 }
 
 /**
@@ -239,6 +325,46 @@ export type MetadataCatalogProviderCallback = (
     userContext?: any
 ) => MetadataCatalogJson | Promise<MetadataCatalogJson>;
 
+/**
+ * A single custom date filter rule declared by the host — a relative window such as "Next 7 Days"
+ * or "Last 90 Days". Mirrors the C# `AIDateFilterRule`. Only `Last` and `Next` relations are
+ * honored (other relations overlap the built-in options and are ignored).
+ */
+export interface AIDateFilterRuleJson {
+    /** The window's relation to today. Only `'Last'` and `'Next'` are honored. */
+    Relation: 'Last' | 'Next';
+    /** How many `Period`s the window spans (e.g. 7 for "Next 7 Days"). Must be positive. */
+    Count: number;
+    /** The unit of the window. */
+    Period: 'Day' | 'Week' | 'Month' | 'Quarter' | 'Semester' | 'Year';
+    /**
+     * Whether today is included in the window, or omitted for the default. Honored for `Last` rules,
+     * which include today by default, and for `Next` rules over `'Day'`, which start tomorrow by default
+     * (with true, "Next 7 Days" starts today instead). Ignored for other periods.
+     */
+    IncludeToday?: boolean | null;
+    /**
+     * Optional canonical name the AI uses to select this rule. When omitted, a stable name is
+     * derived from the relation, count and period (e.g. "Next7Days"). Names that collide with a
+     * built-in date option are ignored in favor of the built-in.
+     */
+    Name?: string | null;
+    /**
+     * Optional human-readable description surfaced to the AI (falls back to a generated phrase).
+     */
+    Description?: string | null;
+}
+
+/**
+ * Node.js-side implementation of IAIDateFilterProvider. Returns the host's custom date menu
+ * options so the AI can offer them alongside the built-ins when generating or editing dashboards.
+ * Invoked once per generation/edit with no arguments other than the request's user context (so the
+ * rules can vary per user/tenant). Return an empty array when there are none.
+ */
+export type DateFilterProviderCallback = (
+    userContext?: any
+) => AIDateFilterRuleJson[] | Promise<AIDateFilterRuleJson[]>;
+
 /**
  * Node.js-side implementation of IMetadataStorageProvider — the persistence layer the built-in
  * file-based MetadataManager reads and writes through. Implement the operations your host supports
@@ -247,6 +373,16 @@ export type MetadataCatalogProviderCallback = (
  * unchanged from `getById` (deserialized back into the requesting C# type). The first argument of
  * every handler is the request's user context, for multi-tenant scoping.
  *
+ * A handler may filter what that user sees, but the answer of `getById` and `list` must depend only
+ * on the id (or pattern) and the user context: within one dashboard generation or edit, each item
+ * and listing is fetched once for the request's user and the request's later reads reuse a copy of
+ * that answer. Nothing is reused across requests or users; a metadata write Reveal makes, from any
+ * request, makes running requests fetch again, and a change your application makes to the storage
+ * directly is seen from the next request. Writes are made under the system
+ * user context (`reveal-ai-metadata-user` by default), and some write back a document just read, so
+ * return unfiltered documents to it. The index document carries every table's alias and
+ * description; filter it like the per-table documents.
+ *
  * When this object is provided, the C# plugin replaces its default JSONMetadataStorageProvider with
  * MetadataStorageProvider, which proxies every call to these handlers. Independent of
  * `metadataManager` (which replaces the whole IMetadataManager and so bypasses storage entirely).
@@ -285,7 +421,8 @@ export interface Callbacks {
      * Observability export: receives one {@link AIUsageRecordJson} per AI call (success or
      * failure, foreground or background) — "save the usage log anywhere". One-way — the return
      * value is ignored and failures never affect AI calls. Not a billing seam: plan checks,
-     * budgets, and debiting tokens belong on `quotaGate`/`quotaSettle`.
+     * budgets, and debiting tokens belong on `quotaGate`/`quotaSettle`. The sink is not called
+     * within a request, so `userContext` is always null; the record's `userId` identifies the user.
      */
     usageSink?: (record: AIUsageRecordJson, userContext?: any) => void | Promise<void>;
     /**
@@ -301,8 +438,10 @@ export interface Callbacks {
      */
     quotaSettle?: (settlement: { context: AICallContextJson; usage: AIUsageRecordJson }, userContext?: any) => void | Promise<void>;
     /**
-     * Plan gating: return the subset of `candidateProfiles` this user may use. Malformed results
-     * or exceptions deny all profiles (fail closed); names outside the candidate set are ignored.
+     * Plan gating: return the subset of `candidateProfiles` this user may use. Called with every
+     * profile for the profile listing, and with just the requested profile to validate a request
+     * (leaving it out returns 403). Malformed results or exceptions deny all profiles (fail
+     * closed); names outside the candidate set are ignored.
      */
     profileAuthorizer?: (request: { user: AIUserContextJson | null; candidateProfiles: string[] }, userContext?: any) => string[] | Promise<string[]>;
     /**
@@ -323,6 +462,12 @@ export interface Callbacks {
      * — configure exactly one catalog source (the plugin throws at startup if both are set).
      */
     metadataCatalogProvider?: MetadataCatalogProviderCallback;
+    /**
+     * Node.js-side IAIDateFilterProvider implementation. Declares the host's custom date menu
+     * options ("Next 7 Days", "Last 90 Days") server-side so the AI recognizes them when generating
+     * or editing dashboards. Mirror the same rules into the client's `onDateFilterMenuOpening`.
+     */
+    dateFilterProvider?: DateFilterProviderCallback;
     /**
      * Node.js-side IMetadataStorageProvider implementation. Swaps the built-in file-based metadata
      * persistence for a custom backend (database, cloud storage, ...) while leaving the rest of the
@@ -331,6 +476,17 @@ export interface Callbacks {
     metadataStorageProvider?: MetadataStorageProviderCallbacks;
 }
 
+/**
+ * Options for the Reveal AI plugin.
+ *
+ * A chat request may omit `datasourceId`: the AI then picks one or more datasources from the catalog
+ * (`metadataCatalogFile`, or `getDatasourceList` of a `metadataManager` callback) and may mix and join them in
+ * one dashboard. The request comes from the browser client, so the server can't rely on it naming a datasource.
+ * The AI only considers the datasources whose metadata index the request's user can read: every metadata read
+ * gets the user context. A host that restricts datasources per user must therefore also filter its metadata
+ * per user (or tenant) in its metadata storage or manager callbacks, returning no index for the datasources a
+ * user can't use; then nothing about them reaches the AI.
+ */
 export interface RevealAIPluginOptions {
     /** Absolute path to AIPlugin.dll (defaults to the bundled native binaries). */
     assemblyPath?: string;

package/index.js

@@ -17,6 +17,27 @@ function wrapJsonCallback(handler) {
     };
 }
 
+/**
+ * The engine only receives the user's id from the SDK, so the hook payloads it sends carry
+ * `user.properties: null`. Fill them in from the user context the SDK resolved for the request
+ * (passed to every callback), so per-request claims are on `user.properties` as documented.
+ * Only done when that context is the payload's user: system calls carry the plugin's own user.
+ */
+function withUserProperties(payload, userContext) {
+    const user = payload?.user ?? payload?.context?.user;
+    const properties = userContext?.properties;
+    if (!user || user.properties != null || properties == null || user.userId !== userContext.userId) {
+        return payload;
+    }
+    user.properties = properties instanceof Map ? Object.fromEntries(properties) : properties;
+    return payload;
+}
+
+/** wrapJsonCallback for the hooks whose payload carries the user (gate, authorizer, resolver). */
+function wrapUserJsonCallback(handler) {
+    return wrapJsonCallback((payload, userContext) => handler(withUserProperties(payload, userContext), userContext));
+}
+
 /**
  * Same as wrapJsonCallback for one-way callbacks: the return value is ignored by the plugin.
  */
@@ -93,6 +114,7 @@ function withOptions(options = {}) {
             aiProvider,
             metadataManager: metadataManagerCallbacks,
             metadataCatalogProvider,
+            dateFilterProvider,
             metadataStorageProvider: metadataStorageProviderCallbacks,
             usageSink, quotaGate, quotaSettle, profileAuthorizer, connectionResolver,
             ...otherCallbacks
@@ -130,10 +152,12 @@ function withOptions(options = {}) {
         // v2 hook callbacks: always object-friendly (parsed payload in, plain value out). Their
         // presence is signaled to the plugin via has* flags.
         if (typeof usageSink === 'function') callbacks.usageSink = wrapOneWayJsonCallback(usageSink);
-        if (typeof quotaGate === 'function') callbacks.quotaGate = wrapJsonCallback(quotaGate);
-        if (typeof quotaSettle === 'function') callbacks.quotaSettle = wrapOneWayJsonCallback(quotaSettle);
-        if (typeof profileAuthorizer === 'function') callbacks.profileAuthorizer = wrapJsonCallback(profileAuthorizer);
-        if (typeof connectionResolver === 'function') callbacks.connectionResolver = wrapJsonCallback(connectionResolver);
+        if (typeof quotaGate === 'function') callbacks.quotaGate = wrapUserJsonCallback(quotaGate);
+        if (typeof quotaSettle === 'function') {
+            callbacks.quotaSettle = wrapOneWayJsonCallback((payload, userContext) => quotaSettle(withUserProperties(payload, userContext), userContext));
+        }
+        if (typeof profileAuthorizer === 'function') callbacks.profileAuthorizer = wrapUserJsonCallback(profileAuthorizer);
+        if (typeof connectionResolver === 'function') callbacks.connectionResolver = wrapUserJsonCallback(connectionResolver);
         parameters.hasUsageSink = typeof usageSink === 'function';
         parameters.hasQuotaGate = typeof quotaGate === 'function';
         parameters.hasQuotaSettle = typeof quotaSettle === 'function';
@@ -159,6 +183,22 @@ function withOptions(options = {}) {
             parameters.hasMetadataCatalogProvider = true;
         }
 
+        // IAIDateFilterProvider bridge — a single getFilterRules() method. When
+        // provided, the C# plugin registers DateFilterProvider, which proxies
+        // IAIDateFilterProvider.GetFilterRulesAsync() to this handler so the AI can
+        // offer the host's custom date menu options ("Next 7 Days", "Last 90 Days"). The payload
+        // carries no arguments, so only the userContext is forwarded; return the array of rules.
+        if (dateFilterProvider) {
+            if (typeof dateFilterProvider !== 'function') {
+                throw new Error('callbacks.dateFilterProvider must be a function returning the custom date filter rules (it may be sync or async)');
+            }
+            callbacks.dateFilterProvider = async (userContext, _message) => {
+                const rules = await dateFilterProvider(userContext);
+                return JSON.stringify(rules ?? []);
+            };
+            parameters.hasDateFilterProvider = true;
+        }
+
         // IMetadataManager bridge — dispatches by methodName from EndpointMethodCallModel.
         if (metadataManagerCallbacks) {
             if (typeof metadataManagerCallbacks !== 'object' || typeof metadataManagerCallbacks === 'function') {
@@ -166,7 +206,12 @@ function withOptions(options = {}) {
             }
 
             // Tell the C# side to use MetadataManagerProvider instead of the file-based MetadataManager.
-            parameters.metadataManager = Object.assign({}, parameters.metadataManager, { useNodeProvider: true });
+            // Without a rankDatasourcesForPrompt handler, the C# side ranks datasources with the
+            // built-in ranker over this manager's getDatasourceList / getMetadataIndex / getMetadata.
+            parameters.metadataManager = Object.assign({}, parameters.metadataManager, {
+                useNodeProvider: true,
+                hostRanksDatasources: typeof metadataManagerCallbacks.rankDatasourcesForPrompt === 'function',
+            });
 
             callbacks.metadataManager = async (userContext, message) => {
                 let methodName, args;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reveal-sdk-node-ai",
-  "version": "1.2.1-rc.1",
+  "version": "1.3.0",
   "description": "Reveal SDK AI plugin for Node.js — adds AI capabilities to Reveal BI dashboards",
   "main": "index.js",
   "types": "index.d.ts",
@@ -23,6 +23,6 @@
     "node": ">=16.0.0"
   },
   "dependencies": {
-    "reveal-sdk-node": ">=2.2.0"
+    "reveal-sdk-node": ">=2.3.0"
   }
 }