@xpert-ai/plugin-analytics-data-xpert 0.2.0 → 0.3.0

package/dist/lib/client.d.ts

@@ -5,6 +5,11 @@ export type DataXpertClientContext = Pick<AnalyticsProviderContext, 'actor' | 'o
 export declare class DataXpertAnalyticsClient {
     private readonly runtime;
     constructor(runtime: RuntimeCapabilityRegistry);
+    /**
+     * Ask Data Xpert to validate disclosure authority using the current human's scoped token.
+     * This metadata-only check neither executes the binding nor grants future query access.
+     */
+    authorizeGroupSharing(binding: AnalyticsBinding, context: DataXpertClientContext): Promise<void>;
     discover(request: JSONValue, context: DataXpertClientContext): Promise<AnalyticsDiscoveryResult>;
     private request;
     execute(binding: AnalyticsBinding, parameters: Record<string, AnalyticsValue>, context: DataXpertClientContext): Promise<AnalyticsProviderResult>;

package/dist/lib/client.js

@@ -46,6 +46,18 @@ let DataXpertAnalyticsClient = class DataXpertAnalyticsClient {
     constructor(runtime) {
         this.runtime = runtime;
     }
+    /**
+     * Ask Data Xpert to validate disclosure authority using the current human's scoped token.
+     * This metadata-only check neither executes the binding nor grants future query access.
+     */
+    async authorizeGroupSharing(binding, context) {
+        const payload = payload_1.dataXpertPayloadSchema.parse(binding.payload);
+        const response = await this.request('authorize-group-sharing', context, {
+            binding: { id: binding.id, resourceId: payload.resourceId, actionTypeCode: payload.actionTypeCode,
+                target: payload.target, params: payload.params }, maxRows: 1
+        });
+        v3_1.z.object({ authorized: v3_1.z.literal(true) }).strict().parse(await boundedJson(response));
+    }
     async discover(request, context) {
         const importing = import_targets_1.importTargetRequest.safeParse(request);
         if (importing.success)
@@ -56,7 +68,7 @@ let DataXpertAnalyticsClient = class DataXpertAnalyticsClient {
             const result = await this.query(datasetId, parsed.payload, parsed.parameters, context);
             return plugin_sdk_1.analyticsDiscoveryResultSchema.parse({
                 items: [{ id: datasetId, name: datasetId, kind: 'dataset',
-                        metadata: { output: (0, result_schema_1.createDataXpertOutput)(datasetId, result.effect.columns) } }],
+                        metadata: { payload: parsed.payload, output: (0, result_schema_1.createDataXpertOutput)(datasetId, result.effect.columns) } }],
                 queryContract: discovery_1.dataXpertQueryContract
             });
         }

package/dist/lib/discovery.js

@@ -48,7 +48,7 @@ exports.dataXpertQueryContract = {
         '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.',
-        'Before authoring a binding, use dashboard_discover with the same source/providerId and requestJson encoding {kind:"query-schema",payload:<native Action envelope>,parameters:<mapped scalar values, or {}>}. This runs that bounded read-only Action under the current viewer policy; respect the native Action limits and filters. It returns items[0].metadata.output without business rows. Omit datasetId to let the provider generate a valid output key. Copy this output into the dashboard_preview binding, preserving datasetId, field IDs, sourceField, logicalType, role and nullable. Decimal/int64 remain exact strings; do not infer types from sample cells or names. If declarations are missing, obtain source metadata instead of guessing.',
-        'The discovered output has empty grain because column roles alone do not prove uniqueness. Declare grain only when supported by query semantics. Always run dashboard_preview with the same payload and parameter values to validate the binding and obtain a preview receipt before saving; schema discovery is not a preview receipt. Re-discover after changing the query projection. A partial page is not a complete business aggregate.'
+        'Before authoring a binding, use dashboard_discover with the same source/providerId and requestJson encoding {kind:"query-schema",payload:<native Action envelope>,parameters:<mapped scalar values, or {}>}. This runs that bounded read-only Action under the current viewer policy; respect the native Action limits and filters. It returns items[0].metadata.payload (the validated native envelope, including parameterPaths) and metadata.output without business rows. Copy both into the preview binding; do not reconstruct or omit required payload fields. Omit datasetId to let the provider generate a valid output key. Copy this output into the dashboard_preview binding, preserving datasetId, field IDs, sourceField, logicalType, role and nullable. Decimal/int64 remain exact strings; do not infer types from sample cells or names. If declarations are missing, obtain source metadata instead of guessing.',
+        'The discovered output has empty grain because column roles alone do not prove uniqueness. Declare grain only when supported by query semantics, using IDs from output.fields rather than source dimension names. Always run dashboard_preview with the same payload and parameter values to validate the binding and obtain a preview receipt before saving; schema discovery is not a preview receipt. Re-discover after changing the query projection. A partial page is not a complete business aggregate.'
     ].join(' ')
 };

package/dist/lib/provider.d.ts

@@ -57,5 +57,7 @@ export declare class DataXpertAnalyticsProvider implements AnalyticsQueryProvide
     private connection;
     private run;
     discover(request: JSONValue, context: AnalyticsProviderContext): Promise<import("@xpert-ai/contracts").AnalyticsDiscoveryResult>;
+    /** Keep source-sharing checks under the same actor and integration revalidation as ordinary queries. */
+    authorizeGroupSharing(binding: AnalyticsBinding, context: AnalyticsProviderContext): Promise<void>;
     execute(binding: AnalyticsBinding, parameters: Record<string, AnalyticsValue>, context: AnalyticsProviderContext): Promise<import("@xpert-ai/plugin-sdk").AnalyticsProviderResult>;
 }

package/dist/lib/provider.js

@@ -68,6 +68,8 @@ let DataXpertAnalyticsProvider = class DataXpertAnalyticsProvider {
         return result;
     }
     discover(request, context) { return this.run(context, resolved => this.engine.discover(request, resolved)); }
+    /** Keep source-sharing checks under the same actor and integration revalidation as ordinary queries. */
+    authorizeGroupSharing(binding, context) { return this.run(context, resolved => this.engine.authorizeGroupSharing(binding, resolved)); }
     execute(binding, parameters, context) { return this.run(context, resolved => this.engine.execute(binding, parameters, resolved)); }
 };
 exports.DataXpertAnalyticsProvider = DataXpertAnalyticsProvider;

package/docs/index.mdx

@@ -96,3 +96,15 @@ the host's declared Binding bridge. They do not call data-xpert directly. Filter
 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.
+
+## Reuse a discovered query
+
+`query-schema` returns both `items[0].metadata.payload` and
+`items[0].metadata.output`. Copy both into the preview binding. The payload is
+the validated native Action envelope, including an empty `parameterPaths` when
+no controls are mapped; it contains no trusted connection options or actor
+credentials. Output contains declared field metadata, not business rows.
+Use output field IDs for `grain`, and declare uniqueness only when the query
+semantics prove it. A successful schema discovery still requires a separate
+binding preview. Adapter-owned time validation errors require correcting the
+query against published metadata; they do not establish missing source data.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-analytics-data-xpert",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Governed data-xpert ontology analytics provider",
   "main": "./index.cjs",
   "types": "./dist/index.d.ts",