@xpert-ai/plugin-analytics-data-xpert 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# data-xpert analytics provider
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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"]}}
+```
+
+This is a SQL semantic-model Action example; it is not the contract for other ontology adapters. Replace placeholders and use exact targets/fields returned by published-resource discovery. Each registered Action defines its own params shape. Array path segments use canonical zero-based indices. Bindings cannot supply actor, credentials or URL. Paths replace entire existing scalar values, never SQL/MDX/OData fragments. Unknown/prototype paths fail.
+
+The provider obtains the current actor's token via ActorTokenRuntimeFactoryCapability.createScopedApi(context.actor), then POSTs to /agent-workbench/analytics/query. data-xpert validates OIDC, Assistant/resource binding, explicit viewer policy and the existing Live Artifact read-only allowlist, bypassing Action result caches. Typed rows/columns and audit receipts are projected into the canonical Dataset.
+
+Run `corepack pnpm exec nx run @xpert-ai/plugin-analytics-data-xpert:test` with the current platform SDK. Real integration requires the corresponding data-xpert endpoint, published resources, Assistant bindings, explicit viewer policy and working xpert-pro OIDC. Mocked identity tests do not establish SSO acceptance.
+
+Discovery preserves each adapter's `definition` (identity, version, native metadata and instructions) and each Action's input schema. Semantic Model, OData and future registered read-only adapters share this transport without sharing query syntax.
+
+See [architecture and Binding usage](docs/index.mdx) and [compatibility and verification](docs/verification.mdx).

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { XpertPlugin } from '@xpert-ai/plugin-sdk';
+declare const plugin: XpertPlugin;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_fs_1 = require("node:fs");
+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 },
+    register: () => ({ module: plugin_1.AnalyticsDataXpertPlugin })
+};
+exports.default = plugin;

package/dist/lib/discovery.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod/v3';
+import type { AnalyticsDiscoveryResult } from '@xpert-ai/contracts';
+/** Private wire contract for data-xpert discovery; actor and Assistant scope are server-owned. */
+export declare const dataXpertDiscoveryRequestSchema: z.ZodDiscriminatedUnion<"kind", [z.ZodObject<{
+    kind: z.ZodLiteral<"resources">;
+    after: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    kind: "resources";
+    after?: string | undefined;
+}, {
+    kind: "resources";
+    after?: string | undefined;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"entities">;
+    resourceId: z.ZodString;
+    entityTypeCode: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    kind: "entities";
+    resourceId: string;
+    entityTypeCode?: string | undefined;
+    query?: string | undefined;
+}, {
+    kind: "entities";
+    resourceId: string;
+    entityTypeCode?: string | undefined;
+    query?: string | undefined;
+}>, z.ZodObject<{
+    kind: z.ZodLiteral<"actions">;
+    resourceId: z.ZodString;
+    target: z.ZodObject<{
+        entityTypeCode: z.ZodString;
+        entityRef: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        entityTypeCode: string;
+        entityRef: string;
+    }, {
+        entityTypeCode: string;
+        entityRef: string;
+    }>;
+}, "strict", z.ZodTypeAny, {
+    kind: "actions";
+    resourceId: string;
+    target: {
+        entityTypeCode: string;
+        entityRef: string;
+    };
+}, {
+    kind: "actions";
+    resourceId: string;
+    target: {
+        entityTypeCode: string;
+        entityRef: string;
+    };
+}>]>;
+/**
+ * All ontology adapters share this envelope, not a native query language.
+ * Preserve definition.adapterId/contractVersion/metadata/instructions and Action inputSchema
+ * from data-xpert. New adapters must not require branches in this provider or the renderer.
+ */
+export declare const dataXpertQueryContract: AnalyticsDiscoveryResult['queryContract'];

package/dist/lib/discovery.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dataXpertQueryContract = exports.dataXpertDiscoveryRequestSchema = void 0;
+const v3_1 = require("zod/v3");
+/** Private wire contract for data-xpert discovery; actor and Assistant scope are server-owned. */
+exports.dataXpertDiscoveryRequestSchema = v3_1.z.discriminatedUnion('kind', [
+    v3_1.z.object({ kind: v3_1.z.literal('resources'), after: v3_1.z.string().min(1).max(160).optional() }).strict(),
+    v3_1.z.object({
+        kind: v3_1.z.literal('entities'), resourceId: v3_1.z.string().min(1).max(160),
+        entityTypeCode: v3_1.z.string().min(1).max(160).optional(), query: v3_1.z.string().max(256).optional()
+    }).strict(),
+    v3_1.z.object({
+        kind: v3_1.z.literal('actions'), resourceId: v3_1.z.string().min(1).max(160),
+        target: v3_1.z.object({ entityTypeCode: v3_1.z.string().min(1).max(160), entityRef: v3_1.z.string().min(1).max(512) }).strict()
+    }).strict()
+]);
+/**
+ * All ontology adapters share this envelope, not a native query language.
+ * Preserve definition.adapterId/contractVersion/metadata/instructions and Action inputSchema
+ * from data-xpert. New adapters must not require branches in this provider or the renderer.
+ */
+exports.dataXpertQueryContract = {
+    operation: 'action', contractVersion: 1,
+    payloadSchema: {
+        type: 'object', additionalProperties: false,
+        required: ['resourceId', 'actionTypeCode', 'target', 'params', 'parameterPaths'],
+        properties: {
+            resourceId: { type: 'string', minLength: 1, maxLength: 160 },
+            actionTypeCode: { type: 'string', minLength: 1, maxLength: 160 },
+            target: {
+                type: 'object', additionalProperties: false,
+                properties: {
+                    entityId: { type: 'string', minLength: 1, maxLength: 256 },
+                    entityTypeCode: { type: 'string', minLength: 1, maxLength: 256 },
+                    entityRef: { type: 'string', minLength: 1, maxLength: 512 }
+                },
+                anyOf: [{ required: ['entityId'] }, { required: ['entityRef'] }]
+            },
+            params: { type: 'object' },
+            parameterPaths: { type: 'object', additionalProperties: {
+                    type: 'array', minItems: 1, maxItems: 8, items: { type: 'string', minLength: 1 }
+                } }
+        }
+    },
+    instructions: [
+        'Follow inspectRequest: resources -> entities -> actions. Continue nextRequest even when the visible resource page is empty. Entity discovery returns top 20 matches; narrow query/entityTypeCode if needed.',
+        'Entity metadata.definition contains adapterId, contractVersion, metadata and instructions. Follow that adapter-specific definition and the discovered Action inputSchema/inputHint. Preserve canonical targets, resource IDs and exact field names. Do not infer adapter types from names or apply one adapter\'s query, filter or time rules to another.',
+        'Use only published metadata and authorized previews to establish business metrics, time axes, supported filters and complete aggregation. Missing metadata does not authorize guessing; obtain sufficient evidence before generating a time filter.',
+        'Use parameterPaths relative to params to replace an existing scalar value, for example {region:["filters","0","value"]}. Paths must be unique. Never interpolate values into query text. Controls supply scalar values; arrays remain static unless the native Action explicitly supports another declared scalar mapping. Null handling and filter operators are defined by the Action schema and adapter instructions.',
+        'Only read-only Actions allowed by the current viewer policy are returned. Map output sourceField to returned column keys (or an explicit semanticRef). Numeric JSON cells require float64; decimal/int64 require exact strings. Preview to verify types, grain and completeness before binding charts. A partial page is not a complete business aggregate.'
+    ].join(' ')
+};

package/dist/lib/plugin.d.ts

@@ -0,0 +1,2 @@
+export declare class AnalyticsDataXpertPlugin {
+}

package/dist/lib/plugin.js

@@ -0,0 +1,17 @@
+"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.AnalyticsDataXpertPlugin = void 0;
+const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
+const provider_1 = require("./provider");
+let AnalyticsDataXpertPlugin = class AnalyticsDataXpertPlugin {
+};
+exports.AnalyticsDataXpertPlugin = AnalyticsDataXpertPlugin;
+exports.AnalyticsDataXpertPlugin = AnalyticsDataXpertPlugin = __decorate([
+    (0, plugin_sdk_1.XpertServerPlugin)({ providers: [provider_1.DataXpertAnalyticsProvider] })
+], AnalyticsDataXpertPlugin);

package/dist/lib/provider.d.ts

@@ -0,0 +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;
+    };
+    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 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>;
+}
+/** 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

@@ -0,0 +1,164 @@
+"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.DataXpertAnalyticsProvider = 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 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
+                } }
+        };
+    }
+    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 });
+    }
+    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.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])
+], 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/AGENTS.md

@@ -0,0 +1,11 @@
+# data-xpert analytics documentation
+
+This Mintlify site documents the analytics provider, not ontology authoring or deployment automation.
+Use MDX with YAML frontmatter and keep `docs.json` navigation synchronized.
+
+- Distinguish Xpert Dataset/Binding, this provider's transport, and data-xpert's ontology adapters.
+- Keep native query semantics in adapter-owned `definition` and Action `inputSchema`.
+- Explain current-viewer Actor Token and Assistant/resource authorization without exposing credentials.
+- Do not claim that a registered ontology adapter automatically permits a read-only Action.
+- Distinguish HTTP fixtures and lifecycle mocks from real SSO and dashboard acceptance.
+- Keep machine paths, private receipts and tokens out of the package.

package/docs/docs.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "maple",
+  "name": "data-xpert Analytics",
+  "colors": {
+    "primary": "#0f766e",
+    "light": "#14b8a6",
+    "dark": "#115e59"
+  },
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Documentation",
+        "groups": [
+          {
+            "group": "Provider",
+            "pages": [
+              "index",
+              "verification"
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}

package/docs/index.mdx

@@ -0,0 +1,100 @@
+---
+title: "data-xpert analytics provider"
+description: "Adapt governed ontology Actions to Xpert Dataset/Binding without coupling the platform to native query languages."
+---
+
+## Responsibilities
+
+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
+maps canonical rows, completeness and audit receipts back to the shared Dataset path.
+
+Data-xpert owns published resource discovery, ontology adapter metadata, Action input
+schemas, Assistant/resource access, explicit viewer policy and registered read-only execution.
+No database runner or ontology-specific branch is added to the Xpert platform.
+
+The provider ID is a stable Binding reference; package ownership uses the
+`analytics_data_xpert` artifact namespace. Changing the ID requires saved-Binding migration.
+
+## Server configuration and identity
+
+Configure `baseUrl` (including `/api`), `audience`, `assistantCode`, `assistantXpertId`
+and `workspaceId` on the platform DataSource. 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
+`ActorTokenRuntimeFactoryCapability.createScopedApi(context.actor)`. Every request sends
+that token and the current actor's `organization-id` header. Neither the Agent's Binding nor
+the HTML iframe supplies a token, actor, API URL or Assistant scope.
+
+Only HTTP(S) base URLs without embedded credentials, query or fragment are accepted.
+Redirects are rejected. The host abort signal propagates through fetch and response streaming;
+a cancellation before or during token acquisition prevents a subsequent HTTP call.
+
+## Discovery across ontology adapters
+
+Start with `{}` or `{ "kind": "resources" }`. Follow each `inspectRequest` from resources
+to entities and then Actions. Follow `nextRequest` even if authorization filtered the entire
+page. Entity results are limited to 20 matches; narrow `query` or `entityTypeCode` as needed.
+
+Entity metadata carries this adapter-owned envelope:
+
+```json
+{
+  "definition": {
+    "adapterId": "sap_odata_api",
+    "contractVersion": 1,
+    "metadata": { "properties": [], "keys": [], "queryCapabilities": {} },
+    "instructions": ["Use the published property definitions and Action inputSchema."]
+  }
+}
+```
+
+The provider preserves this envelope, canonical targets, snapshot/version/partition fields,
+and each Action's `inputSchema` and `inputHint`. Semantic Model metadata may contain an
+`analysisContract`; OData metadata has different fields. The plugin does not translate either
+into the other's language or infer an adapter from labels.
+
+A new ontology adapter can use this path when data-xpert registers its discovery metadata
+and permits its read-only Actions with canonical effects. Registration, published resource
+access and explicit viewer policy are all required. A resource type alone is insufficient.
+
+## Binding and filters
+
+The payload selects exact discovered `resourceId`, `actionTypeCode`, canonical `target`,
+native `params` and `parameterPaths`. The target must contain `entityId` or `entityRef`.
+Use discovered `entityTypeCode` with external references when supplied.
+
+For an Action whose input schema defines the following filter, a mapping looks like this:
+
+```json
+{
+  "params": { "filters": [{ "field": "Region", "op": "eq", "value": null }] },
+  "parameterPaths": { "region": ["filters", "0", "value"] }
+}
+```
+
+This is a parameter-mapping example, not a universal ontology filter format. Use the selected
+Action's actual input schema. Paths are relative to `params`, unique, and must identify an
+existing scalar. Array segments use canonical zero-based indices. Missing/extra mappings,
+prototype keys and replacing an entire object/array are rejected. Parameters are cloned and
+replaced as whole values; the provider never interpolates query text.
+
+Each adapter defines its own null semantics, operators, supported time fields and aggregation
+limits. Verify business meaning and time axes with published metadata and authorized previews.
+Map returned column keys or explicit semantic references to Dataset field IDs.
+
+## Rendering and freshness
+
+Data-xpert's query endpoint supplies canonical rows for `rows`, `series` and `entity` effects.
+The provider carries those rows, source-fetch time, upstream execution ID and audit reference
+into the platform normalizer. Truncated results use page scope and unknown total accuracy.
+The reported count must not be interpreted as a verified full business aggregate.
+
+Structured Data Analytics views and free HTML/JS Artifacts consume the same Dataset through
+the host's declared Binding bridge. They do not call data-xpert directly. Filtering resolves
+new declared parameters; refreshing performs another request. Responses must declare
+`fromCache: false`, meaning the data-xpert Action result cache was bypassed. Upstream source
+caches and business-data freshness are separate concerns.

package/docs/verification.mdx

@@ -0,0 +1,58 @@
+---
+title: "Build and verification"
+description: "Separate transport-contract tests from real SSO and end-to-end dashboard acceptance."
+---
+
+## Compatibility
+
+Development dependencies pin published SDK/contracts 3.25.0, which export AnalyticsProvider,
+AnalyticsQueryProvider, ActorTokenRuntimeFactoryCapability and the shared Dataset/Binding
+contracts. The host must provide the corresponding runtime capabilities.
+
+Data-xpert must expose `POST /agent-workbench/analytics/discover` and
+`POST /agent-workbench/analytics/query` under the configured API base. Discovery returns
+adapter-owned `definition` metadata. Query returns canonical rows, execution/audit references,
+fetch time and `fromCache: false` after the normal authorization and read-only Action pipeline.
+
+## Local verification
+
+From the xpertai workspace:
+
+```sh
+corepack pnpm exec nx run @xpert-ai/plugin-analytics-data-xpert:test
+corepack pnpm exec nx run @xpert-ai/plugin-analytics-data-xpert:typecheck
+```
+
+Tests start a disposable local HTTP fixture and use synthetic Actor Tokens. They verify:
+
+- current actor, organization, trusted Assistant scope and token audience;
+- Semantic Model/OData metadata, canonical targets, pagination and Action schemas;
+- scalar filter mapping and rejection of unknown/prototype/duplicate paths;
+- rows/series/entity projection, partial totals, audit receipts and fresh requests;
+- unknown inputs, missing targets, cached responses and invalid configured URLs;
+- refused redirects, bounded response streaming and cancellation.
+
+Build and package before running `plugin-dev-harness`. Its lifecycle mocks verify package
+loading and Nest injection, not a real identity provider or data-xpert authorization decision.
+Validate `docs.json` navigation and run `mint validate` when updating documentation.
+
+## Separate live acceptance
+
+Install through the authenticated system-plugin workflow with tenant scope in the Default
+tenant. Configure a DataSource pointing to the intended data-xpert API and its OIDC audience.
+Use xpert-pro SSO, a published Assistant/resource binding and explicit viewer policy.
+
+Verify an allowed viewer can discover and query, while a denied viewer cannot. Preview both
+Semantic Model and OData (or another registered adapter) using their actual Action schemas.
+Then verify one-sentence generation, filters, changed-source refresh, save/reopen and rejection
+of undeclared HTML frontend queries. Local HTTP fixtures do not establish those outcomes.
+
+## Errors
+
+- `DATAX_PARAMETER_MAPPING_INVALID`: align parameter names with unique declared paths.
+- `DATAX_PARAMETER_PATH_INVALID`: use an existing path relative to params with canonical indices.
+- `DATAX_PARAMETER_PATH_NOT_SCALAR`: target a scalar value, not an object or array.
+- `DATAX_URL_INVALID`: correct trusted source configuration.
+- `DATAX_QUERY_HTTP_<status>`: investigate authorization or request validation in data-xpert;
+  upstream error bodies and secrets are not forwarded.
+- `DATAX_RESPONSE_TOO_LARGE`: reduce result size; response buffering is bounded.

package/index.cjs

@@ -0,0 +1 @@
+module.exports = require('./dist/index.js').default

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@xpert-ai/plugin-analytics-data-xpert",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Governed data-xpert ontology analytics provider",
+  "main": "./index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./index.cjs",
+      "default": "./index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "index.cjs",
+    "README.md",
+    "docs"
+  ],
+  "license": "AGPL-3.0",
+  "private": false,
+  "xpert": {
+    "plugin": {
+      "level": "system",
+      "artifactNamespace": "analytics_data_xpert"
+    }
+  },
+  "peerDependencies": {
+    "@xpert-ai/plugin-sdk": "^3.25.0",
+    "@xpert-ai/contracts": "^3.25.0",
+    "@nestjs/common": "^11.1.6",
+    "@nestjs/core": "^11.1.6",
+    "zod": "3.25.67"
+  },
+  "devDependencies": {
+    "@xpert-ai/plugin-sdk": "3.25.0",
+    "@xpert-ai/contracts": "3.25.0",
+    "@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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/xpert-ai/xpert-plugins.git",
+    "directory": "xpertai/tools/analytics-data-xpert"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "pnpm run build && node --test tests/*.test.cjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
 }