@xpert-ai/plugin-live-dashboard 0.4.0 → 0.5.0

package/dist/lib/archive.service.js

@@ -0,0 +1,133 @@
+"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.importBrowseSchema = exports.DashboardArchiveService = exports.importInputSchema = void 0;
+const common_1 = require("@nestjs/common");
+const node_crypto_1 = require("node:crypto");
+const v3_1 = require("zod/v3");
+const plugin_sdk_1 = require("@xpert-ai/plugin-sdk");
+const analytics_1 = require("@xpert-ai/plugin-sdk/analytics");
+const dashboard_service_1 = require("./dashboard.service");
+const dashboard_schema_1 = require("./dashboard.schema");
+const dashboard_archive_1 = require("./dashboard-archive");
+const document_package_1 = require("./document-package");
+exports.importInputSchema = v3_1.z.object({ importId: v3_1.z.string().uuid(),
+    bindings: v3_1.z.array(v3_1.z.object({ bindingId: v3_1.z.string(), source: analytics_1.analyticsSourceRefSchema, payload: analytics_1.analyticsBindingObjectSchema.shape.payload }).strict()).max(8)
+}).strict();
+const importBrowseSchema = v3_1.z.object({ importId: v3_1.z.string().uuid(), bindingId: v3_1.z.string(), source: analytics_1.analyticsSourceRefSchema, request: analytics_1.analyticsOptionsSchema.default({}) }).strict();
+exports.importBrowseSchema = importBrowseSchema;
+let DashboardArchiveService = class DashboardArchiveService {
+    constructor(dashboards, runtime) {
+        this.dashboards = dashboards;
+        this.runtime = runtime;
+        this.imports = new Map();
+    }
+    async authorize(context) {
+        if (!(await this.dashboards.access(context)).canEdit)
+            throw new common_1.ForbiddenException('DASHBOARD_DEFINITION_ACCESS_DENIED');
+    }
+    session(context, id) {
+        const session = this.imports.get(id);
+        if (!session || session.scope !== importScope(context) || Date.now() - session.created > 30 * 60_000)
+            throw new common_1.BadRequestException('DASHBOARD_IMPORT_EXPIRED');
+        return session;
+    }
+    async prepare(context, bytes) {
+        await this.authorize(context);
+        const document = (0, dashboard_archive_1.decodeDashboardArchive)(bytes);
+        for (const [key, session] of this.imports)
+            if (Date.now() - session.created > 30 * 60_000)
+                this.imports.delete(key);
+        if (this.imports.size >= 16)
+            throw new common_1.BadRequestException('DASHBOARD_IMPORT_LIMIT');
+        const importId = (0, node_crypto_1.randomUUID)();
+        this.imports.set(importId, { ...document, scope: importScope(context), created: Date.now(), newId: (0, node_crypto_1.randomUUID)(), busy: false });
+        return { importId, manifest: document.manifest, requirements: (0, dashboard_archive_1.dashboardRequirements)(document.manifest), sources: await this.dashboards.sources(context) };
+    }
+    async browse(context, input) {
+        await this.authorize(context);
+        const session = this.session(context, input.importId);
+        const binding = session.manifest.bindings.find(item => item.id === input.bindingId);
+        if (!binding)
+            throw new common_1.BadRequestException('DASHBOARD_BINDING_DENIED');
+        return this.dashboards.discover(context, { source: input.source, providerId: binding.providerId, request: input.request });
+    }
+    async commit(context, input) {
+        await this.authorize(context);
+        const session = this.session(context, input.importId);
+        if (session.busy)
+            throw new common_1.BadRequestException('DASHBOARD_IMPORT_RUNNING');
+        if (new Set(input.bindings.map(item => item.bindingId)).size !== input.bindings.length || input.bindings.some(item => !session.manifest.bindings.some(binding => binding.id === item.bindingId)))
+            throw new common_1.BadRequestException('DASHBOARD_IMPORT_BINDINGS_INVALID');
+        const manifest = dashboard_schema_1.dashboardSchema.parse({ ...session.manifest, id: session.newId,
+            bindings: session.manifest.bindings.map(binding => {
+                const replacement = input.bindings.find(item => item.bindingId === binding.id);
+                return replacement ? { ...binding, source: replacement.source, payload: replacement.payload } : binding;
+            }) });
+        const hash = (0, node_crypto_1.createHash)('sha256').update((0, document_package_1.encodeDashboardPackage)(manifest, session.dependencies)).digest('hex');
+        if (session.committed) {
+            if (session.committed.hash !== hash)
+                throw new common_1.BadRequestException('DASHBOARD_IMPORT_ALREADY_COMPLETED');
+            // Revalidate ownership and current access before returning an idempotent receipt.
+            await this.dashboards.open(context, session.committed.receipt.artifactId);
+            return session.committed.receipt;
+        }
+        session.busy = true;
+        try {
+            const receipt = await this.dashboards.save(context, manifest, null, 0, session.dependencies);
+            session.committed = { hash, receipt };
+            return receipt;
+        }
+        finally {
+            session.busy = false;
+        }
+    }
+    async discard(context, id) {
+        await this.authorize(context);
+        const session = this.session(context, id);
+        if (session.busy)
+            throw new common_1.BadRequestException('DASHBOARD_IMPORT_RUNNING');
+        this.imports.delete(id);
+        return { discarded: true };
+    }
+    async exportFile(context, fileKey) {
+        await this.authorize(context);
+        const match = /^archive\/([a-f0-9-]{36})\/(draft|version)\/([a-f0-9-]+)$/.exec(fileKey);
+        if (!match)
+            throw new common_1.BadRequestException('DASHBOARD_EXPORT_TARGET_INVALID');
+        const artifactId = v3_1.z.string().uuid().parse(match[1]);
+        const versionId = match[2] === 'version' ? v3_1.z.string().uuid().parse(match[3]) : undefined;
+        const revision = match[2] === 'draft' ? v3_1.z.coerce.number().int().positive().parse(match[3]) : undefined;
+        const saved = await this.dashboards.openDocument(context, artifactId, versionId, revision, versionId ? 'published' : 'draft');
+        const buffer = (0, dashboard_archive_1.encodeDashboardArchive)(saved.manifest, saved.dependencies);
+        const fileName = `${saved.manifest.title.replace(/[\\/\u0000-\u001f]/g, '_').slice(0, 100)}.xpert-dashboard.zip`;
+        const project = (0, dashboard_service_1.projectId)(context), hash = (0, node_crypto_1.createHash)('sha256').update(buffer).digest('hex');
+        const scope = { tenantId: context.tenantId, organizationId: context.organizationId, userId: context.userId,
+            ...(project ? { catalog: 'projects', scopeId: project, projectId: project } : { catalog: 'xperts', scopeId: context.hostId, xpertId: context.hostId }) };
+        const uploaded = await this.runtime.require(plugin_sdk_1.WorkspaceFilesRuntimeCapability).uploadBuffer({ ...scope, buffer, originalName: fileName,
+            fileName: `${hash}.zip`, folder: `dashboards/exports/${artifactId}`, mimeType: 'application/zip' });
+        const reference = { ...scope, source: 'platform.workspace.files', filePath: uploaded.filePath,
+            workspacePath: uploaded.filePath, originalName: fileName, mimeType: 'application/zip', size: buffer.length };
+        return { reference, fileName, mimeType: 'application/zip', size: buffer.length };
+    }
+};
+exports.DashboardArchiveService = DashboardArchiveService;
+exports.DashboardArchiveService = DashboardArchiveService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(1, (0, common_1.Inject)(plugin_sdk_1.XPERT_RUNTIME_CAPABILITIES_TOKEN)),
+    __metadata("design:paramtypes", [dashboard_service_1.DashboardService, Object])
+], DashboardArchiveService);
+function importScope(context) {
+    return JSON.stringify([context.tenantId, context.organizationId, context.userId, context.hostType, context.hostId, (0, dashboard_service_1.projectId)(context)]);
+}

