@xpert-ai/plugin-analytics-data-xpert 0.1.0 → 0.1.2

package/README.md

@@ -1,8 +1,10 @@
 # data-xpert analytics provider
 
+The Live Dashboard Agent generates this provider’s Definition through `analytics_definition_connections` → `analytics_definition_inspect` → `analytics_definition_register`. Existing toolset/Integration credentials stay in their original configuration entries. Settings → Analytics is for viewing, correction and version management; users do not fill internal IDs. See [the authoring guide](../../../../docs/analytics-providers.md#automatic-definition-generation).
+Configure API URL and audience in Settings → Integrations → data-xpert Analytics. The Agent selects this integration from the authorized catalog.
+
 System plugin `@xpert-ai/plugin-analytics-data-xpert`; provider `data-xpert.ontology`, operation `action`, version 1.
 
-Contributes the data-xpert DataSource type through DataSourceType sync. Server configuration: baseUrl (including /api), audience, assistantCode, assistantXpertId, workspaceId. No database runner is required. Platform code has no ontology dependency.
 
 ```json
 {"resourceId":"datax-semantic-model-<published-model-id>","actionTypeCode":"sql.query_cube_slice","target":{"entityTypeCode":"semantic_cube","entityRef":"<published-model-id>::Sales"},"params":{"dimensions":["Region"],"measures":["Amount"],"filters":[{"field":"Region","op":"contains","value":"west"}],"limit":100},"parameterPaths":{"region":["filters","0","value"]}}

package/dist/index.js

@@ -5,7 +5,7 @@ const node_path_1 = require("node:path");
 const plugin_1 = require("./lib/plugin");
 const packageJson = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(__dirname, '../package.json'), 'utf8'));
 const plugin = {
-    meta: { name: packageJson.name, version: packageJson.version, category: 'database', displayName: 'data-xpert Analytics', description: 'data-xpert Analytics', author: 'XpertAI', level: packageJson.xpert.plugin.level, artifactNamespace: packageJson.xpert.plugin.artifactNamespace },
+    meta: { name: packageJson.name, version: packageJson.version, category: 'tools', displayName: 'data-xpert Analytics', description: 'data-xpert Analytics', author: 'XpertAI', level: packageJson.xpert.plugin.level, artifactNamespace: packageJson.xpert.plugin.artifactNamespace },
     register: () => ({ module: plugin_1.AnalyticsDataXpertPlugin })
 };
 exports.default = plugin;

package/dist/lib/client.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod/v3';
+import type { AnalyticsBinding, AnalyticsValue, JSONValue, AnalyticsDiscoveryResult } from '@xpert-ai/contracts';
+import { type AnalyticsProviderContext, type AnalyticsProviderResult, type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
+export type DataXpertClientContext = Pick<AnalyticsProviderContext, 'actor' | 'options' | 'signal' | 'deadlineAt' | 'maxRows'>;
+/** Native Action arguments stay plugin-owned; the host only interprets Dataset/Binding. */
+export declare const dataXpertPayloadSchema: z.ZodObject<{
+    resourceId: z.ZodString;
+    actionTypeCode: z.ZodString;
+    target: z.ZodEffects<z.ZodObject<{
+        entityId: z.ZodOptional<z.ZodString>;
+        entityTypeCode: z.ZodOptional<z.ZodString>;
+        entityRef: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        entityTypeCode?: string | undefined;
+        entityRef?: string | undefined;
+        entityId?: string | undefined;
+    }, {
+        entityTypeCode?: string | undefined;
+        entityRef?: string | undefined;
+        entityId?: string | undefined;
+    }>, {
+        entityTypeCode?: string | undefined;
+        entityRef?: string | undefined;
+        entityId?: string | undefined;
+    }, {
+        entityTypeCode?: string | undefined;
+        entityRef?: string | undefined;
+        entityId?: string | undefined;
+    }>;
+    params: z.ZodRecord<z.ZodString, z.ZodType<JSONValue, z.ZodTypeDef, JSONValue>>;
+    parameterPaths: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+}, "strict", z.ZodTypeAny, {
+    params: Record<string, JSONValue>;
+    resourceId: string;
+    target: {
+        entityTypeCode?: string | undefined;
+        entityRef?: string | undefined;
+        entityId?: string | undefined;
+    };
+    actionTypeCode: string;
+    parameterPaths: Record<string, string[]>;
+}, {
+    params: Record<string, JSONValue>;
+    resourceId: string;
+    target: {
+        entityTypeCode?: string | undefined;
+        entityRef?: string | undefined;
+        entityId?: string | undefined;
+    };
+    actionTypeCode: string;
+    parameterPaths?: Record<string, string[]> | undefined;
+}>;
+export declare class DataXpertAnalyticsClient {
+    private readonly runtime;
+    constructor(runtime: RuntimeCapabilityRegistry);
+    discover(request: JSONValue, context: DataXpertClientContext): Promise<AnalyticsDiscoveryResult>;
+    private request;
+    execute(binding: AnalyticsBinding, parameters: Record<string, AnalyticsValue>, context: DataXpertClientContext): Promise<AnalyticsProviderResult>;
+}
+/** Typed paths replace whole parameter values, never splice text into SQL/MDX/OData. */
+export declare function bindParameters(params: Record<string, JSONValue>, paths: Record<string, string[]>, parameters: Record<string, AnalyticsValue>): Record<string, JSONValue>;

package/dist/lib/client.js

@@ -0,0 +1,154 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataXpertAnalyticsClient = exports.dataXpertPayloadSchema = void 0;
+exports.bindParameters = bindParameters;
+const common_1 = require("@nestjs/common");
+const v3_1 = require("zod/v3");
+const discovery_1 = require("./discovery");
+const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
+const scalar = v3_1.z.union([v3_1.z.string(), v3_1.z.number().finite(), v3_1.z.boolean(), v3_1.z.null()]);
+const json = v3_1.z.lazy(() => v3_1.z.union([scalar, v3_1.z.array(json), v3_1.z.record(json)]));
+/** Native Action arguments stay plugin-owned; the host only interprets Dataset/Binding. */
+exports.dataXpertPayloadSchema = v3_1.z.object({
+    resourceId: v3_1.z.string().min(1).max(160), actionTypeCode: v3_1.z.string().min(1).max(160),
+    target: v3_1.z.object({
+        entityId: v3_1.z.string().trim().min(1).max(256).optional(),
+        entityTypeCode: v3_1.z.string().trim().min(1).max(256).optional(),
+        entityRef: v3_1.z.string().trim().min(1).max(512).optional()
+    }).strict().refine(target => Boolean(target.entityId || target.entityRef), 'Target reference is required'),
+    params: v3_1.z.record(json),
+    parameterPaths: v3_1.z.record(v3_1.z.array(v3_1.z.string().min(1)).min(1).max(8)).default({})
+}).strict();
+/** Trusted DataSource configuration; never merge it with payloads, controls or discovery requests. */
+const optionsSchema = v3_1.z.object({
+    baseUrl: v3_1.z.string().url(), audience: v3_1.z.string().min(1),
+    assistantCode: v3_1.z.string().min(1), assistantXpertId: v3_1.z.string().uuid(), workspaceId: v3_1.z.string().uuid()
+}).strict();
+const responseSchema = v3_1.z.object({
+    effect: v3_1.z.object({ version: v3_1.z.literal(2), kind: v3_1.z.enum(['rows', 'series', 'entity']),
+        columns: v3_1.z.array(v3_1.z.object({ key: v3_1.z.string(), semanticRef: v3_1.z.string().optional() })),
+        rows: v3_1.z.array(v3_1.z.record(scalar)),
+        summary: v3_1.z.object({ rowCount: v3_1.z.number().int().nonnegative(), returnedRowCount: v3_1.z.number().int().nonnegative(), truncated: v3_1.z.boolean() }) }),
+    fetchedAt: v3_1.z.string().datetime(), executionId: v3_1.z.string(), auditRef: v3_1.z.string(), fromCache: v3_1.z.literal(false)
+});
+let DataXpertAnalyticsClient = class DataXpertAnalyticsClient {
+    constructor(runtime) {
+        this.runtime = runtime;
+    }
+    async discover(request, context) {
+        const empty = request && typeof request === 'object' && !Array.isArray(request) && Object.keys(request).length === 0;
+        const parsed = discovery_1.dataXpertDiscoveryRequestSchema.parse(empty ? { kind: 'resources' } : request);
+        const response = await this.request('discover', context, { request: parsed });
+        const result = v3_1.z.object({ items: v3_1.z.array(v3_1.z.unknown()),
+            nextRequest: json.optional() }).strict().parse(await boundedJson(response));
+        return plugin_sdk_1.analyticsDiscoveryResultSchema.parse({ ...result, queryContract: discovery_1.dataXpertQueryContract });
+    }
+    async request(endpoint, context, body) {
+        context.signal.throwIfAborted();
+        const options = optionsSchema.parse(context.options);
+        const base = new URL(options.baseUrl);
+        if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash)
+            throw new Error('DATAX_URL_INVALID');
+        const token = await this.runtime.require(plugin_sdk_1.ActorTokenRuntimeFactoryCapability).createScopedApi(context.actor).getToken({ audience: options.audience });
+        context.signal.throwIfAborted();
+        const response = await fetch(`${base.href.replace(/\/$/, '')}/agent-workbench/analytics/${endpoint}`, {
+            method: 'POST', redirect: 'error', signal: context.signal,
+            headers: { Authorization: `Bearer ${token.token}`, 'Content-Type': 'application/json', 'organization-id': context.actor.organizationId },
+            body: JSON.stringify({ assistant: { code: options.assistantCode, xpertId: options.assistantXpertId, workspaceId: options.workspaceId }, ...body })
+        });
+        if (!response.ok) {
+            // Do not retain an unconsumed upstream error stream or expose its potentially sensitive body.
+            await response.body?.cancel().catch(() => undefined);
+            throw new Error(`DATAX_QUERY_HTTP_${response.status}`);
+        }
+        return response;
+    }
+    async execute(binding, parameters, context) {
+        const payload = exports.dataXpertPayloadSchema.parse(binding.payload);
+        const response = await this.request('query', context, {
+            binding: { id: binding.id, resourceId: payload.resourceId, actionTypeCode: payload.actionTypeCode, target: payload.target,
+                params: bindParameters(payload.params, payload.parameterPaths, parameters) }, maxRows: context.maxRows
+        });
+        const result = responseSchema.parse(await boundedJson(response));
+        return { columns: result.effect.columns, rows: result.effect.rows,
+            completeness: { returnedRows: result.effect.summary.returnedRowCount, totalRows: result.effect.summary.rowCount,
+                totalAccuracy: result.effect.summary.truncated ? 'unknown' : 'exact', scope: result.effect.summary.truncated ? 'page' : 'full_query_result',
+                truncated: result.effect.summary.truncated }, sourceFetchedAt: result.fetchedAt,
+            upstreamExecutionId: result.executionId, auditRef: result.auditRef };
+    }
+};
+exports.DataXpertAnalyticsClient = DataXpertAnalyticsClient;
+exports.DataXpertAnalyticsClient = DataXpertAnalyticsClient = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(plugin_sdk_1.XPERT_RUNTIME_CAPABILITIES_TOKEN)),
+    __metadata("design:paramtypes", [Object])
+], DataXpertAnalyticsClient);
+/** Typed paths replace whole parameter values, never splice text into SQL/MDX/OData. */
+function bindParameters(params, paths, parameters) {
+    const result = structuredClone(params);
+    if (Object.keys(parameters).some((name) => !Object.hasOwn(paths, name)) || Object.keys(paths).some((name) => !Object.hasOwn(parameters, name)))
+        throw new Error('DATAX_PARAMETER_MAPPING_INVALID');
+    if (new Set(Object.values(paths).map((path) => JSON.stringify(path))).size !== Object.keys(paths).length)
+        throw new Error('DATAX_PARAMETER_MAPPING_INVALID');
+    for (const [name, path] of Object.entries(paths)) {
+        let current = result;
+        for (const [index, key] of path.entries()) {
+            if (['__proto__', 'prototype', 'constructor'].includes(key) || !current || typeof current !== 'object' || !Object.hasOwn(current, key))
+                throw new common_1.BadRequestException('DATAX_PARAMETER_PATH_INVALID: parameterPaths are relative to params. Omit the leading params segment and target an existing scalar, for example ["slicers","1","value"].');
+            if (Array.isArray(current)) {
+                if (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= current.length)
+                    throw new Error('DATAX_PARAMETER_PATH_INVALID');
+                const position = Number(key);
+                if (index === path.length - 1) {
+                    if (current[position] !== null && typeof current[position] === 'object')
+                        throw new Error('DATAX_PARAMETER_PATH_NOT_SCALAR');
+                    current[position] = parameters[name];
+                }
+                else
+                    current = current[position];
+            }
+            else if (index === path.length - 1) {
+                if (current[key] !== null && typeof current[key] === 'object')
+                    throw new Error('DATAX_PARAMETER_PATH_NOT_SCALAR');
+                current[key] = parameters[name];
+            }
+            else
+                current = current[key];
+        }
+    }
+    return result;
+}
+async function boundedJson(response) {
+    if (!response.body)
+        throw new Error('DATAX_EMPTY_RESPONSE');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            size += chunk.value.byteLength;
+            if (size > 2_500_000)
+                throw new Error('DATAX_RESPONSE_TOO_LARGE');
+            chunks.push(chunk.value);
+        }
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    finally {
+        await reader.cancel();
+    }
+}

package/dist/lib/integration.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod/v3';
+import type { IIntegration } from '@xpert-ai/contracts';
+import { type IntegrationStrategy, type TIntegrationStrategyParams } from '@xpert-ai/plugin-sdk';
+export declare const DATA_XPERT_INTEGRATION = "analytics-data-xpert";
+export declare const connectionSchema: z.ZodObject<{
+    baseUrl: z.ZodEffects<z.ZodString, string, string>;
+    audience: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    baseUrl: string;
+    audience: string;
+}, {
+    baseUrl: string;
+    audience: string;
+}>;
+export declare class DataXpertAnalyticsIntegration implements IntegrationStrategy<z.output<typeof connectionSchema>> {
+    readonly meta: {
+        name: string;
+        label: {
+            en_US: string;
+            zh_Hans: string;
+        };
+        icon: {
+            type: "font";
+            value: string;
+        };
+        schema: {
+            type: "object";
+            properties: {
+                baseUrl: {
+                    type: "string";
+                    title: string;
+                };
+                audience: {
+                    type: "string";
+                    title: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    prepareConfig(config: z.output<typeof connectionSchema>): {
+        baseUrl: string;
+        audience: string;
+    };
+    validateConfig(config: z.output<typeof connectionSchema>): Promise<void>;
+    execute(_integration: IIntegration<z.output<typeof connectionSchema>>, _payload: TIntegrationStrategyParams): Promise<never>;
+}

package/dist/lib/integration.js

@@ -0,0 +1,29 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DataXpertAnalyticsIntegration = exports.connectionSchema = exports.DATA_XPERT_INTEGRATION = void 0;
+const v3_1 = require("zod/v3");
+const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
+exports.DATA_XPERT_INTEGRATION = 'analytics-data-xpert';
+exports.connectionSchema = v3_1.z.object({
+    baseUrl: v3_1.z.string().url().refine(value => { const url = new URL(value); return ['http:', 'https:'].includes(url.protocol) && !url.username && !url.password && !url.search && !url.hash; }),
+    audience: v3_1.z.string().min(1)
+}).strict();
+let DataXpertAnalyticsIntegration = class DataXpertAnalyticsIntegration {
+    constructor() {
+        this.meta = { name: exports.DATA_XPERT_INTEGRATION, label: { en_US: 'data-xpert Analytics', zh_Hans: 'data-xpert 分析服务' }, icon: { type: 'font', value: 'ri-bar-chart-box-line' },
+            schema: { type: 'object', properties: { baseUrl: { type: 'string', title: 'API URL' }, audience: { type: 'string', title: 'OIDC audience' } }, required: ['baseUrl', 'audience'] } };
+    }
+    prepareConfig(config) { return exports.connectionSchema.parse(config); }
+    async validateConfig(config) { exports.connectionSchema.parse(config); }
+    async execute(_integration, _payload) { throw new Error('DATAX_USE_ANALYTICS_RUNTIME'); }
+};
+exports.DataXpertAnalyticsIntegration = DataXpertAnalyticsIntegration;
+exports.DataXpertAnalyticsIntegration = DataXpertAnalyticsIntegration = __decorate([
+    (0, plugin_sdk_1.IntegrationStrategyKey)(exports.DATA_XPERT_INTEGRATION)
+], DataXpertAnalyticsIntegration);

package/dist/lib/plugin.js

@@ -7,11 +7,14 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AnalyticsDataXpertPlugin = void 0;
+const client_1 = require("./client");
 const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
 const provider_1 = require("./provider");
+const cqrs_1 = require("@nestjs/cqrs");
+const integration_1 = require("./integration");
 let AnalyticsDataXpertPlugin = class AnalyticsDataXpertPlugin {
 };
 exports.AnalyticsDataXpertPlugin = AnalyticsDataXpertPlugin;
 exports.AnalyticsDataXpertPlugin = AnalyticsDataXpertPlugin = __decorate([
-    (0, plugin_sdk_1.XpertServerPlugin)({ providers: [provider_1.DataXpertAnalyticsProvider] })
+    (0, plugin_sdk_1.XpertServerPlugin)({ imports: [cqrs_1.CqrsModule], providers: [provider_1.DataXpertAnalyticsProvider, client_1.DataXpertAnalyticsClient, integration_1.DataXpertAnalyticsIntegration] })
 ], AnalyticsDataXpertPlugin);

package/dist/lib/provider.d.ts

@@ -1,61 +1,61 @@
-import { z } from 'zod/v3';
-import type { AnalyticsBinding, AnalyticsProviderDescriptor, AnalyticsValue, JSONValue, AnalyticsDiscoveryResult } from '@xpert-ai/contracts';
-import { type AnalyticsQueryProvider, type AnalyticsProviderContext, type AnalyticsProviderResult, type RuntimeCapabilityRegistry } from '@xpert-ai/plugin-sdk';
-/** Native Action arguments stay plugin-owned; the host only interprets Dataset/Binding. */
-export declare const dataXpertPayloadSchema: z.ZodObject<{
-    resourceId: z.ZodString;
-    actionTypeCode: z.ZodString;
-    target: z.ZodEffects<z.ZodObject<{
-        entityId: z.ZodOptional<z.ZodString>;
-        entityTypeCode: z.ZodOptional<z.ZodString>;
-        entityRef: z.ZodOptional<z.ZodString>;
-    }, "strict", z.ZodTypeAny, {
-        entityTypeCode?: string | undefined;
-        entityRef?: string | undefined;
-        entityId?: string | undefined;
-    }, {
-        entityTypeCode?: string | undefined;
-        entityRef?: string | undefined;
-        entityId?: string | undefined;
-    }>, {
-        entityTypeCode?: string | undefined;
-        entityRef?: string | undefined;
-        entityId?: string | undefined;
-    }, {
-        entityTypeCode?: string | undefined;
-        entityRef?: string | undefined;
-        entityId?: string | undefined;
-    }>;
-    params: z.ZodRecord<z.ZodString, z.ZodType<JSONValue, z.ZodTypeDef, JSONValue>>;
-    parameterPaths: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
-}, "strict", z.ZodTypeAny, {
-    params: Record<string, JSONValue>;
-    resourceId: string;
-    target: {
-        entityTypeCode?: string | undefined;
-        entityRef?: string | undefined;
-        entityId?: string | undefined;
+import { QueryBus } from '@nestjs/cqrs';
+import type { AnalyticsBinding, AnalyticsValue, JSONValue } from '@xpert-ai/contracts';
+import { type AnalyticsQueryProvider, type AnalyticsProviderContext, type AnalyticsDefinitionAuthoring, type DataSourceActor } from '@xpert-ai/plugin-sdk';
+import { DataXpertAnalyticsClient } from './client';
+export declare class DataXpertAnalyticsProvider implements AnalyticsQueryProvider {
+    private readonly engine;
+    private readonly queries;
+    constructor(engine: DataXpertAnalyticsClient, queries: QueryBus);
+    readonly descriptor: {
+        id: string;
+        name: string;
+        sourceKinds: ["definition"];
+        operations: {
+            name: string;
+            contractVersion: number;
+            readOnly: true;
+        }[];
     };
-    actionTypeCode: string;
-    parameterPaths: Record<string, string[]>;
-}, {
-    params: Record<string, JSONValue>;
-    resourceId: string;
-    target: {
-        entityTypeCode?: string | undefined;
-        entityRef?: string | undefined;
-        entityId?: string | undefined;
+    readonly authoring: AnalyticsDefinitionAuthoring;
+    private authoringContext;
+    readonly configuration: {
+        kind: "definition";
+        connection: "integration";
+        schema: {
+            type: string;
+            properties: {
+                integrationId: {
+                    type: string;
+                    format: string;
+                    title: string;
+                };
+                assistantCode: {
+                    type: string;
+                    title: string;
+                };
+                assistantXpertId: {
+                    type: string;
+                    format: string;
+                    title: string;
+                };
+                workspaceId: {
+                    type: string;
+                    format: string;
+                    title: string;
+                };
+            };
+            required: string[];
+            additionalProperties: boolean;
+        };
     };
-    actionTypeCode: string;
-    parameterPaths?: Record<string, string[]> | undefined;
-}>;
-export declare class DataXpertAnalyticsProvider implements AnalyticsQueryProvider {
-    private readonly runtime;
-    readonly descriptor: AnalyticsProviderDescriptor;
-    constructor(runtime: RuntimeCapabilityRegistry);
-    discover(request: JSONValue, context: AnalyticsProviderContext): Promise<AnalyticsDiscoveryResult>;
-    private request;
-    execute(binding: AnalyticsBinding, parameters: Record<string, AnalyticsValue>, context: AnalyticsProviderContext): Promise<AnalyticsProviderResult>;
+    validateConfiguration(options: Record<string, JSONValue>, actor: DataSourceActor): Promise<{
+        assistantCode: string;
+        assistantXpertId: string;
+        workspaceId: string;
+        integrationId: string;
+    }>;
+    private connection;
+    private run;
+    discover(request: JSONValue, context: AnalyticsProviderContext): Promise<import("@xpert-ai/contracts").AnalyticsDiscoveryResult>;
+    execute(binding: AnalyticsBinding, parameters: Record<string, AnalyticsValue>, context: AnalyticsProviderContext): Promise<import("@xpert-ai/plugin-sdk").AnalyticsProviderResult>;
 }
-/** Typed paths replace whole parameter values, never splice text into SQL/MDX/OData. */
-export declare function bindParameters(params: Record<string, JSONValue>, paths: Record<string, string[]>, parameters: Record<string, AnalyticsValue>): Record<string, JSONValue>;

package/dist/lib/provider.js

@@ -8,157 +8,70 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-var __param = (this && this.__param) || function (paramIndex, decorator) {
-    return function (target, key) { decorator(target, key, paramIndex); }
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DataXpertAnalyticsProvider = exports.dataXpertPayloadSchema = void 0;
-exports.bindParameters = bindParameters;
-const common_1 = require("@nestjs/common");
+exports.DataXpertAnalyticsProvider = void 0;
+const cqrs_1 = require("@nestjs/cqrs");
 const v3_1 = require("zod/v3");
-const discovery_1 = require("./discovery");
 const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
-const scalar = v3_1.z.union([v3_1.z.string(), v3_1.z.number().finite(), v3_1.z.boolean(), v3_1.z.null()]);
-const json = v3_1.z.lazy(() => v3_1.z.union([scalar, v3_1.z.array(json), v3_1.z.record(json)]));
-/** Native Action arguments stay plugin-owned; the host only interprets Dataset/Binding. */
-exports.dataXpertPayloadSchema = v3_1.z.object({
-    resourceId: v3_1.z.string().min(1).max(160), actionTypeCode: v3_1.z.string().min(1).max(160),
-    target: v3_1.z.object({
-        entityId: v3_1.z.string().trim().min(1).max(256).optional(),
-        entityTypeCode: v3_1.z.string().trim().min(1).max(256).optional(),
-        entityRef: v3_1.z.string().trim().min(1).max(512).optional()
-    }).strict().refine(target => Boolean(target.entityId || target.entityRef), 'Target reference is required'),
-    params: v3_1.z.record(json),
-    parameterPaths: v3_1.z.record(v3_1.z.array(v3_1.z.string().min(1)).min(1).max(8)).default({})
-}).strict();
-/** Trusted DataSource configuration; never merge it with payloads, controls or discovery requests. */
-const optionsSchema = v3_1.z.object({
-    baseUrl: v3_1.z.string().url(), audience: v3_1.z.string().min(1),
-    assistantCode: v3_1.z.string().min(1), assistantXpertId: v3_1.z.string().uuid(), workspaceId: v3_1.z.string().uuid()
-}).strict();
-const responseSchema = v3_1.z.object({
-    effect: v3_1.z.object({ version: v3_1.z.literal(2), kind: v3_1.z.enum(['rows', 'series', 'entity']),
-        columns: v3_1.z.array(v3_1.z.object({ key: v3_1.z.string(), semanticRef: v3_1.z.string().optional() })),
-        rows: v3_1.z.array(v3_1.z.record(scalar)),
-        summary: v3_1.z.object({ rowCount: v3_1.z.number().int().nonnegative(), returnedRowCount: v3_1.z.number().int().nonnegative(), truncated: v3_1.z.boolean() }) }),
-    fetchedAt: v3_1.z.string().datetime(), executionId: v3_1.z.string(), auditRef: v3_1.z.string(), fromCache: v3_1.z.literal(false)
-});
+const client_1 = require("./client");
+const integration_1 = require("./integration");
+const optionsSchema = v3_1.z.object({ integrationId: v3_1.z.string().uuid(), assistantCode: v3_1.z.string().min(1), assistantXpertId: v3_1.z.string().uuid(), workspaceId: v3_1.z.string().uuid() }).strict();
 let DataXpertAnalyticsProvider = class DataXpertAnalyticsProvider {
-    constructor(runtime) {
-        this.runtime = runtime;
-        this.descriptor = {
-            id: 'data-xpert.ontology', name: 'data-xpert Ontology', dataSourceTypes: ['data-xpert'],
-            operations: [{ name: 'action', contractVersion: 1, readOnly: true }],
-            connectionType: { type: 'data-xpert', name: 'data-xpert', configuration: {
-                    type: 'object', properties: { baseUrl: { type: 'string', title: 'API URL' }, audience: { type: 'string', title: 'OIDC audience' },
-                        assistantCode: { type: 'string', title: 'Assistant code' }, assistantXpertId: { type: 'string', title: 'Assistant Xpert ID' },
-                        workspaceId: { type: 'string', title: 'Workspace ID' } },
-                    required: ['baseUrl', 'audience', 'assistantCode', 'assistantXpertId', 'workspaceId'], additionalProperties: false
-                } }
+    constructor(engine, queries) {
+        this.engine = engine;
+        this.queries = queries;
+        this.descriptor = { id: 'data-xpert.ontology', name: 'data-xpert Ontology', sourceKinds: ['definition'], operations: [{ name: 'action', contractVersion: 1, readOnly: true }] };
+        this.authoring = {
+            integrationProvider: integration_1.DATA_XPERT_INTEGRATION,
+            inspectSchema: { type: 'object', additionalProperties: true },
+            definitionSchema: { type: 'object', properties: {}, additionalProperties: false },
+            instructions: 'The system supplies integration and current Assistant identity. Inspect the authorized ontology, following nextRequest/inspectRequest. Register with definition {} then discover and preview the returned source. Do not ask the user for integration, workspace or Assistant IDs.',
+            inspect: (input, context) => this.run(this.authoringContext(context), resolved => this.engine.discover(input, resolved)).then(result => JSON.parse(JSON.stringify(result))),
+            prepare: async (input, context) => {
+                v3_1.z.object({}).strict().parse(input);
+                const resolved = this.authoringContext(context);
+                await this.run(resolved, current => this.engine.discover({}, current));
+                return resolved.options;
+            }
         };
+        this.configuration = { kind: 'definition', connection: 'integration', schema: {
+                type: 'object', properties: { integrationId: { type: 'string', format: 'uuid', title: 'Integration ID' }, assistantCode: { type: 'string', title: 'Assistant code' }, assistantXpertId: { type: 'string', format: 'uuid', title: 'Assistant ID' }, workspaceId: { type: 'string', format: 'uuid', title: 'Workspace ID' } },
+                required: ['integrationId', 'assistantCode', 'assistantXpertId', 'workspaceId'], additionalProperties: false
+            } };
     }
-    async discover(request, context) {
-        const empty = request && typeof request === 'object' && !Array.isArray(request) && Object.keys(request).length === 0;
-        const parsed = discovery_1.dataXpertDiscoveryRequestSchema.parse(empty ? { kind: 'resources' } : request);
-        const response = await this.request('discover', context, { request: parsed });
-        const result = v3_1.z.object({ items: v3_1.z.array(v3_1.z.unknown()),
-            nextRequest: json.optional() }).strict().parse(await boundedJson(response));
-        return plugin_sdk_1.analyticsDiscoveryResultSchema.parse({ ...result, schemaVersion: 1, queryContract: discovery_1.dataXpertQueryContract });
+    authoringContext(context) {
+        if (context.connection.kind !== 'integration')
+            throw new Error('ANALYTICS_CONNECTION_INVALID');
+        // The host uses the Assistant UUID as x-assistant-code for data-xpert calls.
+        return { actor: context.actor, signal: context.signal, deadlineAt: context.deadlineAt, maxRows: 5,
+            options: { integrationId: context.connection.integrationId, assistantCode: context.xpertId,
+                assistantXpertId: context.xpertId, workspaceId: context.workspaceId } };
     }
-    async request(endpoint, context, body) {
-        context.signal.throwIfAborted();
-        const options = optionsSchema.parse(context.options);
-        const base = new URL(options.baseUrl);
-        if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash)
-            throw new Error('DATAX_URL_INVALID');
-        const token = await this.runtime.require(plugin_sdk_1.ActorTokenRuntimeFactoryCapability).createScopedApi(context.actor).getToken({ audience: options.audience });
-        context.signal.throwIfAborted();
-        const response = await fetch(`${base.href.replace(/\/$/, '')}/agent-workbench/analytics/${endpoint}`, {
-            method: 'POST', redirect: 'error', signal: context.signal,
-            headers: { Authorization: `Bearer ${token.token}`, 'Content-Type': 'application/json', 'organization-id': context.actor.organizationId },
-            body: JSON.stringify({ assistant: { code: options.assistantCode, xpertId: options.assistantXpertId, workspaceId: options.workspaceId }, ...body })
-        });
-        if (!response.ok) {
-            // Do not retain an unconsumed upstream error stream or expose its potentially sensitive body.
-            await response.body?.cancel().catch(() => undefined);
-            throw new Error(`DATAX_QUERY_HTTP_${response.status}`);
-        }
-        return response;
+    async validateConfiguration(options, actor) {
+        const parsed = optionsSchema.parse(options);
+        await this.connection(parsed.integrationId, actor);
+        return parsed;
     }
-    async execute(binding, parameters, context) {
-        const payload = exports.dataXpertPayloadSchema.parse(binding.payload);
-        const response = await this.request('query', context, {
-            binding: { id: binding.id, resourceId: payload.resourceId, actionTypeCode: payload.actionTypeCode, target: payload.target,
-                params: bindParameters(payload.params, payload.parameterPaths, parameters) }, maxRows: context.maxRows
-        });
-        const result = responseSchema.parse(await boundedJson(response));
-        return { columns: result.effect.columns, rows: result.effect.rows,
-            completeness: { returnedRows: result.effect.summary.returnedRowCount, totalRows: result.effect.summary.rowCount,
-                totalAccuracy: result.effect.summary.truncated ? 'unknown' : 'exact', scope: result.effect.summary.truncated ? 'page' : 'full_query_result',
-                truncated: result.effect.summary.truncated }, sourceFetchedAt: result.fetchedAt,
-            upstreamExecutionId: result.executionId, auditRef: result.auditRef };
+    async connection(id, actor) {
+        const integration = await this.queries.execute(new plugin_sdk_1.ResolveConnectorIntegrationQuery(id, integration_1.DATA_XPERT_INTEGRATION, { tenantId: actor.tenantId, organizationId: actor.organizationId }));
+        if (!integration || integration.tenantId !== actor.tenantId || (integration.organizationId && integration.organizationId !== actor.organizationId))
+            throw new Error('DATAX_INTEGRATION_UNAVAILABLE');
+        return integration_1.connectionSchema.parse(integration.options);
     }
+    async run(context, execute) {
+        const { integrationId, ...target } = optionsSchema.parse(context.options);
+        const connection = await this.connection(integrationId, context.actor);
+        const result = await execute({ ...context, options: { ...target, ...connection } });
+        const current = await this.connection(integrationId, context.actor);
+        if (JSON.stringify(current) !== JSON.stringify(connection))
+            throw new Error('DATAX_INTEGRATION_CHANGED');
+        return result;
+    }
+    discover(request, context) { return this.run(context, resolved => this.engine.discover(request, resolved)); }
+    execute(binding, parameters, context) { return this.run(context, resolved => this.engine.execute(binding, parameters, resolved)); }
 };
 exports.DataXpertAnalyticsProvider = DataXpertAnalyticsProvider;
 exports.DataXpertAnalyticsProvider = DataXpertAnalyticsProvider = __decorate([
     (0, plugin_sdk_1.AnalyticsProvider)('data-xpert.ontology'),
-    __param(0, (0, common_1.Inject)(plugin_sdk_1.XPERT_RUNTIME_CAPABILITIES_TOKEN)),
-    __metadata("design:paramtypes", [Object])
+    __metadata("design:paramtypes", [client_1.DataXpertAnalyticsClient, cqrs_1.QueryBus])
 ], DataXpertAnalyticsProvider);
-/** Typed paths replace whole parameter values, never splice text into SQL/MDX/OData. */
-function bindParameters(params, paths, parameters) {
-    const result = structuredClone(params);
-    if (Object.keys(parameters).some((name) => !Object.hasOwn(paths, name)) || Object.keys(paths).some((name) => !Object.hasOwn(parameters, name)))
-        throw new Error('DATAX_PARAMETER_MAPPING_INVALID');
-    if (new Set(Object.values(paths).map((path) => JSON.stringify(path))).size !== Object.keys(paths).length)
-        throw new Error('DATAX_PARAMETER_MAPPING_INVALID');
-    for (const [name, path] of Object.entries(paths)) {
-        let current = result;
-        for (const [index, key] of path.entries()) {
-            if (['__proto__', 'prototype', 'constructor'].includes(key) || !current || typeof current !== 'object' || !Object.hasOwn(current, key))
-                throw new common_1.BadRequestException('DATAX_PARAMETER_PATH_INVALID: parameterPaths are relative to params. Omit the leading params segment and target an existing scalar, for example ["slicers","1","value"].');
-            if (Array.isArray(current)) {
-                if (!/^(0|[1-9]\d*)$/.test(key) || Number(key) >= current.length)
-                    throw new Error('DATAX_PARAMETER_PATH_INVALID');
-                const position = Number(key);
-                if (index === path.length - 1) {
-                    if (current[position] !== null && typeof current[position] === 'object')
-                        throw new Error('DATAX_PARAMETER_PATH_NOT_SCALAR');
-                    current[position] = parameters[name];
-                }
-                else
-                    current = current[position];
-            }
-            else if (index === path.length - 1) {
-                if (current[key] !== null && typeof current[key] === 'object')
-                    throw new Error('DATAX_PARAMETER_PATH_NOT_SCALAR');
-                current[key] = parameters[name];
-            }
-            else
-                current = current[key];
-        }
-    }
-    return result;
-}
-async function boundedJson(response) {
-    if (!response.body)
-        throw new Error('DATAX_EMPTY_RESPONSE');
-    const reader = response.body.getReader();
-    const chunks = [];
-    let size = 0;
-    try {
-        for (;;) {
-            const chunk = await reader.read();
-            if (chunk.done)
-                break;
-            size += chunk.value.byteLength;
-            if (size > 2_500_000)
-                throw new Error('DATAX_RESPONSE_TOO_LARGE');
-            chunks.push(chunk.value);
-        }
-        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
-    }
-    finally {
-        await reader.cancel();
-    }
-}

package/docs/index.mdx

@@ -7,8 +7,7 @@ description: "Adapt governed ontology Actions to Xpert Dataset/Binding without c
 
 Xpert owns the shared Dataset/Binding protocol, current actor, source configuration,
 parameter validation, execution budget and Artifact persistence. This system plugin registers
-`data-xpert.ontology`, operation `action`, contract version `1`, and the `data-xpert`
-DataSource type. It converts declared scalar parameters into native Action arguments and
+`data-xpert.ontology`, operation `action`, contract version `1`, a Definition configuration entry and the `analytics-data-xpert` Integration strategy. It converts declared scalar parameters into native Action arguments and
 maps canonical rows, completeness and audit receipts back to the shared Dataset path.
 
 Data-xpert owns published resource discovery, ontology adapter metadata, Action input
@@ -20,8 +19,7 @@ The provider ID is a stable Binding reference; package ownership uses the
 
 ## Server configuration and identity
 
-Configure `baseUrl` (including `/api`), `audience`, `assistantCode`, `assistantXpertId`
-and `workspaceId` on the platform DataSource. The Assistant and workspace must already
+Create a **data-xpert Analytics** Integration with `baseUrl` (including `/api`) and `audience`. In **Settings → Analytics**, publish a Definition with `integrationId`, `assistantCode`, `assistantXpertId` and `workspaceId`. The Integration is resolved in the current tenant/organization before and after each request. The Assistant and workspace must already
 have the intended published resources and viewer policy in data-xpert.
 
 The provider gets a short-lived token through

package/docs/verification.mdx

@@ -5,7 +5,7 @@ description: "Separate transport-contract tests from real SSO and end-to-end das
 
 ## Compatibility
 
-Development dependencies pin published SDK/contracts 3.25.0, which export AnalyticsProvider,
+Development dependencies pin published SDK/contracts 3.26.1, which export AnalyticsProvider,
 AnalyticsQueryProvider, ActorTokenRuntimeFactoryCapability and the shared Dataset/Binding
 contracts. The host must provide the corresponding runtime capabilities.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-analytics-data-xpert",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Governed data-xpert ontology analytics provider",
   "main": "./index.cjs",
   "types": "./dist/index.d.ts",
@@ -27,21 +27,23 @@
     }
   },
   "peerDependencies": {
-    "@xpert-ai/plugin-sdk": "^3.25.0",
-    "@xpert-ai/contracts": "^3.25.0",
+    "@xpert-ai/plugin-sdk": "^3.26.1",
+    "@xpert-ai/contracts": "^3.26.1",
     "@nestjs/common": "^11.1.6",
     "@nestjs/core": "^11.1.6",
-    "zod": "3.25.67"
+    "zod": "3.25.67",
+    "@nestjs/cqrs": "^11.0.3"
   },
   "devDependencies": {
-    "@xpert-ai/plugin-sdk": "3.25.0",
-    "@xpert-ai/contracts": "3.25.0",
+    "@xpert-ai/plugin-sdk": "3.26.1",
+    "@xpert-ai/contracts": "3.26.1",
     "@nestjs/common": "^11.1.6",
     "@nestjs/core": "^11.1.6",
     "zod": "3.25.67",
     "typescript": "^5.9.2",
     "@types/node": "^20.19.9",
-    "reflect-metadata": "^0.2.2"
+    "reflect-metadata": "^0.2.2",
+    "@nestjs/cqrs": "^11.0.3"
   },
   "repository": {
     "type": "git",