@dp-bohrium/widget-contracts 0.0.1

package/dist/generated-runtime-contracts.d.ts

@@ -0,0 +1,401 @@
+/** GENERATED FILE. Do not edit directly. */
+export type WidgetSlot = ("tool-result" | "file-preview" | "panel");
+export type RenderRequest = (ToolResultRenderRequest | FilePreviewRenderRequest | PanelRenderRequest);
+export type ToolResultRenderRequest = (RenderRequestBase & {
+    slot: "tool-result";
+    content: ToolResultContent;
+});
+export type RenderState = ("loading" | "partial" | "complete" | "error");
+export type ThemeMode = ("light" | "dark");
+export type GrantedCapability = ({
+    name: "files.list";
+    limits: {
+        pageSize: number;
+        callsPerMinute: number;
+    };
+} | {
+    name: "files.metadata";
+    limits: {
+        callsPerMinute: number;
+    };
+} | {
+    name: "files.read";
+    limits: {
+        bytesPerRequest: number;
+        bytesPerRun: number;
+        callsPerMinute: number;
+    };
+} | {
+    name: "events.read";
+    /**
+     * @minItems 1
+     * @maxItems 32
+     */
+    topics: [string, ...(string)[]];
+    limits: {
+        callsPerMinute: number;
+        pageSize: number;
+        minPollMs: number;
+    };
+} | {
+    name: "actions.invoke";
+    /**
+     * @minItems 1
+     * @maxItems 32
+     */
+    actions: [string, ...(string)[]];
+    limits: {
+        callsPerMinute: number;
+    };
+} | {
+    name: "network.fetch";
+    limits: WidgetNetworkLimits;
+} | GrantedPresentationCapability);
+export type PositiveInteger = number;
+export type JsonValue = (null | boolean | number | string | JsonValue[] | {
+    [k: string]: JsonValue;
+});
+export type FilePreviewRenderRequest = (RenderRequestBase & {
+    slot: "file-preview";
+    content: FilePreviewContent;
+});
+export type PanelRenderRequest = (RenderRequestBase & {
+    slot: "panel";
+    content: PanelContent;
+});
+export type HostToWidgetMessage = (InitMessage | RenderMessage | CapabilityResultMessage | ErrorMessage | DisposeMessage);
+export type InitMessage = (BridgeEnvelopeBase & {
+    type: "init";
+    payload: InitPayload;
+});
+export type RenderMessage = (BridgeEnvelopeBase & {
+    type: ("render" | "update");
+    payload: RenderRequest;
+});
+export type CapabilityResultMessage = (BridgeEnvelopeBase & {
+    type: "capability-result";
+    payload: {
+        requestId: string;
+        result: CapabilityResult;
+    };
+});
+export type CapabilityResult = ({
+    ok: true;
+    data: JsonValue;
+} | {
+    ok: false;
+    reason: ("unsupported" | "permission-denied" | "resource-limit" | "invalid-reference" | "timeout" | "internal-error" | "network-consent-denied" | "network-policy-denied" | "network-transport-unavailable" | "network-request-too-large" | "network-response-too-large" | "network-rate-limited" | "network-redirect-denied" | "network-credential-unavailable" | "network-scope-invalid" | "network-dns-denied" | "network-error");
+    message: string;
+    retryable: boolean;
+});
+export type ErrorMessage = (BridgeEnvelopeBase & {
+    type: "error";
+    payload: WidgetError;
+});
+export type DisposeMessage = (BridgeEnvelopeBase & {
+    type: "dispose";
+    payload: {
+        reason: string;
+        deadlineMs: number;
+    };
+});
+export type WidgetToHostMessage = (ReadyMessage | ResizeMessage | CapabilityRequestMessage | ErrorMessage);
+export type ReadyMessage = (BridgeEnvelopeBase & {
+    type: "ready";
+    payload: {
+        widgetSdkVersion: string;
+        hostApiVersion: 1;
+    };
+});
+export type ResizeMessage = (BridgeEnvelopeBase & {
+    type: "resize";
+    payload: {
+        width: number;
+        height: number;
+    };
+});
+export type CapabilityRequestMessage = (BridgeEnvelopeBase & {
+    type: "capability-request";
+    payload: {
+        requestId: string;
+        request: CapabilityRequest;
+    };
+});
+export type CapabilityRequest = ({
+    operation: "files.list";
+    input: {
+        directory: FileReference;
+        cursor?: string;
+        limit?: number;
+    };
+} | {
+    operation: "files.metadata";
+    input: {
+        reference: FileReference;
+    };
+} | {
+    operation: "files.read";
+    input: {
+        file: FileReference;
+        offset: number;
+        length: number;
+        encoding: ("utf8" | "base64");
+    };
+} | {
+    operation: "events.read";
+    input: {
+        topic: string;
+        cursor?: string;
+        limit: number;
+    };
+} | {
+    operation: "actions.invoke";
+    input: {
+        action: string;
+        idempotencyKey: string;
+        arguments: JsonValue;
+    };
+} | {
+    operation: "network.fetch";
+    input: WidgetNetworkFetchInput;
+} | PresentationCapabilityRequest);
+export type PresentationCapabilityRequest = ({
+    operation: "ui.presentation";
+    input: ({
+        action: ("present" | "change-surface");
+        surface: ("workspace" | "floating" | "overlay");
+    } | {
+        action: "close";
+    });
+} | FocusBoundaryPresentationCapabilityRequest);
+export type FocusBoundaryPresentationCapabilityRequest = {
+    operation: "ui.presentation";
+    input: {
+        action: "focus-boundary";
+        direction: ("forward" | "backward");
+    };
+};
+export type PresentationCapabilityOutput = ({
+    action: ("present" | "change-surface");
+    surface: ("workspace" | "floating" | "overlay");
+} | {
+    action: "close";
+} | {
+    action: "focus-boundary";
+    direction: ("forward" | "backward");
+});
+export type PresentationCapabilityResult = ({
+    ok: true;
+    data: PresentationCapabilityOutput;
+} | {
+    ok: false;
+    reason: ("unsupported" | "permission-denied" | "resource-limit" | "invalid-reference" | "timeout" | "internal-error" | "network-consent-denied" | "network-policy-denied" | "network-transport-unavailable" | "network-request-too-large" | "network-response-too-large" | "network-rate-limited" | "network-redirect-denied" | "network-credential-unavailable" | "network-scope-invalid" | "network-dns-denied" | "network-error");
+    message: string;
+    retryable: boolean;
+});
+export interface WidgetRuntimeContracts {
+    widgetSlot: WidgetSlot;
+    renderRequest: RenderRequest;
+    hostToWidgetMessage: HostToWidgetMessage;
+    widgetToHostMessage: WidgetToHostMessage;
+    capabilityRequest: CapabilityRequest;
+    capabilityResult: CapabilityResult;
+    widgetError: WidgetError;
+    resourceBudget: ResourceBudget;
+    widgetEventBatch?: WidgetEventBatch;
+    toolLifecycleEvent?: ToolLifecycleEvent;
+    widgetNetworkFetchOutput?: WidgetNetworkFetchOutput;
+    presentationCapabilityOutput?: PresentationCapabilityOutput;
+    presentationCapabilityResult?: PresentationCapabilityResult;
+}
+export interface RenderRequestBase {
+    schemaVersion: 1;
+    requestId: string;
+    instanceId: string;
+    revision: number;
+    state: RenderState;
+    context: WidgetRenderContext;
+}
+export interface WidgetRenderContext {
+    locale: string;
+    theme: Theme;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    capabilities: GrantedCapability[];
+    correlationId: string;
+}
+export interface Theme {
+    mode: ThemeMode;
+    tokens: {
+        background: string;
+        foreground: string;
+        muted: string;
+        mutedForeground: string;
+        border: string;
+        primary: string;
+        danger: string;
+    };
+}
+export interface WidgetNetworkLimits {
+    timeoutMs: PositiveInteger;
+    maxRedirects: PositiveInteger;
+    maxConcurrentRequests: PositiveInteger;
+    callsPerMinute: PositiveInteger;
+    requestHeaderBytes: PositiveInteger;
+    responseHeaderBytes: PositiveInteger;
+    requestBodyBytes: PositiveInteger;
+    responseBodyBytes: PositiveInteger;
+}
+export interface GrantedPresentationCapability {
+    name: "ui.presentation";
+    /**
+     * @minItems 1
+     * @maxItems 2
+     */
+    surfaces: [("floating" | "overlay")] | [("floating" | "overlay"), ("floating" | "overlay")];
+    requiresHostConfirmation: true;
+}
+export interface ToolResultContent {
+    slot: "tool-result";
+    tool: {
+        name: string;
+        callId: string;
+        status: ("running" | "succeeded" | "failed" | "cancelled");
+    };
+    input: JsonValue;
+    result?: JsonValue;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface FilePreviewContent {
+    slot: "file-preview";
+    file: FileReference;
+    preview?: JsonValue;
+}
+export interface FileReference {
+    id: string;
+    kind: ("file" | "directory");
+    name: string;
+    extension?: string;
+    mimeType?: string;
+    size?: number;
+}
+export interface PanelContent {
+    slot: "panel";
+    panelType: string;
+    title?: string;
+    data: JsonValue;
+}
+export interface BridgeEnvelopeBase {
+    protocolVersion: 1;
+    channelId: string;
+    messageId: string;
+    sequence: number;
+}
+export interface InitPayload {
+    instanceId: string;
+    locale: string;
+    theme: Theme;
+    capabilities: GrantedCapability[];
+    resourceBudget: ResourceBudget;
+}
+export interface ResourceBudget {
+    version: 1;
+    bundle: {
+        compressedBytes: number;
+        expandedBytes: number;
+        fileCount: number;
+        singleFileBytes: number;
+    };
+    bridge: {
+        messageBytes: number;
+        messagesPerSecond: number;
+        pendingRequests: number;
+    };
+    files: {
+        readBytesPerRequest: number;
+        readBytesPerRun: number;
+        callsPerMinute: number;
+        listPageSize: number;
+    };
+    timeouts: {
+        bundleLoadMs: number;
+        handshakeMs: number;
+        firstRenderMs: number;
+        updateMs: number;
+        capabilityMs: number;
+        disposeGraceMs: number;
+    };
+    concurrency: {
+        activeIframesPerPage: number;
+        activeIframesPerRun: number;
+        hiddenRecycleMs: number;
+    };
+    retry: {
+        maxAttempts: number;
+        initialDelayMs: number;
+        maxDelayMs: number;
+        totalMs: number;
+    };
+    failure: {
+        consecutiveFailures: number;
+        windowMs: number;
+    };
+}
+export interface WidgetError {
+    code: ("BUNDLE_LOAD_FAILED" | "DIGEST_MISMATCH" | "RUNTIME_CONFIG_EXPIRED" | "WIDGET_VERSION_REVOKED" | "HOST_API_UNSUPPORTED" | "HANDSHAKE_TIMEOUT" | "MESSAGE_INVALID" | "CHANNEL_MISMATCH" | "MESSAGE_TOO_LARGE" | "MESSAGE_RATE_LIMITED" | "TOO_MANY_PENDING_REQUESTS" | "CAPABILITY_UNDECLARED" | "CAPABILITY_DENIED" | "CAPABILITY_UNSUPPORTED" | "CAPABILITY_TIMEOUT" | "FILE_REFERENCE_INVALID" | "FILE_PERMISSION_DENIED" | "RESOURCE_LIMIT" | "RENDER_FAILED" | "UPDATE_FAILED" | "WIDGET_CRASHED" | "INSTANCE_DISPOSED");
+    phase: ("load" | "handshake" | "render" | "update" | "capability" | "dispose");
+    message: string;
+    retryable: boolean;
+    correlationId: string;
+}
+export interface WidgetNetworkFetchInput {
+    url: string;
+    auth: ("none" | "optional" | "required");
+    method?: ("GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE");
+    headers?: WidgetNetworkRequestHeaders;
+    body?: string;
+    bodyEncoding?: ("utf8" | "base64");
+    redirect?: ("follow" | "manual" | "error");
+}
+export interface WidgetNetworkRequestHeaders {
+    [k: string]: string;
+}
+export interface WidgetEventBatch {
+    schemaVersion: 1;
+    topic: string;
+    cursor: string;
+    reset: boolean;
+    hasMore: boolean;
+    /**
+     * @maxItems 100
+     */
+    events: WidgetEvent[];
+    snapshot?: JsonValue;
+}
+export interface WidgetEvent {
+    id: string;
+    type: string;
+    payload: JsonValue;
+}
+export interface ToolLifecycleEvent {
+    toolCallId: string;
+    toolName: string;
+    phase: ("started" | "completed" | "failed" | "cancelled");
+}
+export interface WidgetNetworkFetchOutput {
+    status: number;
+    statusText: string;
+    headers: NetworkHeaders;
+    body: string;
+    bodyEncoding: ("utf8" | "base64");
+    finalUrl: string;
+    redirected: boolean;
+}
+export interface NetworkHeaders {
+    [k: string]: string;
+}

package/dist/generated-runtime-contracts.js

@@ -0,0 +1,3 @@
+/* eslint-disable */
+/** GENERATED FILE. Do not edit directly. */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/** Public Widget contract surface. Runtime host/client APIs are deferred. */
+import type { FallbackBinding, LoadableBinding } from "./generated-host-runtime-config.js";
+import type { BridgeEnvelopeBase, GrantedCapability, HostToWidgetMessage, RenderRequest, WidgetError, WidgetToHostMessage } from "./generated-runtime-contracts.js";
+/**
+ * Every type is re-exported from the module generated out of the schema that
+ * owns it. The Host Config module also contains inlined `$ref` copies of
+ * Manifest and Runtime definitions; re-exporting those copies would let the
+ * public surface drift from the canonical contract.
+ */
+export type { FallbackBinding, LoadableBinding, NetworkAuthority, RuntimeAuthority, WidgetHostRuntimeConfig, } from "./generated-host-runtime-config.js";
+export type { RequestedPresentationCapability, WidgetManifest, WidgetSlotConfig, } from "./generated-manifest.js";
+export type { BridgeEnvelopeBase, CapabilityRequest, CapabilityRequestMessage, CapabilityResult, CapabilityResultMessage, DisposeMessage, ErrorMessage, FilePreviewContent, FilePreviewRenderRequest, FileReference, FocusBoundaryPresentationCapabilityRequest, GrantedCapability, GrantedPresentationCapability, HostToWidgetMessage, InitMessage, InitPayload, JsonValue, PanelContent, PanelRenderRequest, PresentationCapabilityOutput, PresentationCapabilityRequest, PresentationCapabilityResult, ReadyMessage, RenderMessage, RenderRequest, RenderRequestBase, RenderState, ResizeMessage, ResourceBudget, Theme, ThemeMode, ToolLifecycleEvent, ToolResultContent, ToolResultRenderRequest, WidgetError, WidgetEvent, WidgetEventBatch, WidgetNetworkFetchInput, WidgetNetworkFetchOutput, WidgetNetworkLimits, WidgetRenderContext, WidgetSlot, WidgetToHostMessage, } from "./generated-runtime-contracts.js";
+export type HostApiVersion = 1;
+export type WidgetRenderRequest = RenderRequest;
+export type WidgetProtocolMessage = HostToWidgetMessage | WidgetToHostMessage;
+export type ReadonlyFileCapability = Extract<GrantedCapability["name"], `files.${string}`>;
+export type WidgetErrorCode = WidgetError["code"];
+export type BridgeEnvelope<TType extends string = string, TPayload = unknown> = BridgeEnvelopeBase & {
+    type: TType;
+    payload: TPayload;
+};
+export type ResolvedWidgetBinding = LoadableBinding | FallbackBinding;

package/dist/index.js

@@ -0,0 +1,2 @@
+/** Public Widget contract surface. Runtime host/client APIs are deferred. */
+export {};

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@dp-bohrium/widget-contracts",
+  "version": "0.0.1",
+  "description": "Versioned Widget schemas and generated contract types.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./schemas/*.json": "./schemas/*.json",
+    "./conformance/*": "./conformance/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "conformance",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "ajv": "^8.17.1",
+    "@biomejs/biome": "^2.2.0",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@types/node": "^22.15.0",
+    "json-schema-to-typescript": "^15.0.4",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "generate:types": "node ../../scripts/schema/generate-types.mjs",
+    "schema:check": "node ../../scripts/schema/generate-types.mjs --check && node ../../scripts/schema/check-drift.mjs",
+    "typecheck": "node ../../scripts/schema/generate-types.mjs --check && tsc --noEmit",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "lint": "biome check src test",
+    "format:check": "biome check --linter-enabled=false src test",
+    "build": "tsc -b tsconfig.build.json --pretty false",
+    "check:surface": "node ../../scripts/quality/check-contract-surface.mjs",
+    "check:no-coupling": "node ../../scripts/quality/check-no-coupling.mjs",
+    "pack:check": "pnpm pack --pack-destination ../../.artifacts",
+    "package:contents": "node ../../scripts/quality/check-package-contents.mjs ../../.artifacts/dp-bohrium-widget-contracts-*.tgz",
+    "check": "pnpm schema:check && pnpm check:surface && pnpm check:no-coupling && pnpm typecheck && pnpm test && pnpm lint && pnpm format:check && pnpm build"
+  }
+}