package/dist/lib/content.provider.d.ts

@@ -15,7 +15,7 @@ export declare class DashboardContentProvider implements IContentResourceProvide
         providerKey: string;
         resourceId: string;
         title: string;
-        role: "owner" | "manager" | "editor" | "member";
+        role: "owner" | "manager" | "editor" | "member" | "assistant";
         canWrite: boolean;
         canManage: boolean;
     }>;

package/dist/lib/dashboard-archive.d.ts

@@ -0,0 +1,70 @@
+import type { DashboardManifest } from './dashboard.schema';
+import type { ArtifactDocumentDependencyAsset } from '@xpert-ai/plugin-sdk/artifact-document';
+export declare const MAX_DASHBOARD_ARCHIVE_BYTES = 12000000;
+export declare function dashboardRequirements(manifest: DashboardManifest): {
+    schema: string;
+    version: number;
+    bindings: {
+        id: string;
+        providerId: string;
+        operation: string;
+        contractVersion: number;
+        source: import("@xpert-ai/contracts").AnalyticsSourceRef;
+    }[];
+    externalResources: string[];
+    dynamicResourcesMayExist: boolean;
+    includesQueryResults: boolean;
+    requiresAuthorizedHost: boolean;
+};
+export declare function encodeDashboardArchive(manifest: DashboardManifest, dependencies: ArtifactDocumentDependencyAsset[]): Buffer<ArrayBuffer>;
+export declare function decodeDashboardArchive(bytes: Buffer): {
+    manifest: {
+        title: string;
+        id: string;
+        schema: "xpert.live-dashboard";
+        bindings: import("@xpert-ai/contracts").AnalyticsBinding[];
+        controls: {
+            type: "string" | "number" | "boolean" | "date";
+            controlId: string;
+            label: string;
+            defaultValue?: string | number | boolean | null | undefined;
+            allowedValues?: (string | number | boolean | null)[] | undefined;
+        }[];
+        charts: {
+            title: string;
+            type: "bar" | "line" | "area" | "pie" | "scatter";
+            id: string;
+            datasetId: string;
+            x: string;
+            y: string;
+            color?: string | undefined;
+        }[];
+        tables: {
+            title: string;
+            id: string;
+            datasetId: string;
+            fields: string[];
+        }[];
+        sourceMetadata?: {
+            bindingId: string;
+            title: string;
+            description?: string | undefined;
+        }[] | undefined;
+        components?: {
+            title: string;
+            id: string;
+            elementId: string;
+            kind: "filter" | "metric" | "chart" | "table" | "text";
+            sources: {
+                bindingId: string;
+                fieldIds?: string[] | undefined;
+            }[];
+        }[] | undefined;
+        presentation?: {
+            type: "html";
+            html: string;
+            dependencies?: import("@xpert-ai/plugin-sdk/artifact-document").ArtifactDocumentDependencyLock[] | undefined;
+        } | undefined;
+    };
+    dependencies: ArtifactDocumentDependencyAsset[];
+};

