@floegence/redevplugin-ui 0.1.6 → 0.2.2

package/dist/surface.d.ts

@@ -0,0 +1,328 @@
+import { PluginBridgeError } from "./errors.js";
+import { pluginUIProtocolVersion } from "./contracts.gen.js";
+import { type OpaqueSurfaceAllowedTag } from "./opaque-surface-policy.gen.js";
+import { type FetchLike } from "./http.js";
+import { type PluginSurfaceScope } from "./surface-scope.js";
+export declare const opaqueSurfaceDocumentSchemaVersion: "redevplugin.opaque_surface_document.v1";
+export declare const pluginRiskPlanSchemaVersion: "redevplugin.capability.risk_plan.v1";
+export type PluginJSONValue = null | boolean | number | string | PluginJSONValue[] | PluginJSONObject;
+export type PluginJSONObject = {
+    [key: string]: PluginJSONValue;
+};
+export type BridgeLifecycleEvent = {
+    type: "ready";
+} | {
+    type: "visible";
+} | {
+    type: "hidden";
+} | {
+    type: "dispose";
+};
+export type TrustedParentBridgeHandshake = {
+    type: "redevplugin.bridge.handshake";
+    plugin_id: string;
+    surface_id: string;
+    surface_instance_id: string;
+    active_fingerprint: string;
+    bridge_nonce: string;
+    asset_session_nonce: string;
+    plugin_state_version: number;
+    revoke_epoch: number;
+    ui_protocol_version: typeof pluginUIProtocolVersion;
+};
+export type TrustedParentBridgeTokenRequest = {
+    bridge_channel_id: string;
+    handshake: TrustedParentBridgeHandshake;
+    handshake_transcript_sha256: string;
+    previous_plugin_gateway_token?: string;
+};
+export type PluginBridgeRequest = {
+    id: string;
+    method: string;
+    params?: PluginJSONObject;
+};
+export type PluginBridgeResponse = {
+    type: "redevplugin.bridge.response";
+    id: string;
+    ok: true;
+    data?: unknown;
+} | {
+    type: "redevplugin.bridge.response";
+    id: string;
+    ok: false;
+    error_code: string;
+    error: string;
+};
+export type PluginBridgeCancelMessage = {
+    type: "redevplugin.bridge.cancel";
+    id: string;
+};
+export type PluginBridgeLifecycleMessage = {
+    type: "redevplugin.bridge.lifecycle";
+    event: BridgeLifecycleEvent;
+};
+export type PluginUIActionEvent = {
+    action: string;
+    event: "click" | "input" | "change" | "submit";
+    value?: string;
+    checked?: boolean;
+    form_data?: Record<string, string>;
+};
+export type PluginUIAttributeValue = string | number | boolean;
+export type PluginUIVNode = string | {
+    type: "element";
+    tag: OpaqueSurfaceAllowedTag;
+    attributes?: Record<string, PluginUIAttributeValue>;
+    children?: PluginUIVNode[];
+};
+export type PluginMethodResult<T = unknown> = {
+    data?: T;
+    operation_id?: string;
+    stream_handle?: string;
+    confirmation_required?: boolean;
+    confirmation_token_id?: string;
+    request_hash?: string;
+};
+export type PluginTrustedMethodResult<T = unknown> = Omit<PluginMethodResult<T>, "stream_handle"> & {
+    stream_id?: string;
+    stream_ticket?: string;
+    stream_ticket_id?: string;
+    stream_expires_at?: string;
+};
+export type PluginStreamEvent = {
+    stream_id: string;
+    sequence: number;
+    kind: string;
+    data?: string;
+    error?: string;
+    at: string;
+};
+export type PluginRiskSeverity = "info" | "low" | "medium" | "high" | "critical";
+export type PluginRiskEffect = "read" | "write" | "execute" | "delete" | "admin";
+export type PluginRiskFlag = {
+    id: string;
+    severity: PluginRiskSeverity;
+    summary: string;
+    description?: string;
+    requires_confirmation?: boolean;
+    requires_admin?: boolean;
+    data_loss_risk?: boolean;
+    destructive?: boolean;
+};
+export type PluginRiskPlan = {
+    schema_version: typeof pluginRiskPlanSchemaVersion;
+    capability_id?: string;
+    binding_id?: string;
+    method?: string;
+    target_method?: string;
+    action?: string;
+    effect?: PluginRiskEffect;
+    resource_ref?: string;
+    resource_display_name?: string;
+    summary: string;
+    risk_flags: PluginRiskFlag[];
+    requires_confirmation?: boolean;
+    requires_admin?: boolean;
+    data_loss_risk?: boolean;
+    destructive?: boolean;
+    deny_reason?: string;
+    details?: Record<string, unknown>;
+};
+export type PluginConfirmationPlan = PluginRiskPlan | Record<string, unknown>;
+export type PluginConfirmationIntent = {
+    requestId: string;
+    method: string;
+    params?: Record<string, unknown>;
+    requestHash: string;
+    planHash: string;
+    plan?: PluginConfirmationPlan;
+    confirmationTokenId: string;
+    signal: AbortSignal;
+};
+export type PluginConfirmationDecision = boolean | {
+    confirmed: boolean;
+};
+export type PluginConfirmationHandler = (intent: PluginConfirmationIntent) => Promise<PluginConfirmationDecision> | PluginConfirmationDecision;
+export type MessageEventLike = {
+    origin?: string;
+    data: unknown;
+    source?: WindowLike | null;
+    ports?: MessagePortLike[];
+};
+export type MessagePortLike = {
+    postMessage(message: unknown): void;
+    addEventListener(type: "message", listener: (event: MessageEventLike) => void): void;
+    removeEventListener(type: "message", listener: (event: MessageEventLike) => void): void;
+    start(): void;
+    close(): void;
+};
+export type WindowLike = {
+    postMessage(message: unknown, targetOrigin: string, transfer?: MessagePortLike[]): void;
+};
+export type MessageChannelLike = {
+    port1: MessagePortLike;
+    port2: MessagePortLike;
+};
+export type PluginBridgeClientOptions = {
+    timeoutMs?: number;
+    port?: MessagePortLike;
+    surfaceHandle?: string;
+};
+export declare class PluginBridgeClient {
+    #private;
+    readonly surfaceHandle: string;
+    readonly timeoutMs: number;
+    constructor(options?: PluginBridgeClientOptions);
+    ready(): Promise<void>;
+    call<T = unknown>(method: string, params?: PluginJSONObject): Promise<T>;
+    readStream(streamHandle: string): Promise<PluginStreamEvent[]>;
+    render(tree: PluginUIVNode | PluginUIVNode[]): Promise<void>;
+    onAction(action: string, handler: (event: PluginUIActionEvent) => void): () => void;
+    onLifecycle(handler: (event: BridgeLifecycleEvent) => void): () => void;
+    dispose(): void;
+}
+export declare const defaultPluginSurfaceReloadMax = 2;
+export declare const defaultPluginSurfaceReloadWindowMs = 30000;
+export type PluginSurfaceReloadLimiterOptions = {
+    maxReloads?: number;
+    windowMs?: number;
+    now?: () => number;
+};
+export type PluginSurfaceReloadDecision = {
+    allowed: true;
+    attempt: number;
+    remaining: number;
+    windowStartedAtMs: number;
+} | {
+    allowed: false;
+    attempt: number;
+    remaining: 0;
+    windowStartedAtMs: number;
+    nextRetryAtMs: number;
+    reason: "reload_limit_exceeded";
+};
+export type PluginSurfaceReloadState = {
+    reloads: number;
+    remaining: number;
+    windowStartedAtMs?: number;
+    nextRetryAtMs?: number;
+};
+export declare class PluginSurfaceReloadLimiter {
+    #private;
+    readonly maxReloads: number;
+    readonly windowMs: number;
+    constructor(options?: PluginSurfaceReloadLimiterOptions);
+    recordCrash(nowMs?: number): PluginSurfaceReloadDecision;
+    recordHealthyLoad(): void;
+    reset(): void;
+    get state(): PluginSurfaceReloadState;
+}
+export declare function isPluginRiskPlan(plan: unknown): plan is PluginRiskPlan;
+export declare function decodePluginStreamText(event: PluginStreamEvent): string;
+export declare function trustedParentBridgeHandshakeTranscriptSHA256(handshake: TrustedParentBridgeHandshake, bridgeChannelID: string): Promise<string>;
+export type OpaqueSurfaceStyle = {
+    path: string;
+    sha256: string;
+    content: string;
+};
+export type OpaqueSurfaceWorker = {
+    path: string;
+    sha256: string;
+    type: "classic";
+    content: string;
+};
+export type OpaqueSurfaceAsset = {
+    binding_id: string;
+    path: string;
+    sha256: string;
+    size: number;
+    content_type: string;
+};
+export type OpaqueSurfaceDocument = {
+    schema_version: typeof opaqueSurfaceDocumentSchemaVersion;
+    entry_path: string;
+    entry_sha256: string;
+    title?: string;
+    language?: string;
+    direction?: string;
+    body_html: string;
+    styles: OpaqueSurfaceStyle[];
+    worker: OpaqueSurfaceWorker;
+    assets: OpaqueSurfaceAsset[];
+    critical_bytes: number;
+};
+export type PluginSurfacePreparationResult = {
+    asset_session: string;
+    asset_session_id: string;
+    asset_session_nonce: string;
+    entry_path: string;
+    entry_sha256: string;
+    plugin_state_version: number;
+    revoke_epoch: number;
+    issued_at: string;
+    expires_at: string;
+    document: OpaqueSurfaceDocument;
+};
+export type PluginSurfaceHostBootstrap = {
+    pluginId: string;
+    pluginInstanceId: string;
+    pluginVersion: string;
+    surfaceId: string;
+    surfaceInstanceId: string;
+    activeFingerprint: string;
+    bridgeNonce: string;
+    entryPath: string;
+    entrySHA256: string;
+    assetTicket: string;
+    assetSessionNonce: string;
+    pluginStateVersion: number;
+    revokeEpoch: number;
+    runtimeGenerationId: string;
+};
+export type PluginSurfaceOpeningProgress = {
+    phase: "opening";
+    elapsedMs: number;
+};
+export type PluginSurfaceHostOptions = {
+    bootstrap: PluginSurfaceHostBootstrap;
+    hostTransport: ReDevPluginSurfaceTransport;
+    surfaceScope?: PluginSurfaceScope;
+    bridgeChannelId?: string;
+    loadTimeoutMs?: number;
+    requestTimeoutMs?: number;
+    leaseRenewalLeadMs?: number;
+    reloadLimiter?: PluginSurfaceReloadLimiter;
+    confirm?: PluginConfirmationHandler;
+    onOpeningProgress?: (progress: PluginSurfaceOpeningProgress) => void;
+    onError?: (error: PluginBridgeError) => void;
+};
+declare const redevPluginSurfaceTransportBrand: unique symbol;
+export type ReDevPluginSurfaceTransport = {
+    readonly [redevPluginSurfaceTransportBrand]: true;
+};
+export type ReDevPluginSurfaceTransportOptions = {
+    fetch?: FetchLike;
+    apiBaseURL?: string;
+};
+export declare function createReDevPluginSurfaceTransport(options?: ReDevPluginSurfaceTransportOptions): ReDevPluginSurfaceTransport;
+export type OpaquePluginBootstrapHTMLOptions = {
+    scriptNonce?: string;
+};
+export declare function createOpaquePluginBootstrapHTML(options?: OpaquePluginBootstrapHTMLOptions): string;
+export declare class PluginSurfaceHost {
+    #private;
+    readonly element: HTMLIFrameElement;
+    readonly bootstrap: PluginSurfaceHostBootstrap;
+    readonly bridgeChannelId: string;
+    readonly frameGenerationId: string;
+    readonly surfaceHandle: string;
+    static create(options: PluginSurfaceHostOptions): PluginSurfaceHost;
+    private constructor();
+    open(): Promise<void>;
+    sendLifecycle(event: Exclude<BridgeLifecycleEvent, {
+        type: "ready" | "dispose";
+    }>): void;
+    close(): Promise<void>;
+    dispose(): void;
+}
+export {};