package/schemas/host-runtime-config.schema.json

@@ -0,0 +1,185 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "host-runtime-config.schema.json",
+  "title": "Widget Host Runtime Config",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion",
+    "hostApiVersion",
+    "configId",
+    "runId",
+    "mode",
+    "issuedAt",
+    "expiresAt",
+    "recheckAt",
+    "securityProfile",
+    "resourceBudget",
+    "runtime",
+    "network",
+    "bindings"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "hostApiVersion": { "const": 1 },
+    "configId": { "$ref": "#/$defs/Identifier" },
+    "runId": { "$ref": "#/$defs/Identifier" },
+    "mode": { "$ref": "#/$defs/Mode" },
+    "issuedAt": { "$ref": "#/$defs/Timestamp" },
+    "expiresAt": { "$ref": "#/$defs/Timestamp" },
+    "recheckAt": { "$ref": "#/$defs/Timestamp" },
+    "securityProfile": { "const": "runtime-security-profile-v1" },
+    "resourceBudget": {
+      "$ref": "widget-runtime-contracts.schema.json#/$defs/ResourceBudget"
+    },
+    "runtime": { "$ref": "#/$defs/RuntimeAuthority" },
+    "network": { "$ref": "#/$defs/NetworkAuthority" },
+    "bindings": {
+      "type": "array",
+      "items": {
+        "oneOf": [
+          { "$ref": "#/$defs/LoadableBinding" },
+          { "$ref": "#/$defs/FallbackBinding" }
+        ]
+      }
+    }
+  },
+  "$defs": {
+    "LoadableBinding": {
+      "title": "LoadableBinding",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "bindingId",
+        "widgetId",
+        "widgetVersionId",
+        "digest",
+        "manifest",
+        "launch",
+        "grantedCapabilities"
+      ],
+      "properties": {
+        "status": { "const": "loadable" },
+        "bindingId": { "$ref": "#/$defs/Identifier" },
+        "widgetId": { "$ref": "#/$defs/Identifier" },
+        "widgetVersionId": { "$ref": "#/$defs/Identifier" },
+        "digest": { "$ref": "#/$defs/Digest" },
+        "manifest": {
+          "$ref": "widget-manifest.schema.json"
+        },
+        "launch": { "$ref": "#/$defs/Launch" },
+        "grantedCapabilities": { "$ref": "#/$defs/GrantedCapabilities" }
+      }
+    },
+    "FallbackBinding": {
+      "title": "FallbackBinding",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "bindingId",
+        "widgetId",
+        "widgetVersionId",
+        "slot",
+        "reason"
+      ],
+      "properties": {
+        "status": { "const": "fallback" },
+        "bindingId": { "$ref": "#/$defs/Identifier" },
+        "widgetId": { "$ref": "#/$defs/Identifier" },
+        "widgetVersionId": { "$ref": "#/$defs/Identifier" },
+        "slot": {
+          "$ref": "widget-manifest.schema.json#/$defs/WidgetSlotConfig"
+        },
+        "reason": { "$ref": "#/$defs/FallbackReason" }
+      }
+    },
+    "RuntimeAuthority": {
+      "title": "RuntimeAuthority",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["origin", "catalogRevision"],
+      "properties": {
+        "origin": { "$ref": "#/$defs/RuntimeOrigin" },
+        "catalogRevision": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        }
+      }
+    },
+    "NetworkAuthority": {
+      "title": "NetworkAuthority",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["mode", "policyVersion", "limits"],
+      "properties": {
+        "mode": { "enum": ["runtime-consent", "unavailable"] },
+        "policyVersion": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]*$"
+        },
+        "limits": {
+          "$ref": "widget-runtime-contracts.schema.json#/$defs/WidgetNetworkLimits"
+        }
+      }
+    },
+    "GrantedCapabilities": {
+      "title": "GrantedCapabilities",
+      "type": "array",
+      "items": {
+        "$ref": "widget-runtime-contracts.schema.json#/$defs/GrantedCapability"
+      }
+    },
+    "Launch": {
+      "title": "Launch",
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["url", "expiresAt"],
+      "properties": {
+        "url": { "type": "string", "pattern": "^https?://" },
+        "expiresAt": { "$ref": "#/$defs/Timestamp" }
+      }
+    },
+    "RuntimeOrigin": {
+      "title": "RuntimeOrigin",
+      "type": "string",
+      "maxLength": 253,
+      "pattern": "^(?:https://[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?(?::[0-9]{1,5})?|http://(?:localhost|127\\.0\\.0\\.1|\\[::1\\])(?::[0-9]{1,5})?)$"
+    },
+    "FallbackReason": {
+      "title": "FallbackReason",
+      "enum": [
+        "not-authorized",
+        "not-approved",
+        "delisted-for-new-use",
+        "revoked",
+        "host-api-unsupported",
+        "preview-not-allowed"
+      ]
+    },
+    "Digest": {
+      "title": "Digest",
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "Identifier": {
+      "title": "Identifier",
+      "type": "string",
+      "minLength": 1
+    },
+    "Mode": {
+      "title": "Mode",
+      "enum": ["preview", "published"]
+    },
+    "Timestamp": {
+      "title": "Timestamp",
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T[^ ]+Z$"
+    }
+  }
+}