package/dist/lib/dashboard-archive.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_DASHBOARD_ARCHIVE_BYTES = void 0;
+exports.dashboardRequirements = dashboardRequirements;
+exports.encodeDashboardArchive = encodeDashboardArchive;
+exports.decodeDashboardArchive = decodeDashboardArchive;
+const node_crypto_1 = require("node:crypto");
+const fflate_1 = require("fflate");
+const v3_1 = require("zod/v3");
+const parse5_1 = require("parse5");
+const document_package_1 = require("./document-package");
+exports.MAX_DASHBOARD_ARCHIVE_BYTES = 12_000_000;
+const entryNames = ['dashboard.json', 'dashboard.html', 'requirements.json'];
+const archiveIndex = v3_1.z.object({
+    schema: v3_1.z.literal('xpert.live-dashboard.archive'), version: v3_1.z.literal(1),
+    files: v3_1.z.array(v3_1.z.object({ name: v3_1.z.enum(entryNames), bytes: v3_1.z.number().int().nonnegative().max(document_package_1.MAX_DASHBOARD_PACKAGE_BYTES), sha256: v3_1.z.string().regex(/^[a-f0-9]{64}$/) }).strict()).min(2).max(3)
+}).strict();
+const hash = (value) => (0, node_crypto_1.createHash)('sha256').update(value).digest('hex');
+function dashboardRequirements(manifest) {
+    const externalResources = new Set();
+    const visit = (node) => {
+        if ('attrs' in node)
+            for (const attr of node.attrs) {
+                if (['src', 'href'].includes(attr.name) && /^(https?:)?\/\//i.test(attr.value))
+                    externalResources.add(attr.value);
+            }
+        if ('childNodes' in node)
+            node.childNodes.forEach(visit);
+    };
+    if (manifest.presentation)
+        visit((0, parse5_1.parse)(manifest.presentation.html));
+    return { schema: 'xpert.live-dashboard.requirements', version: 1,
+        bindings: manifest.bindings.map(({ id, providerId, operation, contractVersion, source }) => ({ id, providerId, operation, contractVersion, source })),
+        externalResources: [...externalResources], dynamicResourcesMayExist: !!manifest.presentation,
+        includesQueryResults: false, requiresAuthorizedHost: true };
+}
+function encodeDashboardArchive(manifest, dependencies) {
+    const entries = {
+        'dashboard.json': (0, document_package_1.encodeDashboardPackage)(manifest, dependencies),
+        'requirements.json': Buffer.from(JSON.stringify(dashboardRequirements(manifest), null, 2))
+    };
+    if (entries['dashboard.json'].length > document_package_1.MAX_DASHBOARD_PACKAGE_BYTES)
+        throw new Error('DASHBOARD_PACKAGE_TOO_LARGE');
+    if (manifest.presentation)
+        entries['dashboard.html'] = Buffer.from(manifest.presentation.html);
+    const index = { schema: 'xpert.live-dashboard.archive', version: 1,
+        files: Object.entries(entries).map(([name, bytes]) => ({ name, bytes: bytes.length, sha256: hash(bytes) })) };
+    entries['package.json'] = Buffer.from(JSON.stringify(index, null, 2));
+    const bytes = Buffer.from((0, fflate_1.zipSync)(entries, { level: 6 }));
+    if (bytes.length > exports.MAX_DASHBOARD_ARCHIVE_BYTES)
+        throw new Error('DASHBOARD_ARCHIVE_TOO_LARGE');
+    return bytes;
+}
+/** Never extracts paths to disk. Bound both advertised and actually inflated bytes. */
+function unzipBounded(bytes) {
+    const files = new Map(), seen = new Set();
+    let total = 0, active = 0, failed;
+    const unzip = new fflate_1.Unzip(file => {
+        if (seen.has(file.name) || !['package.json', ...entryNames].includes(file.name) || (file.originalSize ?? 0) > document_package_1.MAX_DASHBOARD_PACKAGE_BYTES)
+            throw new Error('DASHBOARD_ARCHIVE_ENTRY_INVALID');
+        seen.add(file.name);
+        active++;
+        const chunks = [];
+        let size = 0;
+        file.ondata = (error, data, final) => {
+            if (error) {
+                failed = error;
+                file.terminate();
+                return;
+            }
+            size += data.length;
+            total += data.length;
+            if (size > document_package_1.MAX_DASHBOARD_PACKAGE_BYTES || total > exports.MAX_DASHBOARD_ARCHIVE_BYTES) {
+                failed = new Error('DASHBOARD_ARCHIVE_TOO_LARGE');
+                file.terminate();
+                return;
+            }
+            chunks.push(data);
+            if (final) {
+                files.set(file.name, Buffer.concat(chunks));
+                active--;
+            }
+        };
+        file.start();
+    });
+    unzip.register(fflate_1.UnzipInflate);
+    for (let offset = 0; offset < bytes.length; offset += 1024) {
+        unzip.push(bytes.subarray(offset, offset + 1024), offset + 1024 >= bytes.length);
+        if (failed)
+            throw failed;
+    }
+    if (active || !files.has('package.json') || !files.has('dashboard.json') || !files.has('requirements.json'))
+        throw new Error('DASHBOARD_ARCHIVE_INCOMPLETE');
+    return files;
+}
+function decodeDashboardArchive(bytes) {
+    if (bytes.length > exports.MAX_DASHBOARD_ARCHIVE_BYTES)
+        throw new Error('DASHBOARD_ARCHIVE_TOO_LARGE');
+    if (bytes[0] !== 0x50 || bytes[1] !== 0x4b)
+        return (0, document_package_1.decodeDashboardPackage)(bytes);
+    const files = unzipBounded(bytes);
+    const index = archiveIndex.parse(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(files.get('package.json'))));
+    if (new Set(index.files.map(entry => entry.name)).size !== index.files.length || files.size !== index.files.length + 1)
+        throw new Error('DASHBOARD_ARCHIVE_ENTRY_INVALID');
+    for (const entry of index.files) {
+        const file = files.get(entry.name);
+        if (!file || file.length !== entry.bytes || hash(file) !== entry.sha256)
+            throw new Error('DASHBOARD_ARCHIVE_INTEGRITY_FAILED');
+    }
+    if (!index.files.some(entry => entry.name === 'dashboard.json') || !index.files.some(entry => entry.name === 'requirements.json'))
+        throw new Error('DASHBOARD_ARCHIVE_INCOMPLETE');
+    const result = (0, document_package_1.decodeDashboardPackage)(files.get('dashboard.json'));
+    if (result.manifest.presentation ? !files.get('dashboard.html')?.equals(Buffer.from(result.manifest.presentation.html)) : files.has('dashboard.html'))
+        throw new Error('DASHBOARD_ARCHIVE_HTML_MISMATCH');
+    if (!files.get('requirements.json')?.equals(Buffer.from(JSON.stringify(dashboardRequirements(result.manifest), null, 2))))
+        throw new Error('DASHBOARD_ARCHIVE_REQUIREMENTS_MISMATCH');
+    return result;
+}

