@floegence/redevplugin-ui 3.4.0 → 3.5.0

package/dist/platform.d.ts

@@ -1,5 +1,6 @@
 import { type FetchLike } from "./http.js";
 import type { components } from "./openapi.gen.js";
+import type { PluginFileAccessConfirmation } from "./files.js";
 import { type PluginConfirmationHandler, type PluginWebOriginPreparationHandler, type PluginSurfaceHost, type PluginSurfaceContext, type PluginSurfaceOpeningProgress, type PluginSurfaceInteractionEvent, type PluginSurfaceFileExportHandler, type PluginSurfaceReloadLimiter, type PluginSurfaceSlot, type PluginMethodResult, type ReDevPluginSurfaceTransport } from "./surface.js";
 import { type PluginSurfaceScope } from "./surface-scope.js";
 export type PluginPlatformClientOptions = {
@@ -41,6 +42,7 @@ export type PluginDisableRequest = PlatformSchemas["DisableRequest"];
 export type PluginUninstallRequest = PlatformSchemas["UninstallRequest"];
 export type PluginOpenSurfaceRequest = PlatformSchemas["OpenSurfaceRequest"];
 export type PluginOpenSurfaceInSlotOptions = PluginRequestOptions & {
+    confirmFileAccess?: PluginFileAccessConfirmation;
     bridgeChannelId?: string;
     loadTimeoutMs?: number;
     requestTimeoutMs?: number;
@@ -170,6 +172,15 @@ export declare class PluginPlatformClient {
     listRetainedData(options?: PluginRetainedDataListOptions, requestOptions?: PluginRequestOptions): Promise<PluginRetainedDataList>;
     deleteRetainedData(request: PluginRetainedDataDeleteRequest, options?: PluginRequestOptions): Promise<PluginDataBinding>;
     cleanupExpiredRetainedData(request?: PluginRetainedDataCleanupRequest, options?: PluginRequestOptions): Promise<PluginRetainedDataCleanupResult>;
+    selectFileResource(request: PlatformSchemas["FileSelectRequest"], options?: PluginRequestOptions): Promise<PlatformSchemas["SelectFileResourceSuccessResponse"]["data"]>;
+    approveFileResource(request: PlatformSchemas["FileReviewRequest"], options?: PluginRequestOptions): Promise<PlatformSchemas["FileResource"]>;
+    cancelFileResource(request: PlatformSchemas["FileReviewRequest"], options?: PluginRequestOptions): Promise<{
+        canceled: true;
+    }>;
+    listFileResources(request: PlatformSchemas["FileListRequest"], options?: PluginRequestOptions): Promise<PlatformSchemas["ListFileResourcesSuccessResponse"]["data"]>;
+    revokeFileResource(request: PlatformSchemas["FileRevokeRequest"], options?: PluginRequestOptions): Promise<{
+        revoked: true;
+    }>;
     listPermissions(options?: PluginPermissionListOptions, requestOptions?: PluginRequestOptions): Promise<PluginPermissionList>;
     getPermissionRequirements(request: PluginPermissionRequirementsRequest, options?: PluginRequestOptions): Promise<PluginPermissionRequirements>;
     grantPermission(request: PluginPermissionGrantRequest, options?: PluginRequestOptions): Promise<PluginPermissionMutationResult>;

package/dist/platform.js

@@ -261,6 +261,21 @@ export class PluginPlatformClient {
     cleanupExpiredRetainedData(request = {}, options = {}) {
         return this.#requestMutation("POST", "/_redevplugin/api/plugins/retained-data/cleanup-expired", request, options);
     }
+    selectFileResource(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/file-resources/select", request, options);
+    }
+    approveFileResource(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/file-resources/approve", request, options);
+    }
+    cancelFileResource(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/file-resources/cancel", request, options);
+    }
+    listFileResources(request, options = {}) {
+        return this.#requestQuery("/_redevplugin/api/plugins/file-resources/query", request, options);
+    }
+    revokeFileResource(request, options = {}) {
+        return this.#requestMutation("POST", "/_redevplugin/api/plugins/file-resources/revoke", request, options);
+    }
     listPermissions(options = {}, requestOptions = {}) {
         return this.#requestQuery("/_redevplugin/api/plugins/permissions/query", options, requestOptions);
     }

package/dist/plugin.d.ts

@@ -1,4 +1,6 @@
 export { PluginBridgeClient } from "./surface.js";
+export { PluginFilesClient, PluginFileHandle, PluginFileWriteError } from "./files.js";
+export type { PluginFileResource, PluginFileSelectionOptions, PluginFileOpenOptions, PluginFileStat, PluginDirectoryEntry } from "./files.js";
 export { PluginBridgeError } from "./errors.js";
 export { pluginAPIMajor } from "./contracts.gen.js";
 export { createPluginProcessClient } from "./process.js";

package/dist/plugin.js

@@ -1,4 +1,5 @@
 export { PluginBridgeClient } from "./surface.js";
+export { PluginFilesClient, PluginFileHandle, PluginFileWriteError } from "./files.js";
 export { PluginBridgeError } from "./errors.js";
 export { pluginAPIMajor } from "./contracts.gen.js";
 export { createPluginProcessClient } from "./process.js";

package/dist/surface.d.ts

@@ -1,3 +1,4 @@
+import { PluginFilesClient, type PluginFileAccessConfirmation } from "./files.js";
 import { PluginBridgeError, type PluginMutationOutcome } from "./errors.js";
 import { type FetchLike } from "./http.js";
 import { type PluginSurfaceScope } from "./surface-scope.js";
@@ -242,6 +243,7 @@ export type PluginBridgeRequestOptions = {
 };
 export declare class PluginBridgeClient {
     #private;
+    readonly files: PluginFilesClient;
     readonly surfaceHandle: string;
     readonly timeoutMs: number;
     constructor(options?: PluginBridgeClientOptions);
@@ -380,6 +382,7 @@ export type PluginWebOriginPreparation = Readonly<{
 /** Prepare only the allocated route; return no URL, token, or alternate bootstrap. */
 export type PluginWebOriginPreparationHandler = (request: PluginWebOriginPreparation) => void | Promise<void>;
 export type PluginSurfaceHostOptions = {
+    confirmFileAccess?: PluginFileAccessConfirmation;
     bootstrap: PluginSurfaceHostBootstrap;
     hostTransport: ReDevPluginSurfaceTransport;
     surfaceScope?: PluginSurfaceScope;

package/dist/surface.js

@@ -1,4 +1,5 @@
 import { sha256 } from "@noble/hashes/sha2.js";
+import { PluginFilesClient, isPluginFileResource, isPluginFileResourceReview, validFileIORequest } from "./files.js";
 import { bytesToHex } from "@noble/hashes/utils.js";
 import { PluginBridgeError, PluginPlatformRequestError, PluginTransportError, pluginBridgeErrorCodes, } from "./errors.js";
 import { pluginBridgeCapabilityEffect, } from "./bridge-capability.js";
@@ -29,6 +30,7 @@ const hostCapabilityIDPattern = new RegExp("^[A-Za-z0-9][A-Za-z0-9._-]*$");
 const lowercaseSHA256Pattern = new RegExp("^[0-9a-f]{64}$");
 const businessErrorCodePattern = new RegExp("^[A-Z][A-Z0-9_]*$");
 export class PluginBridgeClient {
+    files = new PluginFilesClient((request, options) => this.#fileIO(request, options));
     surfaceHandle;
     timeoutMs;
     #nextID = 1;
@@ -74,6 +76,13 @@ export class PluginBridgeClient {
         const effect = options[pluginBridgeCapabilityEffect];
         return this.#call(method, params, options, effect === undefined || effect !== "read");
     }
+    #fileIO(request, options = {}) {
+        this.#assertActive();
+        if (!validFileIORequest(request))
+            throw new PluginBridgeError("PLUGIN_INVALID_REQUEST", "File operation is invalid");
+        const id = this.#requestID("file");
+        return this.#request(id, { type: "redevplugin.bridge.file_io", id, request }, { mutation: true, signal: options.signal });
+    }
     #call(method, params, options, mutation) {
         this.#assertActive();
         if (!validMethod(method)) {
@@ -573,6 +582,7 @@ class PluginSurfaceHostImplementation {
     #leaseRenewalLeadMs;
     #reloadLimiter;
     #confirm;
+    #confirmFileAccess;
     #prepareWebOrigin;
     #onOpeningProgress;
     #onInteraction;
@@ -662,6 +672,7 @@ class PluginSurfaceHostImplementation {
         this.#leaseRenewalLeadMs = normalizeLeaseRenewalLead(options.leaseRenewalLeadMs);
         this.#reloadLimiter = options.reloadLimiter ?? new PluginSurfaceReloadLimiter();
         this.#confirm = options.confirm;
+        this.#confirmFileAccess = options.confirmFileAccess;
         this.#prepareWebOrigin = options.prepareWebOrigin;
         this.#onOpeningProgress = options.onOpeningProgress;
         this.#onInteraction = options.onInteraction;
@@ -1073,6 +1084,12 @@ class PluginSurfaceHostImplementation {
                 await this.#handleCall(data.request);
                 return;
             }
+            if (hasExactKeys(data, ["type", "id", "request", "frame_generation_id", "surface_handle"]) && data.type === "redevplugin.surface.file_io" && validBridgeRequestID(data.id, "file") && validFileIORequest(data.request)) {
+                if (data.frame_generation_id !== this.frameGenerationId || data.surface_handle !== this.surfaceHandle)
+                    return;
+                await this.#handleFileIO(data.id, data.request);
+                return;
+            }
             if (isExecutionCancelMessage(data)) {
                 await this.#handleExecutionCancel(data);
                 return;
@@ -1184,6 +1201,61 @@ class PluginSurfaceHostImplementation {
                 this.#pendingRequestControllers.delete(request.id);
         }
     }
+    async #handleFileIO(id, request) {
+        if (!this.#ready || !this.#bridgeReady || !this.#gatewayToken) {
+            this.#postError(id, "PLUGIN_BRIDGE_HANDSHAKE_REQUIRED", "File operation arrived before the surface became ready");
+            return;
+        }
+        if (request.operation === "select" && !this.#confirmFileAccess) {
+            this.#postError(id, "PLUGIN_FEATURE_NOT_CONFIGURED", "File access confirmation is not configured");
+            return;
+        }
+        const controller = this.#registerPendingRequest(id);
+        let reviewID;
+        let approvalSent = false;
+        try {
+            let result = await this.#postMutationJSON("/_redevplugin/api/plugins/file-resources/surface-io", () => ({ plugin_instance_id: this.bootstrap.pluginInstanceId, surface_instance_id: this.bootstrap.surfaceInstanceId, bridge_channel_id: this.bridgeChannelId, plugin_gateway_token: this.#gatewayToken, ...request }), controller.signal);
+            if (request.operation === "select" && result.canceled !== true) {
+                if (!isPluginFileResourceReview(result.review) || result.review.plugin_instance_id !== this.bootstrap.pluginInstanceId)
+                    throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "File review is invalid");
+                reviewID = result.review.review_id;
+                const approved = await abortableConfirmationDecision(this.#confirmFileAccess({ ...result.review, signal: controller.signal }), controller.signal);
+                if (controller.signal.aborted || this.#disposed)
+                    return;
+                if (!confirmationDecisionAccepted(approved)) {
+                    await this.#postMutationJSON("/_redevplugin/api/plugins/file-resources/cancel", { plugin_instance_id: this.bootstrap.pluginInstanceId, review_id: reviewID }, controller.signal);
+                    reviewID = undefined;
+                    result = { canceled: true };
+                }
+                else {
+                    approvalSent = true;
+                    const resource = await this.#postMutationJSON("/_redevplugin/api/plugins/file-resources/approve", { plugin_instance_id: this.bootstrap.pluginInstanceId, review_id: reviewID }, controller.signal);
+                    if (!isPluginFileResource(resource))
+                        throw new PluginBridgeError("PLUGIN_CONTRACT_MISMATCH", "Approved file resource is invalid");
+                    reviewID = undefined;
+                    result = { resource };
+                }
+            }
+            if (!controller.signal.aborted && !this.#disposed)
+                this.#postResponse(id, result);
+        }
+        catch (error) {
+            if (controller.signal.aborted || this.#disposed)
+                return;
+            const failure = toBridgeError(error, "PLUGIN_INTERNAL_FAILURE");
+            this.#postError(id, failure.errorCode, failure.message, failure.details, failure.mutationOutcome);
+        }
+        finally {
+            if (reviewID && !approvalSent) {
+                try {
+                    await this.#fetchJSONRequest("/_redevplugin/api/plugins/file-resources/cancel", { plugin_instance_id: this.bootstrap.pluginInstanceId, review_id: reviewID }, { mutation: true, independentLifecycle: true });
+                }
+                catch { /* Expired reviews are reclaimed by Host maintenance. */ }
+            }
+            if (this.#pendingRequestControllers.get(id) === controller)
+                this.#pendingRequestControllers.delete(id);
+        }
+    }
     async #handleConfirmationRequired(request, originalError, signal) {
         if (!this.#confirm) {
             this.#postError(request.id, originalError.errorCode, originalError.message, originalError.details, originalError.mutationOutcome);
@@ -2421,6 +2493,8 @@ function isBridgeResponse(value) {
         return isCapabilityBusinessErrorDetails(value.error_details);
     if (value.error_code === "PLUGIN_WORKER_ERROR")
         return isWorkerErrorDetails(value.error_details);
+    if (value.error_code === "PLUGIN_FILE_OPERATION_FAILED")
+        return hasExactKeys(value.error_details, ["file_error_code", "file_retryable"]) && typeof value.error_details.file_retryable === "boolean" && ["INVALID_ARGUMENT", "PERMISSION_DENIED", "NOT_FOUND", "NOT_EMPTY", "ALREADY_EXISTS", "RESOURCE_CLOSED", "RESOURCE_LIMIT", "CROSS_DEVICE", "MOUNT_UNAVAILABLE", "RUNTIME_UNAVAILABLE", "CANCELED", "TIMEOUT", "IO_ERROR"].includes(String(value.error_details.file_error_code));
     if (value.error_details === undefined)
         return true;
     try {

package/dist/testing.d.ts

@@ -18,6 +18,7 @@ export declare function createPluginTestHarness(options?: PluginTestHarnessOptio
     mode: "fixture";
     BridgeClient: {
         new (clientOptions?: PluginBridgeClientOptions): {
+            readonly files: import("./files.js").PluginFilesClient;
             readonly surfaceHandle: string;
             readonly timeoutMs: number;
             "__#private@#nextID": number;
@@ -45,6 +46,7 @@ export declare function createPluginTestHarness(options?: PluginTestHarnessOptio
             "__#private@#onMessage": (event: MessageEventLike) => void;
             ready(): Promise<void>;
             call<T = unknown>(method: string, params?: PluginJSONObject, options?: import("./surface.js").PluginBridgeRequestOptions): Promise<T>;
+            "__#private@#fileIO"(request: import("./files.js").PluginFileIORequest, options?: import("./surface.js").PluginBridgeRequestOptions): Promise<import("./files.js").PluginFileIOResult>;
             "__#private@#call"<T>(method: string, params: PluginJSONObject | undefined, options: import("./surface.js").PluginBridgeRequestOptions, mutation: boolean): Promise<T>;
             executionEvents(executionID: string, afterCursor: number, options?: import("./surface.js").PluginBridgeRequestOptions): Promise<import("./surface.js").PluginExecutionEventList>;
             cancelExecution(executionID: string, reason?: string, options?: import("./surface.js").PluginBridgeRequestOptions): Promise<void>;

package/dist/trusted-parent.d.ts

@@ -5,3 +5,4 @@ export { PluginSurfaceScope, createPluginSurfaceScope } from "./surface-scope.js
 export { PluginSurfaceReloadLimiter, PluginSurfaceSlot, createReDevPluginSurfaceTransport, defaultPluginSurfaceReloadMax, defaultPluginSurfaceReloadWindowMs, isPluginRiskPlan, webSurfaceDocumentSchemaVersion, pluginSurfaceContextSchemaVersion, pluginRiskPlanSchemaVersion, pluginSurfaceFileExportMaxBytes, pluginSurfaceFileExportMediaTypes, trustedParentBridgeHandshakeTranscriptSHA256, } from "./surface.js";
 export type { BridgeLifecycleEvent, MessageChannelLike, MessageEventLike, MessagePortLike, WebSurfaceDocument, PluginConfirmationDecision, PluginConfirmationHandler, PluginConfirmationIntent, PluginConfirmationPlan, PluginMethodResult, PluginRiskEffect, PluginRiskFlag, PluginRiskPlan, PluginRiskSeverity, PluginExecutionEvent, PluginSurfaceHost, PluginWebOriginPreparation, PluginWebOriginPreparationHandler, PluginSurfaceCloseResult, PluginSurfaceOpeningProgress, PluginSurfaceOpeningStage, PluginSurfaceOpeningMilestone, PluginSurfaceInteractionEvent, PluginSurfaceInteractionKind, PluginSurfaceFileExport, PluginSurfaceFileExportHandler, PluginSurfaceFileExportMediaType, PluginSurfaceQuiesceResult, PluginSurfaceRevocationReconciliation, PluginSurfacePreparationResult, PluginSurfaceContext, PluginSurfaceReloadDecision, PluginSurfaceReloadLimiterOptions, PluginSurfaceReloadState, PluginSurfaceSlotOptions, PluginSurfaceSlotState, ReDevPluginSurfaceTransport, ReDevPluginSurfaceTransportOptions, TrustedParentBridgeHandshake, TrustedParentBridgeTokenRequest, WindowLike, } from "./surface.js";
 export type { FetchInitLike, FetchLike, FetchResponseLike, PlatformResponse } from "./http.js";
+export type { PluginFileAccessConfirmation, PluginFileResourceReview, PluginFileResource } from "./files.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@floegence/redevplugin-ui",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -36,7 +36,7 @@
     "dist"
   ],
   "dependencies": {
-    "@floegence/redevplugin-contracts": "3.4.0",
+    "@floegence/redevplugin-contracts": "3.5.0",
     "@noble/hashes": "2.4.0"
   },
   "publishConfig": {