@easyai-canvas/canvas-plugin-sdk 0.1.0

package/dist/protocol/index.d.ts

@@ -0,0 +1,295 @@
+/** Public, dependency-free contract. Host copies are generated by protocol:sync. */
+export declare const PROTOCOL: "easyai.plugin/v1";
+/** Host-provided theme for plugin nodes; plugins cannot publish native UI configuration. */
+export type CanvasColorTokens = Partial<Record<'primary' | 'canvasBackground' | 'panelBackground' | 'textPrimary' | 'textSecondary' | 'borderColor', string>>;
+export type PluginNodeTheme = {
+    mode?: 'light' | 'dark';
+    theme?: {
+        typography?: {
+            fontFamily?: 'system' | 'sans' | 'serif' | 'mono';
+            fontSize?: number;
+        };
+        shape?: {
+            controlRadius?: number;
+            panelRadius?: number;
+            nodeRadius?: number;
+        };
+        light?: CanvasColorTokens;
+        dark?: CanvasColorTokens;
+    };
+};
+export type PortType = 'text' | 'json' | 'image' | 'video' | 'audio' | 'file' | 'any';
+export type DataPacket = {
+    type: PortType;
+    payload: Record<string, unknown>;
+    source?: {
+        nodeId: string;
+        portId: string;
+        timestamp: string;
+    };
+};
+export type Port = {
+    id: string;
+    type: PortType;
+    required?: boolean;
+    multiple?: boolean;
+};
+export type ConfigField = {
+    key: string;
+    label: string;
+    type: 'string' | 'number' | 'boolean' | 'select' | 'secret';
+    default?: unknown;
+    options?: {
+        label: string;
+        value: string;
+    }[];
+    required?: boolean;
+};
+export type PluginMenuContribution = {
+    group: 'basic' | 'storyboard' | 'tools' | 'resources';
+    order?: number;
+    icon?: string;
+};
+export type PluginRuntimeContext = {
+    user: {
+        id: string;
+        username?: string;
+        ssoId?: string;
+        tenantId?: string;
+    };
+    projectId?: string;
+    nodeId?: string;
+    environment: 'canvas';
+};
+export type PluginDocumentStateCapability = {
+    key: string;
+    schema?: string;
+    maxBytes?: number;
+    /** Optional legacy host fields updated after a result is durably delivered. */
+    renderedRevisionKey?: string;
+    resultKey?: string;
+    subtitleResultKey?: string;
+};
+export type PluginNodeCapabilities = {
+    documentState?: PluginDocumentStateCapability;
+    workspace?: boolean;
+    mediaUpload?: boolean;
+    inputManagement?: boolean;
+    outputToCanvas?: boolean;
+};
+export type PluginNodeRuntimePolicy = {
+    safeRetry?: boolean;
+    maxAttempts?: number;
+    maxQueuedPerUser?: number;
+    maxQueued?: number;
+};
+export type NodeDefinition = {
+    type: string;
+    name: string;
+    description?: string;
+    inputs: Port[];
+    outputs: Port[];
+    parameters?: ConfigField[];
+    execution: 'remote' | 'source' | 'display' | 'confirmed';
+    ui?: {
+        preview?: string;
+        panel?: string;
+        actions?: string;
+    };
+    defaults?: Record<string, unknown>;
+    timeoutMs?: number;
+    menu?: PluginMenuContribution;
+    capabilities?: PluginNodeCapabilities;
+    runtime?: PluginNodeRuntimePolicy;
+};
+export type AssetSource = {
+    id: string;
+    name: string;
+    description?: string;
+    url?: string;
+    origin?: string;
+    mediaTypes: PortType[];
+    ui?: {
+        selector: string;
+    };
+    menu?: PluginMenuContribution;
+};
+export type PluginAction = {
+    id: string;
+    name: string;
+    description?: string;
+    action: 'asset-selection';
+    presentation: 'dialog';
+    mediaTypes: Array<'image' | 'video' | 'audio' | 'file'>;
+    maxCount?: number;
+    ui: {
+        component?: string;
+        url?: string;
+        origin?: string;
+    };
+    menu: PluginMenuContribution;
+    /** Set only on the normalized view returned by listPluginActions(). */
+    legacyAssetSource?: boolean;
+};
+export type PluginManifest = {
+    protocol: typeof PROTOCOL;
+    id: string;
+    name: string;
+    release: string;
+    configFields?: ConfigField[];
+    contributes: {
+        nodes?: NodeDefinition[];
+        actions?: PluginAction[];
+        assetSources?: AssetSource[];
+    };
+};
+export type PluginUiBundle = {
+    url: string;
+    digest: string;
+    globalName: string;
+    cssUrl?: string;
+    cssDigest?: string;
+};
+export type CatalogEntry = {
+    packageDigest?: string;
+    uiBundle?: PluginUiBundle;
+    manifest: PluginManifest;
+    enabled: boolean;
+    config: Record<string, unknown>;
+    /** Optimistic-lock version for this service instance's plugin configuration. */
+    configVersion?: number;
+    /** Secret values are never returned; only their configured state is exposed. */
+    secretConfigured?: Record<string, boolean>;
+    configCheckAvailable?: boolean;
+};
+export type Catalog = {
+    protocol: typeof PROTOCOL;
+    revision: number;
+    /** Stable identity for the currently running plugin-service data directory. */
+    instanceId?: string;
+    plugins: CatalogEntry[];
+};
+export type HostFilesCapability = {
+    /** Trusted host endpoint. The plugin service rejects non-HTTPS remote capabilities. */
+    baseUrl: string;
+    /** Short-lived, task-bound bearer grant. It must never be written to execution records. */
+    grant: string;
+    expiresAt: number;
+    /** Optional explicit route for the host file capability. */
+    path?: '/v1/plugin-artifacts';
+};
+export type ExecutionRequest = {
+    executionId: string;
+    pluginId: string;
+    nodeType: string;
+    parameters: Record<string, unknown>;
+    inputsByPort: Record<string, DataPacket[]>;
+    document?: {
+        key: string;
+        schema?: string;
+        revision: string;
+        value: unknown;
+    };
+    context: {
+        nodeId: string;
+        taskId?: string;
+        userId: string;
+        projectId?: string;
+        runtime?: PluginRuntimeContext;
+    };
+    host?: {
+        files?: HostFilesCapability;
+    };
+};
+export type PluginQueryRequest = {
+    input: Record<string, unknown>;
+    context: PluginRuntimeContext;
+};
+export type ExecutionResult = {
+    outputs: Record<string, DataPacket>;
+    parameters?: Record<string, unknown>;
+    documentRevision?: string;
+    phase?: string;
+};
+export type ExecutionStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'interrupted';
+export type ExecutionRecord = {
+    executionId: string;
+    pluginId: string;
+    nodeType: string;
+    status: ExecutionStatus;
+    progress: number;
+    phase?: string;
+    attempt: number;
+    maxAttempts: number;
+    cancelRequested: boolean;
+    result?: ExecutionResult;
+    error?: {
+        code: string;
+        message: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+};
+export type SelectedResource = {
+    url: string;
+    type: 'image' | 'video' | 'audio' | 'file';
+    name?: string;
+    mimeType?: string;
+    size?: number;
+    width?: number;
+    height?: number;
+    duration?: number;
+    sourceId?: string;
+};
+export type HostSnapshot = {
+    revision: number;
+    plugins: Array<{
+        installationId?: string;
+        installationRevision?: number;
+        deployment?: 'hosted' | 'remote';
+        serviceId: string;
+        entry: CatalogEntry;
+        enabled: boolean;
+        uiBundle?: {
+            url: string;
+            digest: string;
+            globalName: string;
+            cssUrl?: string;
+            cssDigest?: string;
+        };
+    }>;
+};
+export declare class ContractError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(message: string, status?: number, code?: string);
+}
+export declare function object(value: unknown, path?: string): Record<string, unknown>;
+export declare function validatePluginRuntimeContext(value: unknown): PluginRuntimeContext;
+export declare function identifier(value: unknown, path: string): string;
+export declare function validateParameters(fields: ConfigField[], input: Record<string, unknown>): Record<string, unknown>;
+/** Returns the interaction-oriented view while preserving legacy asset source manifests. */
+export declare function listPluginActions(manifest: PluginManifest): PluginAction[];
+export declare function validateManifest(value: unknown): PluginManifest;
+export declare function validatePacket(value: unknown, expected?: PortType): DataPacket;
+export declare function validateExecution(value: unknown, node: NodeDefinition): ExecutionRequest;
+export declare function validateResult(value: unknown, node: NodeDefinition): ExecutionResult;
+export declare function validateSelectedResources(resources: unknown, allowedTypes: string[], limit: number): SelectedResource[];
+/** One outstanding iframe selection. A caller must cancel on close/unmount. */
+export declare class AssetSelectionSession {
+    readonly requestId: string;
+    private origin;
+    private source;
+    private allowedTypes;
+    private limit;
+    private closed;
+    constructor(requestId: string, origin: string, source: unknown, allowedTypes: string[], limit: number);
+    cancel(): void;
+    receive(event: {
+        origin: string;
+        source: unknown;
+        data: unknown;
+    }): SelectedResource[] | undefined;
+}
+/** Confirmation binds semantic input content, not transport timestamps or object key order. */
+export declare function confirmationPayload(parameters: Record<string, unknown>, inputs: Record<string, DataPacket[]>): string;