package/dist/lib/dashboard-sources.d.ts

@@ -0,0 +1,69 @@
+import { z } from 'zod/v3';
+import type { DashboardManifest } from './dashboard.schema';
+export declare const componentId: z.ZodString;
+export declare const sourceMetadataSchema: z.ZodArray<z.ZodObject<{
+    bindingId: z.ZodString;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    bindingId: string;
+    title: string;
+    description?: string | undefined;
+}, {
+    bindingId: string;
+    title: string;
+    description?: string | undefined;
+}>, "many">;
+export declare const dashboardComponentsSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    elementId: z.ZodString;
+    title: z.ZodString;
+    kind: z.ZodEnum<["metric", "chart", "table", "filter", "text"]>;
+    sources: z.ZodArray<z.ZodObject<{
+        bindingId: z.ZodString;
+        fieldIds: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        bindingId: string;
+        fieldIds?: string[] | undefined;
+    }, {
+        bindingId: string;
+        fieldIds?: string[] | undefined;
+    }>, "many">;
+}, "strict", z.ZodTypeAny, {
+    title: string;
+    id: string;
+    elementId: string;
+    kind: "filter" | "metric" | "chart" | "table" | "text";
+    sources: {
+        bindingId: string;
+        fieldIds?: string[] | undefined;
+    }[];
+}, {
+    title: string;
+    id: string;
+    elementId: string;
+    kind: "filter" | "metric" | "chart" | "table" | "text";
+    sources: {
+        bindingId: string;
+        fieldIds?: string[] | undefined;
+    }[];
+}>, "many">;
+export type DashboardComponent = z.infer<typeof dashboardComponentsSchema>[number];
+export declare function dashboardComponents(manifest: DashboardManifest): DashboardComponent[];
+export declare function dashboardSources(manifest: DashboardManifest): {
+    binding: import("@xpert-ai/contracts").AnalyticsBinding;
+    title: string;
+    description: string | undefined;
+    components: {
+        title: string;
+        id: string;
+        elementId: string;
+        kind: "filter" | "metric" | "chart" | "table" | "text";
+        sources: {
+            bindingId: string;
+            fieldIds?: string[] | undefined;
+        }[];
+    }[];
+}[];
+/** A rendering projection never exposes provider-native query configuration to a viewer. */
+export declare function publicDashboardManifest(manifest: DashboardManifest): DashboardManifest;

