@floegence/redevplugin-ui 0.0.0-dev

package/dist/index.js

@@ -0,0 +1,876 @@
+export const pluginPlatformErrorCodes = [
+    "PLUGIN_INVALID_REQUEST",
+    "PLUGIN_MANIFEST_INVALID",
+    "PLUGIN_PACKAGE_INVALID",
+    "PLUGIN_PACKAGE_TOO_LARGE",
+    "PLUGIN_PACKAGE_PATH_FORBIDDEN",
+    "PLUGIN_SIGNATURE_INVALID",
+    "PLUGIN_TRUST_STATE_DENIED",
+    "PLUGIN_TRUST_VERIFICATION_REQUIRED",
+    "PLUGIN_TRUST_VERIFICATION_INVALID",
+    "PLUGIN_DISABLED",
+    "PLUGIN_DISABLED_BY_POLICY",
+    "PLUGIN_PERMISSION_DENIED",
+    "PLUGIN_CONFIRMATION_REQUIRED",
+    "PLUGIN_CONFIRMATION_INVALID",
+    "PLUGIN_TOKEN_EXPIRED",
+    "PLUGIN_TOKEN_REPLAY",
+    "PLUGIN_GATEWAY_TOKEN_INVALID",
+    "PLUGIN_GATEWAY_TOKEN_REPLAYED",
+    "PLUGIN_GATEWAY_TOKEN_CHANNEL_MISMATCH",
+    "PLUGIN_ASSET_TICKET_INVALID",
+    "PLUGIN_ASSET_SESSION_INVALID",
+    "PLUGIN_STREAM_TICKET_INVALID",
+    "PLUGIN_STREAM_CANCELLED",
+    "PLUGIN_LEASE_INVALID",
+    "PLUGIN_LEASE_REPLAYED",
+    "PLUGIN_GRANT_INVALID",
+    "PLUGIN_STORAGE_QUOTA_EXCEEDED",
+    "PLUGIN_OPERATION_BLOCKED",
+    "PLUGIN_OPERATION_NOT_FOUND",
+    "PLUGIN_OPERATION_NOT_CANCELABLE",
+    "PLUGIN_NETWORK_TARGET_DENIED",
+    "PLUGIN_NETWORK_RATE_LIMITED",
+    "PLUGIN_RUNTIME_UNAVAILABLE",
+    "PLUGIN_RUNTIME_VERSION_MISMATCH",
+    "PLUGIN_JSON_LIMIT_EXCEEDED",
+    "PLUGIN_CONTRACT_MISMATCH",
+    "PLUGIN_CSRF_REQUIRED",
+    "PLUGIN_RETAINED_DATA_CLEANUP_FAILED",
+    "PLUGIN_RETAINED_DATA_BIND_FAILED",
+];
+export const pluginBridgeErrorCodes = [
+    ...pluginPlatformErrorCodes,
+    "PLUGIN_CONFIRMATION_REJECTED",
+    "PLUGIN_BRIDGE_TIMEOUT",
+    "PLUGIN_BRIDGE_DISPOSED",
+    "PLUGIN_BRIDGE_HANDSHAKE_FAILED",
+    "PLUGIN_BRIDGE_HANDSHAKE_REQUIRED",
+];
+export const pluginClientErrorCodes = [
+    ...pluginBridgeErrorCodes,
+    "PLUGIN_PLATFORM_REQUEST_FAILED",
+    "PLUGIN_STREAM_FAILED",
+];
+export const defaultPluginSurfaceReloadMax = 2;
+export const defaultPluginSurfaceReloadWindowMs = 30_000;
+export class PluginBridgeError extends Error {
+    errorCode;
+    data;
+    details;
+    constructor(errorCode, message, data, details) {
+        super(message);
+        this.name = "PluginBridgeError";
+        this.errorCode = errorCode;
+        this.data = data;
+        this.details = details ?? data;
+    }
+}
+export async function pluginBridgeHandshakeTranscriptSHA256(handshake, bridgeChannelID) {
+    const subtle = globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new PluginBridgeError("PLUGIN_BRIDGE_HANDSHAKE_FAILED", "Web Crypto SHA-256 is unavailable for plugin bridge handshake");
+    }
+    const encoder = new TextEncoder();
+    const fields = [
+        "redevplugin.bridge.handshake.v1",
+        handshake.plugin_id,
+        handshake.surface_id,
+        handshake.surface_instance_id,
+        handshake.active_fingerprint,
+        handshake.bridge_nonce,
+        handshake.ui_protocol_version,
+        bridgeChannelID,
+    ];
+    const chunks = [];
+    let totalBytes = 0;
+    for (const field of fields) {
+        const data = encoder.encode(field);
+        const prefix = encoder.encode(`${data.byteLength}:`);
+        const terminator = new Uint8Array([0]);
+        chunks.push(prefix, data, terminator);
+        totalBytes += prefix.byteLength + data.byteLength + terminator.byteLength;
+    }
+    const transcript = new Uint8Array(totalBytes);
+    let offset = 0;
+    for (const chunk of chunks) {
+        transcript.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    const digest = await subtle.digest("SHA-256", transcript);
+    const bytes = new Uint8Array(digest);
+    return `sha256:${Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+export class PluginSurfaceReloadLimiter {
+    maxReloads;
+    windowMs;
+    #now;
+    #windowStartedAtMs;
+    #reloads = 0;
+    constructor(options = {}) {
+        this.maxReloads = normalizeReloadMax(options.maxReloads ?? defaultPluginSurfaceReloadMax);
+        this.windowMs = normalizeReloadWindow(options.windowMs ?? defaultPluginSurfaceReloadWindowMs);
+        this.#now = options.now ?? (() => Date.now());
+    }
+    recordCrash(nowMs = this.#now()) {
+        nowMs = normalizeNowMs(nowMs);
+        this.#ensureWindow(nowMs);
+        const windowStartedAtMs = this.#windowStartedAtMs ?? nowMs;
+        if (this.#reloads >= this.maxReloads) {
+            return {
+                allowed: false,
+                attempt: this.#reloads + 1,
+                remaining: 0,
+                windowStartedAtMs,
+                nextRetryAtMs: windowStartedAtMs + this.windowMs,
+                reason: "reload_limit_exceeded",
+            };
+        }
+        this.#reloads += 1;
+        return {
+            allowed: true,
+            attempt: this.#reloads,
+            remaining: this.maxReloads - this.#reloads,
+            windowStartedAtMs,
+        };
+    }
+    recordHealthyLoad() {
+        this.reset();
+    }
+    reset() {
+        this.#windowStartedAtMs = undefined;
+        this.#reloads = 0;
+    }
+    get state() {
+        const remaining = Math.max(0, this.maxReloads - this.#reloads);
+        return {
+            reloads: this.#reloads,
+            remaining,
+            windowStartedAtMs: this.#windowStartedAtMs,
+            nextRetryAtMs: remaining === 0 && this.#windowStartedAtMs !== undefined
+                ? this.#windowStartedAtMs + this.windowMs
+                : undefined,
+        };
+    }
+    #ensureWindow(nowMs) {
+        if (this.#windowStartedAtMs === undefined ||
+            nowMs < this.#windowStartedAtMs ||
+            nowMs >= this.#windowStartedAtMs + this.windowMs) {
+            this.#windowStartedAtMs = nowMs;
+            this.#reloads = 0;
+        }
+    }
+}
+class PluginConfirmationRequiredError extends PluginBridgeError {
+}
+export class PluginBridgeClient {
+    bootstrap;
+    timeoutMs;
+    #nextID = 1;
+    #target;
+    #receiver;
+    #pending = new Map();
+    #lifecycleHandlers = new Set();
+    #disposed = false;
+    #onMessage = (event) => {
+        this.#handleMessage(event);
+    };
+    constructor(bootstrap, options = {}) {
+        if (!bootstrap.parentOrigin || bootstrap.parentOrigin === "*") {
+            throw new Error("parentOrigin must be an exact origin");
+        }
+        this.bootstrap = bootstrap;
+        this.timeoutMs = normalizeTimeout(options.timeoutMs);
+        this.#target = options.target ?? window.parent;
+        this.#receiver = options.receiver ?? window;
+        this.#receiver.addEventListener?.("message", this.#onMessage);
+    }
+    handshake() {
+        this.#assertActive();
+        const message = {
+            type: "redevplugin.bridge.handshake",
+            plugin_id: this.bootstrap.pluginId,
+            surface_id: this.bootstrap.surfaceId,
+            surface_instance_id: this.bootstrap.surfaceInstanceId,
+            active_fingerprint: this.bootstrap.activeFingerprint,
+            bridge_nonce: this.bootstrap.bridgeNonce,
+            ui_protocol_version: "plugin-ui-v1",
+        };
+        this.#target.postMessage(message, this.bootstrap.parentOrigin);
+    }
+    call(method, params) {
+        this.#assertActive();
+        const request = {
+            id: String(this.#nextID++),
+            method,
+            params,
+        };
+        const message = { type: "redevplugin.bridge.call", request };
+        const result = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.#pending.delete(request.id);
+                reject(new PluginBridgeError("PLUGIN_BRIDGE_TIMEOUT", `Plugin bridge call ${request.id} timed out`));
+            }, this.timeoutMs);
+            this.#pending.set(request.id, {
+                resolve: (value) => resolve(value),
+                reject,
+                timer,
+            });
+        });
+        this.#target.postMessage(message, this.bootstrap.parentOrigin);
+        return result;
+    }
+    onLifecycle(handler) {
+        this.#assertActive();
+        this.#lifecycleHandlers.add(handler);
+        return () => {
+            this.#lifecycleHandlers.delete(handler);
+        };
+    }
+    dispose() {
+        if (this.#disposed) {
+            return;
+        }
+        this.#disposed = true;
+        this.#receiver.removeEventListener?.("message", this.#onMessage);
+        for (const [id, pending] of this.#pending) {
+            clearTimeout(pending.timer);
+            pending.reject(new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", `Plugin bridge call ${id} was disposed`));
+        }
+        this.#pending.clear();
+        this.#lifecycleHandlers.clear();
+    }
+    #handleMessage(event) {
+        if (this.#disposed || event.origin !== this.bootstrap.parentOrigin) {
+            return;
+        }
+        const data = event.data;
+        if (isBridgeResponse(data)) {
+            const pending = this.#pending.get(data.id);
+            if (!pending) {
+                return;
+            }
+            this.#pending.delete(data.id);
+            clearTimeout(pending.timer);
+            if (data.ok) {
+                pending.resolve(data.data);
+            }
+            else {
+                pending.reject(new PluginBridgeError(data.error_code, data.error));
+            }
+            return;
+        }
+        if (isLifecycleMessage(data)) {
+            for (const handler of this.#lifecycleHandlers) {
+                handler(data.event);
+            }
+        }
+    }
+    #assertActive() {
+        if (this.#disposed) {
+            throw new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", "Plugin bridge client is disposed");
+        }
+    }
+}
+export const pluginRiskPlanSchemaVersion = "redevplugin.capability.risk_plan.v1";
+export function isPluginRiskPlan(plan) {
+    return isRecord(plan) &&
+        plan.schema_version === pluginRiskPlanSchemaVersion &&
+        typeof plan.summary === "string" &&
+        Array.isArray(plan.risk_flags) &&
+        plan.risk_flags.every(isPluginRiskFlag) &&
+        (plan.effect == null || isPluginRiskEffect(plan.effect)) &&
+        (plan.details == null || isRecord(plan.details));
+}
+export class PluginPlatformClient {
+    #fetch;
+    #apiBaseURL;
+    #ownerSessionHashHeader;
+    constructor(options = {}) {
+        this.#fetch = options.fetch ?? defaultFetch();
+        this.#apiBaseURL = trimTrailingSlash(options.apiBaseURL ?? "");
+        this.#ownerSessionHashHeader = options.ownerSessionHashHeader;
+    }
+    catalog() {
+        return this.#getJSON("/_redevplugin/api/plugins/catalog");
+    }
+    getCompatibility() {
+        return this.#getJSON("/_redevplugin/api/plugins/platform/compatibility");
+    }
+    installPlugin(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/install", request);
+    }
+    updatePlugin(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/update", request);
+    }
+    downgradePlugin(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/downgrade", request);
+    }
+    enablePlugin(pluginInstanceIdOrRequest) {
+        return this.#postJSON("/_redevplugin/api/plugins/enable", pluginInstanceRequest(pluginInstanceIdOrRequest));
+    }
+    disablePlugin(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/disable", request);
+    }
+    uninstallPlugin(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/uninstall", request);
+    }
+    openSurface(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/surfaces/open", request);
+    }
+    startRuntime(request = {}) {
+        return this.#postJSON("/_redevplugin/api/plugins/runtime/start", request);
+    }
+    stopRuntime() {
+        return this.#postJSON("/_redevplugin/api/plugins/runtime/stop", {});
+    }
+    refreshEnabledRuntimeState() {
+        return this.#postJSON("/_redevplugin/api/plugins/runtime/refresh-enabled", {});
+    }
+    runtimeHealth() {
+        return this.#getJSON("/_redevplugin/api/plugins/runtime/health");
+    }
+    getSettingsSchema(pluginInstanceId) {
+        return this.#getJSON(`/_redevplugin/api/plugins/${encodeURIComponent(pluginInstanceId)}/settings/schema`);
+    }
+    getSettings(pluginInstanceId) {
+        return this.#getJSON(`/_redevplugin/api/plugins/${encodeURIComponent(pluginInstanceId)}/settings`);
+    }
+    patchSettings(pluginInstanceId, values) {
+        return this.#patchJSON(`/_redevplugin/api/plugins/${encodeURIComponent(pluginInstanceId)}/settings`, { values });
+    }
+    listOperations(pluginInstanceId) {
+        const query = pluginInstanceId ? `?plugin_instance_id=${encodeURIComponent(pluginInstanceId)}` : "";
+        return this.#getJSON(`/_redevplugin/api/plugins/operations${query}`);
+    }
+    getOperation(operationId) {
+        return this.#getJSON(`/_redevplugin/api/plugins/operations/${encodeURIComponent(operationId)}`);
+    }
+    cancelOperation(operationId, reason) {
+        const body = reason ? { reason } : {};
+        return this.#postJSON(`/_redevplugin/api/plugins/operations/${encodeURIComponent(operationId)}/cancel`, body);
+    }
+    listIntents(options = {}) {
+        const params = new URLSearchParams();
+        if (options.intent_id) {
+            params.set("intent_id", options.intent_id);
+        }
+        if (options.plugin_instance_id) {
+            params.set("plugin_instance_id", options.plugin_instance_id);
+        }
+        const query = params.toString();
+        return this.#getJSON(`/_redevplugin/api/plugins/intents${query ? `?${query}` : ""}`);
+    }
+    invokeIntent(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/intents/invoke", request);
+    }
+    exportData(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/data/export", request);
+    }
+    importData(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/data/import", request);
+    }
+    listRetainedData(options = {}) {
+        const params = new URLSearchParams();
+        if (options.publisher_id) {
+            params.set("publisher_id", options.publisher_id);
+        }
+        if (options.plugin_id) {
+            params.set("plugin_id", options.plugin_id);
+        }
+        if (options.source_plugin_instance_id) {
+            params.set("source_plugin_instance_id", options.source_plugin_instance_id);
+        }
+        if (options.state) {
+            params.set("state", options.state);
+        }
+        const query = params.toString();
+        return this.#getJSON(`/_redevplugin/api/plugins/retained-data${query ? `?${query}` : ""}`);
+    }
+    deleteRetainedData(retainedId) {
+        return this.#postJSON("/_redevplugin/api/plugins/retained-data/delete", { retained_id: retainedId });
+    }
+    bindRetainedData(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/retained-data/bind", request);
+    }
+    cleanupExpiredRetainedData(request = {}) {
+        return this.#postJSON("/_redevplugin/api/plugins/retained-data/cleanup-expired", request);
+    }
+    listPermissions(pluginInstanceId, activeOnly) {
+        const params = new URLSearchParams();
+        if (pluginInstanceId) {
+            params.set("plugin_instance_id", pluginInstanceId);
+        }
+        if (activeOnly != null) {
+            params.set("active_only", activeOnly ? "true" : "false");
+        }
+        const query = params.toString();
+        return this.#getJSON(`/_redevplugin/api/plugins/permissions${query ? `?${query}` : ""}`);
+    }
+    grantPermission(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/permissions/grant", request);
+    }
+    revokePermission(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/permissions/revoke", request);
+    }
+    bindSecret(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/secrets/bind", request);
+    }
+    testSecret(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/secrets/test", request);
+    }
+    deleteSecret(request) {
+        return this.#postJSON("/_redevplugin/api/plugins/secrets/delete", request);
+    }
+    listAuditEvents(options = {}) {
+        return this.#getJSON(`/_redevplugin/api/plugins/audit${queryString(options)}`);
+    }
+    listDiagnosticEvents(options = {}) {
+        return this.#getJSON(`/_redevplugin/api/plugins/diagnostics${queryString(options)}`);
+    }
+    #getJSON(path) {
+        return this.#requestJSON("GET", path);
+    }
+    #postJSON(path, body) {
+        return this.#requestJSON("POST", path, body);
+    }
+    #patchJSON(path, body) {
+        return this.#requestJSON("PATCH", path, body);
+    }
+    async #requestJSON(method, path, body) {
+        const response = await this.#fetch(this.#apiBaseURL + path, {
+            method,
+            headers: this.#headers(body !== undefined),
+            body: body === undefined ? undefined : JSON.stringify(body),
+            credentials: "same-origin",
+        });
+        return readHostEnvelope(response, "PLUGIN_PLATFORM_REQUEST_FAILED");
+    }
+    #headers(hasBody) {
+        const headers = { "Accept": "application/json" };
+        if (hasBody) {
+            headers["Content-Type"] = "application/json";
+        }
+        if (this.#ownerSessionHashHeader) {
+            headers["X-ReDevPlugin-Owner-Session-Hash"] = this.#ownerSessionHashHeader;
+        }
+        return headers;
+    }
+}
+export class PluginSurfaceHost {
+    bootstrap;
+    iframeOrigin;
+    bridgeChannelId;
+    #iframeWindow;
+    #parentWindow;
+    #fetch;
+    #apiBaseURL;
+    #ownerSessionHashHeader;
+    #confirm;
+    #onError;
+    #gatewayToken;
+    #disposed = false;
+    #onMessage = (event) => {
+        void this.#handleMessage(event);
+    };
+    constructor(options) {
+        if (!options.iframeOrigin || options.iframeOrigin === "*") {
+            throw new Error("iframeOrigin must be an exact origin");
+        }
+        this.bootstrap = options.bootstrap;
+        this.iframeOrigin = options.iframeOrigin;
+        this.bridgeChannelId = options.bridgeChannelId ?? randomBridgeChannelID();
+        this.#iframeWindow = options.iframeWindow;
+        this.#parentWindow = options.parentWindow ?? window;
+        this.#fetch = options.fetch ?? defaultFetch();
+        this.#apiBaseURL = trimTrailingSlash(options.apiBaseURL ?? "");
+        this.#ownerSessionHashHeader = options.ownerSessionHashHeader ?? options.bootstrap.ownerSessionHash;
+        this.#confirm = options.confirm;
+        this.#onError = options.onError;
+        this.#parentWindow.addEventListener?.("message", this.#onMessage);
+    }
+    sendLifecycle(event) {
+        this.#assertActive();
+        this.#postToIframe({ type: "redevplugin.bridge.lifecycle", event });
+    }
+    dispose() {
+        if (this.#disposed) {
+            return;
+        }
+        this.#disposed = true;
+        this.#gatewayToken = undefined;
+        this.#parentWindow.removeEventListener?.("message", this.#onMessage);
+        this.#postToIframe({ type: "redevplugin.bridge.lifecycle", event: { type: "dispose" } });
+    }
+    async #handleMessage(event) {
+        if (this.#disposed || event.origin !== this.iframeOrigin) {
+            return;
+        }
+        if (event.source != null && event.source !== this.#iframeWindow) {
+            return;
+        }
+        const data = event.data;
+        if (isBridgeHandshake(data)) {
+            await this.#handleHandshake(data);
+            return;
+        }
+        if (isBridgeCallMessage(data)) {
+            await this.#handleCall(data.request);
+        }
+    }
+    async #handleHandshake(handshake) {
+        if (!handshakeMatchesBootstrap(handshake, this.bootstrap)) {
+            this.#reportError(new PluginBridgeError("PLUGIN_BRIDGE_HANDSHAKE_FAILED", "Plugin bridge handshake did not match the surface bootstrap"));
+            return;
+        }
+        try {
+            const request = {
+                bridge_channel_id: this.bridgeChannelId,
+                handshake,
+                handshake_transcript_sha256: await pluginBridgeHandshakeTranscriptSHA256(handshake, this.bridgeChannelId),
+            };
+            const token = await this.#postJSON(`/_redevplugin/api/plugins/surfaces/${encodeURIComponent(this.bootstrap.surfaceInstanceId)}/bridge-token`, request);
+            this.#gatewayToken = token.plugin_gateway_token;
+            this.#postToIframe({ type: "redevplugin.bridge.lifecycle", event: { type: "ready" } });
+        }
+        catch (error) {
+            this.#reportError(toBridgeError(error, "PLUGIN_BRIDGE_HANDSHAKE_FAILED"));
+        }
+    }
+    async #handleCall(request) {
+        if (!this.#gatewayToken) {
+            this.#postError(request.id, "PLUGIN_BRIDGE_HANDSHAKE_REQUIRED", "Plugin bridge call arrived before a successful handshake");
+            return;
+        }
+        if (!validRPCParams(request.params)) {
+            this.#postError(request.id, "PLUGIN_INVALID_REQUEST", "Plugin bridge call params must be a JSON object when present");
+            return;
+        }
+        try {
+            const result = await this.#callRPC(request);
+            this.#postToIframe({ type: "redevplugin.bridge.response", id: request.id, ok: true, data: result });
+        }
+        catch (error) {
+            const bridgeError = toBridgeError(error, "PLUGIN_PERMISSION_DENIED");
+            if (bridgeError instanceof PluginConfirmationRequiredError) {
+                await this.#handleConfirmationRequired(request, bridgeError);
+                return;
+            }
+            this.#postError(request.id, bridgeError.errorCode, bridgeError.message);
+        }
+    }
+    async #handleConfirmationRequired(request, originalError) {
+        if (!this.#confirm) {
+            this.#postError(request.id, originalError.errorCode, originalError.message);
+            return;
+        }
+        try {
+            const confirmation = await this.#prepareConfirmation(request);
+            const decision = await this.#confirm({
+                requestId: request.id,
+                method: request.method,
+                params: validRPCParams(request.params) ? request.params : undefined,
+                requestHash: confirmation.request_hash,
+                planHash: confirmation.plan_hash,
+                plan: confirmation.plan,
+                confirmationTokenId: confirmation.confirmation_token_id,
+            });
+            if (!confirmationDecisionAccepted(decision)) {
+                this.#postError(request.id, "PLUGIN_CONFIRMATION_REJECTED", "Plugin method confirmation was rejected");
+                return;
+            }
+            const result = await this.#callRPC(request, confirmation.confirmation_id);
+            this.#postToIframe({ type: "redevplugin.bridge.response", id: request.id, ok: true, data: result });
+        }
+        catch (error) {
+            const bridgeError = toBridgeError(error, "PLUGIN_PERMISSION_DENIED");
+            this.#postError(request.id, bridgeError.errorCode, bridgeError.message);
+        }
+    }
+    #callRPC(request, confirmationId) {
+        return this.#postJSON(`/_redevplugin/api/plugins/rpc`, this.#rpcBody(request, confirmationId));
+    }
+    #prepareConfirmation(request) {
+        return this.#postJSON(`/_redevplugin/api/plugins/confirm`, this.#rpcBody(request));
+    }
+    #rpcBody(request, confirmationId) {
+        const body = {
+            plugin_instance_id: this.bootstrap.pluginInstanceId,
+            surface_instance_id: this.bootstrap.surfaceInstanceId,
+            session_channel_id_hash: this.bootstrap.sessionChannelIdHash,
+            owner_session_hash: this.bootstrap.ownerSessionHash,
+            owner_user_hash: this.bootstrap.ownerUserHash,
+            bridge_channel_id: this.bridgeChannelId,
+            plugin_gateway_token: this.#gatewayToken,
+            method: request.method,
+            params: request.params,
+        };
+        if (confirmationId) {
+            body.confirmation_id = confirmationId;
+        }
+        return body;
+    }
+    async #postJSON(path, body) {
+        const headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+        };
+        if (this.#ownerSessionHashHeader) {
+            headers["X-ReDevPlugin-Owner-Session-Hash"] = this.#ownerSessionHashHeader;
+        }
+        const response = await this.#fetch(this.#apiBaseURL + path, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            credentials: "same-origin",
+        });
+        return readHostEnvelope(response, "PLUGIN_PERMISSION_DENIED");
+    }
+    #postError(id, errorCode, error) {
+        this.#postToIframe({ type: "redevplugin.bridge.response", id, ok: false, error_code: errorCode, error });
+    }
+    #postToIframe(message) {
+        this.#iframeWindow.postMessage(message, this.iframeOrigin);
+    }
+    #reportError(error) {
+        this.#onError?.(error);
+    }
+    #assertActive() {
+        if (this.#disposed) {
+            throw new PluginBridgeError("PLUGIN_BRIDGE_DISPOSED", "Plugin surface host is disposed");
+        }
+    }
+}
+export async function readPluginStream(options) {
+    const streamId = options.streamId ?? options.result?.stream_id;
+    const streamTicket = options.streamTicket ?? options.result?.stream_ticket;
+    if (!streamId || !streamTicket) {
+        throw new PluginBridgeError("PLUGIN_INVALID_REQUEST", "stream_id and stream_ticket are required to read a plugin stream");
+    }
+    const fetchLike = options.fetch ?? defaultStreamFetch();
+    const url = `${trimTrailingSlash(options.apiBaseURL ?? "")}/_redevplugin/stream/${encodeURIComponent(streamId)}?ticket=${encodeURIComponent(streamTicket)}`;
+    const response = await fetchLike(url, {
+        method: "GET",
+        headers: { "Accept": "application/x-ndjson, application/json" },
+        credentials: "same-origin",
+    });
+    const raw = await response.text();
+    if (!response.ok) {
+        throw streamErrorFromBody(raw, response.status);
+    }
+    return parseNDJSONEvents(raw);
+}
+export function decodePluginStreamText(event) {
+    if (!event.data) {
+        return "";
+    }
+    if (typeof TextDecoder === "function" && typeof atob === "function") {
+        const binary = atob(event.data);
+        const bytes = Uint8Array.from(binary, (char) => char.charCodeAt(0));
+        return new TextDecoder().decode(bytes);
+    }
+    const bufferLike = globalThis.Buffer;
+    if (bufferLike) {
+        return bufferLike.from(event.data, "base64").toString("utf8");
+    }
+    throw new PluginBridgeError("PLUGIN_STREAM_FAILED", "No base64 decoder is available for plugin stream data");
+}
+function normalizeTimeout(timeoutMs) {
+    if (timeoutMs == null) {
+        return 30_000;
+    }
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+        throw new Error("timeoutMs must be a positive finite number");
+    }
+    return timeoutMs;
+}
+function normalizeReloadMax(maxReloads) {
+    if (!Number.isInteger(maxReloads) || maxReloads < 0) {
+        throw new Error("maxReloads must be a non-negative integer");
+    }
+    return maxReloads;
+}
+function normalizeReloadWindow(windowMs) {
+    if (!Number.isFinite(windowMs) || windowMs <= 0) {
+        throw new Error("windowMs must be a positive finite number");
+    }
+    return windowMs;
+}
+function normalizeNowMs(nowMs) {
+    if (!Number.isFinite(nowMs)) {
+        throw new Error("nowMs must be a finite number");
+    }
+    return nowMs;
+}
+function defaultFetch() {
+    const fetchLike = globalThis.fetch;
+    if (!fetchLike) {
+        throw new Error("fetch is required when globalThis.fetch is unavailable");
+    }
+    return fetchLike.bind(globalThis);
+}
+function defaultStreamFetch() {
+    const fetchLike = globalThis.fetch;
+    if (!fetchLike) {
+        throw new Error("fetch is required when globalThis.fetch is unavailable");
+    }
+    return fetchLike.bind(globalThis);
+}
+function randomBridgeChannelID() {
+    const cryptoLike = globalThis;
+    if (cryptoLike.crypto?.randomUUID) {
+        return `bridge_${cryptoLike.crypto.randomUUID()}`;
+    }
+    return `bridge_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}`;
+}
+function trimTrailingSlash(value) {
+    return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+function queryString(values) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(values)) {
+        if (value != null && value !== "") {
+            params.set(key, String(value));
+        }
+    }
+    const query = params.toString();
+    return query ? `?${query}` : "";
+}
+function pluginInstanceRequest(value) {
+    return typeof value === "string" ? { plugin_instance_id: value } : value;
+}
+function isBridgeHandshake(value) {
+    return isRecord(value) &&
+        value.type === "redevplugin.bridge.handshake" &&
+        typeof value.plugin_id === "string" &&
+        typeof value.surface_id === "string" &&
+        typeof value.surface_instance_id === "string" &&
+        typeof value.active_fingerprint === "string" &&
+        typeof value.bridge_nonce === "string" &&
+        value.ui_protocol_version === "plugin-ui-v1";
+}
+function isBridgeCallMessage(value) {
+    return isRecord(value) &&
+        value.type === "redevplugin.bridge.call" &&
+        isRecord(value.request) &&
+        typeof value.request.id === "string" &&
+        typeof value.request.method === "string";
+}
+function isBridgeResponse(value) {
+    if (!isRecord(value) || value.type !== "redevplugin.bridge.response" || typeof value.id !== "string") {
+        return false;
+    }
+    if (value.ok === true) {
+        return true;
+    }
+    return value.ok === false && typeof value.error_code === "string" && typeof value.error === "string";
+}
+function isHostEnvelope(value) {
+    if (!isRecord(value) || typeof value.ok !== "boolean") {
+        return false;
+    }
+    if (value.ok) {
+        return true;
+    }
+    return (value.error == null || typeof value.error === "string") &&
+        (value.error_details == null || isRecord(value.error_details));
+}
+async function readHostEnvelope(response, fallbackCode) {
+    const raw = await response.json();
+    if (!isHostEnvelope(raw)) {
+        throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", `Plugin platform endpoint returned an invalid envelope with HTTP ${response.status}`);
+    }
+    if (!raw.ok) {
+        const errorCode = raw.error_code ?? fallbackCode;
+        const message = raw.error ?? `Plugin platform endpoint failed with HTTP ${response.status}`;
+        if (errorCode === "PLUGIN_CONFIRMATION_REQUIRED") {
+            throw new PluginConfirmationRequiredError(errorCode, message, raw.data, raw.error_details ?? raw.data);
+        }
+        throw new PluginBridgeError(errorCode, message, raw.data, raw.error_details ?? raw.data);
+    }
+    return raw.data;
+}
+function parseNDJSONEvents(raw) {
+    const events = [];
+    for (const line of raw.split(/\r?\n/)) {
+        if (line.trim() === "") {
+            continue;
+        }
+        const event = JSON.parse(line);
+        if (!isStreamEvent(event)) {
+            throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Plugin stream endpoint returned an invalid event");
+        }
+        events.push(event);
+    }
+    return events;
+}
+function streamErrorFromBody(raw, status) {
+    try {
+        const body = JSON.parse(raw);
+        if (isHostEnvelope(body) && !body.ok) {
+            return new PluginBridgeError(body.error_code ?? "PLUGIN_STREAM_FAILED", body.error ?? `Plugin stream endpoint failed with HTTP ${status}`, body.data, body.error_details ?? body.data);
+        }
+    }
+    catch {
+        // Fall back to a generic error when the stream endpoint did not return JSON.
+    }
+    return new PluginBridgeError("PLUGIN_STREAM_FAILED", `Plugin stream endpoint failed with HTTP ${status}`);
+}
+function isStreamEvent(value) {
+    return isRecord(value) &&
+        typeof value.stream_id === "string" &&
+        typeof value.sequence === "number" &&
+        typeof value.kind === "string" &&
+        (value.data == null || typeof value.data === "string") &&
+        (value.error == null || typeof value.error === "string") &&
+        typeof value.at === "string";
+}
+function isLifecycleMessage(value) {
+    if (!isRecord(value) || value.type !== "redevplugin.bridge.lifecycle" || !isRecord(value.event)) {
+        return false;
+    }
+    return value.event.type === "ready" || value.event.type === "visible" || value.event.type === "hidden" || value.event.type === "dispose";
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isPluginRiskFlag(value) {
+    return isRecord(value) &&
+        typeof value.id === "string" &&
+        isPluginRiskSeverity(value.severity) &&
+        typeof value.summary === "string" &&
+        (value.description == null || typeof value.description === "string") &&
+        (value.requires_confirmation == null || typeof value.requires_confirmation === "boolean") &&
+        (value.requires_admin == null || typeof value.requires_admin === "boolean") &&
+        (value.data_loss_risk == null || typeof value.data_loss_risk === "boolean") &&
+        (value.destructive == null || typeof value.destructive === "boolean");
+}
+function isPluginRiskSeverity(value) {
+    return value === "info" || value === "low" || value === "medium" || value === "high" || value === "critical";
+}
+function isPluginRiskEffect(value) {
+    return value === "read" || value === "write" || value === "execute" || value === "delete" || value === "admin";
+}
+function validRPCParams(value) {
+    return value == null || (isRecord(value) && !Array.isArray(value));
+}
+function confirmationDecisionAccepted(decision) {
+    return typeof decision === "boolean" ? decision : decision.confirmed;
+}
+function handshakeMatchesBootstrap(handshake, bootstrap) {
+    return handshake.plugin_id === bootstrap.pluginId &&
+        handshake.surface_id === bootstrap.surfaceId &&
+        handshake.surface_instance_id === bootstrap.surfaceInstanceId &&
+        handshake.active_fingerprint === bootstrap.activeFingerprint &&
+        handshake.bridge_nonce === bootstrap.bridgeNonce &&
+        handshake.ui_protocol_version === "plugin-ui-v1";
+}
+function toBridgeError(error, fallbackCode) {
+    if (error instanceof PluginBridgeError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new PluginBridgeError(fallbackCode, error.message);
+    }
+    return new PluginBridgeError(fallbackCode, String(error));
+}