package/dist/lib/dashboard-sources.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashboardComponentsSchema = exports.sourceMetadataSchema = exports.componentId = void 0;
+exports.dashboardComponents = dashboardComponents;
+exports.dashboardSources = dashboardSources;
+exports.publicDashboardManifest = publicDashboardManifest;
+const v3_1 = require("zod/v3");
+exports.componentId = v3_1.z.string().regex(/^[A-Za-z][A-Za-z0-9_.-]{0,79}$/);
+exports.sourceMetadataSchema = v3_1.z.array(v3_1.z.object({
+    bindingId: exports.componentId, title: v3_1.z.string().min(1).max(160), description: v3_1.z.string().max(2000).optional()
+}).strict()).max(8);
+exports.dashboardComponentsSchema = v3_1.z.array(v3_1.z.object({
+    id: exports.componentId, elementId: exports.componentId, title: v3_1.z.string().min(1).max(160),
+    kind: v3_1.z.enum(['metric', 'chart', 'table', 'filter', 'text']),
+    sources: v3_1.z.array(v3_1.z.object({ bindingId: exports.componentId, fieldIds: v3_1.z.array(exports.componentId).max(80).optional() }).strict()).max(8)
+}).strict()).max(160);
+function dashboardComponents(manifest) {
+    if (manifest.presentation)
+        return manifest.components ?? [];
+    return [...manifest.charts, ...manifest.tables].map(view => ({
+        id: view.id, elementId: view.id, title: view.title, kind: 'fields' in view ? 'table' : 'chart',
+        sources: manifest.bindings.filter(binding => binding.output.datasetId === view.datasetId)
+            .map(binding => ({ bindingId: binding.id, fieldIds: 'fields' in view ? view.fields : [view.x, view.y, ...(view.color ? [view.color] : [])] }))
+    }));
+}
+function dashboardSources(manifest) {
+    const components = dashboardComponents(manifest);
+    return manifest.bindings.map(binding => ({
+        binding, title: manifest.sourceMetadata?.find(item => item.bindingId === binding.id)?.title ?? binding.id,
+        description: manifest.sourceMetadata?.find(item => item.bindingId === binding.id)?.description,
+        components: components.filter(component => component.sources.some(source => source.bindingId === binding.id))
+    }));
+}
+/** A rendering projection never exposes provider-native query configuration to a viewer. */
+function publicDashboardManifest(manifest) {
+    return { ...manifest, bindings: manifest.bindings.map(binding => ({ ...binding, payload: {} })) };
+}