@sequenceholdings/storage 0.1.0

package/README.md

@@ -0,0 +1,91 @@
+# Atlas storage client
+
+Typed Workspaces V2 metadata and direct-to-GCS sequential resumable transfers.
+Initial release is pending publication and public-contract review.
+
+```ts
+import { createStorageClient } from '@sequenceholdings/storage'
+
+const storage = createStorageClient({ baseUrl: atlasUrl, getToken: authenticatedToken })
+const workspace = storage.workspace(workspaceId)
+const result = await workspace.uploads.put({
+  path: 'reports/quarterly.pdf', parentId: null,
+  contentType: 'application/pdf',
+}, fileBlob, { onProgress: uploadedBytes => console.log(uploadedBytes) })
+// Store result.fileId (and optionally result.versionId) in your application's data model.
+```
+
+`uploads.start` returns an upload ID before transfer. Keep that ID for
+`uploads.resume(id, originalSource)`. Source can be a Blob, Web ReadableStream or
+Node async iterable. The client retains fixed-size chunks, probes GCS offsets and
+retries transient failures. Supply `size` when known (up to 50 GiB); a stream without
+one reserves 1 GiB and fails once it exceeds that. Pass `signal` to stop transfer, then
+either resume or `uploads.abort(id)` to release the reservation. When `put` fails after
+starting a session it aborts the session for you; pass `{ keepSessionOnFailure: true }`
+to keep it and `resume` later. `put` generates an `idempotencyKey` unless you pass
+one and reuses it whenever it resends `start`, which `start` itself does after a
+timeout, a lost reply or a 5xx: the server replays a start that committed, so it
+never leaves an unnamed session holding one of your 20 pending uploads per
+workspace. Small Blobs can use
+`{ method: 'simple' }`; sequential resumable is the default. Parallel multipart is
+not included. Do not log the session URL: it is a bearer credential.
+
+`resume` and `put` compute a CRC32C over the whole source as they read it (from
+byte zero, including the prefix a resume skips) and send it on completion; Atlas
+aborts the session with `409` if the stored object differs, which is how a resume
+with a source that yields different bytes is caught. If you transfer bytes yourself
+with `transferStorageUpload`, pass its result: `uploads.complete(id, { crc32c })`.
+`Crc32c` (incremental `update(bytes)` / `digest()`) and `crc32c(bytes)` are exported
+for producers that want to declare `checksum` at start. The completion field is
+optional today and becomes required once in-repo consumers ship this SDK.
+
+Replace a file by supplying `fileId` and its `expectedRevision`. Concurrent stale
+replacement fails with `409`; reload before retrying. Completion is idempotent.
+While a just-committed permission change is still being applied, Atlas answers
+`503 permissions_pending`; while other changes hold the workspace, `503
+storage_busy`. The client retries both on reads, upload `start`/`complete`/`abort`,
+`createFolder` and manifest `apply` (replay-safe) for ~10 seconds; other mutations are not retried,
+because the change may already have been applied, so refresh before repeating one.
+`createFolder` sends an `idempotencyKey` (generated per call, or pass
+`{ idempotencyKey }` to cover your own retries), so a resend returns the folder
+it already created instead of `409`. `createStorageClient` bounds each metadata request with `requestTimeoutMs`
+(default 30 s, `0` disables); a timeout surfaces as `request_timeout`.
+`versions`, `restoreVersion` and `deleteVersion` manage immutable history. Restore
+creates a new revision without copying bytes. `update` renames/moves metadata while
+preserving file IDs. `trash`/`restore` are reversible; `purge` and workspace `delete`
+return durable receipts from `operations` (yours by default; `{ scope: 'workspace' }`
+lists everyone's for workspace Admins). Poll these until `succeeded`; failed runs
+requeue automatically, and `retryOperation` restarts one marked `failed` after
+correcting its cause.
+
+In an Artifact, use the trusted host's Blob transfer bridge:
+
+```ts
+import { createArtifactStorageClient } from '@sequenceholdings/artifact-studio'
+const workspace = createArtifactStorageClient().workspace(workspaceId)
+await workspace.uploads.put(input, file, {
+  onProgress: ({ uploadedBytes }) => updateProgress(uploadedBytes),
+})
+```
+
+Declare `capabilities.storage` as a map from workspace UUID to `viewer`, `editor`
+or `admin`. The declaration only limits reach; the caller also needs resource
+permissions. A folder-only grant is sufficient for that folder's resources.
+
+In a Managed Function, use invocation headers, never a caller-supplied token or URL:
+
+```ts
+import { createFunctionStorageClient } from '@sequenceholdings/managed-functions'
+const storage = createFunctionStorageClient({ baseUrl: configuredAtlasUrl, headers: req.headers })
+const file = await storage.workspace(workspaceId).getNode(fileId)
+```
+
+User mode is the default. `{ mode: 'service' }` explicitly selects the manifest's
+attached platform service account, which needs its own storage grants. Declare
+`service_account`, `capabilities.storage` and hosted network egress to your Atlas
+host and `storage.googleapis.com`. Delegation expires after 15 minutes; resume in a
+fresh invocation when necessary. Signed download leases expire after 60 seconds.
+
+For local integration use the normal local Atlas environment, `seq-studio storage`
+and `functions deploy -e local`. File references in ORM remain application-owned;
+there is no automatic row-to-file authorization or deletion cascade.

package/dist/client.d.ts

@@ -0,0 +1,453 @@
+import { z } from 'zod';
+import { type CompleteStorageUpload, type StartStorageUpload, type StorageOperationScope, type WorkspaceManifest, type updateNodeSchema, type updateStorageAccessSchema } from './contracts.js';
+import { type StorageUploadSource, type StorageTransferOptions } from './transfer.js';
+export declare const STORAGE_TOKEN_HEADER = "x-sequence-storage-token";
+export declare const STORAGE_SERVICE_TOKEN_HEADER = "x-sequence-storage-token-service";
+export interface StorageTransport {
+    request(method: string, path: string, body?: unknown): Promise<unknown>;
+}
+export interface StorageListOptions {
+    cursor?: string;
+    limit?: number;
+    q?: string;
+    sort?: 'name' | 'newest';
+}
+export declare class StorageApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+/** Backoff for replay-safe requests (see `replayable`). */
+export interface StoragePermissionsRetry {
+    /** Total attempts including the first; 1 disables retrying. */
+    attempts?: number;
+    /** Ceiling of the first backoff; each later retry doubles it. */
+    baseDelayMs?: number;
+}
+export declare const storageDownloadSchema: z.ZodObject<{
+    url: z.ZodURL;
+    expiresAt: z.ZodString;
+    preview: z.ZodBoolean;
+}, z.core.$strip>;
+/** Supply a transport for an Artifact bridge, or use createStorageClient for HTTP. */
+export declare function storageClient(transport: StorageTransport, { permissionsRetry, }?: {
+    permissionsRetry?: StoragePermissionsRetry;
+}): {
+    capabilities: () => Promise<{
+        canProvision: boolean;
+        uploadMethods: string[];
+    }>;
+    list: (options?: StorageListOptions) => Promise<{
+        items: {
+            id: string;
+            name: string;
+            description: string;
+            environment: string;
+            state: "active" | "trashed" | "purging";
+            revision: number;
+            createdAt: string;
+            role: "viewer" | "editor" | "admin" | "owner";
+            quotaBytes: number;
+            usedBytes: number;
+            reservedBytes: number;
+        }[];
+        nextCursor: string | null;
+    }>;
+    shared: (options?: StorageListOptions & {
+        trash?: boolean;
+    }) => Promise<{
+        items: {
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }[];
+        nextCursor: string | null;
+    }>;
+    apply: (manifest: WorkspaceManifest) => Promise<{
+        id: string;
+        name: string;
+        description: string;
+        environment: string;
+        state: "active" | "trashed" | "purging";
+        revision: number;
+        createdAt: string;
+        role: "viewer" | "editor" | "admin" | "owner";
+        quotaBytes: number;
+        usedBytes: number;
+        reservedBytes: number;
+    }>;
+    workspace(id: string): {
+        get: () => Promise<{
+            id: string;
+            name: string;
+            description: string;
+            environment: string;
+            state: "active" | "trashed" | "purging";
+            revision: number;
+            createdAt: string;
+            role: "viewer" | "editor" | "admin" | "owner";
+            quotaBytes: number;
+            usedBytes: number;
+            reservedBytes: number;
+        }>;
+        delete: (expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            targetId: string | null;
+            kind: "purge" | "delete_version";
+            status: "queued" | "running" | "succeeded" | "failed";
+            completed: number;
+            total: number;
+            error: string | null;
+            createdAt: string;
+            updatedAt: string;
+            canRetry: boolean;
+        }>;
+        list: (options?: StorageListOptions & {
+            parentId?: string | null;
+            trash?: boolean;
+        }) => Promise<{
+            items: {
+                id: string;
+                workspaceId: string;
+                parentId: string | null;
+                name: string;
+                kind: "file" | "folder";
+                state: "active" | "trashed" | "purging";
+                restricted: boolean;
+                revision: number;
+                currentVersionId: string | null;
+                metadata: Record<string, string>;
+                createdAt: string;
+                updatedAt: string;
+                role: "viewer" | "editor" | "admin";
+                size: number | null;
+                contentType: string | null;
+            }[];
+            nextCursor: string | null;
+        }>;
+        getNode: (id: string) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        /**
+         * Keyed like upload start, so every resend (storage_busy,
+         * permissions_pending, a lost reply) returns the one folder it made.
+         * Pass `idempotencyKey` to extend that across your own retries.
+         */
+        createFolder: (name: string, parentId?: string | null, { idempotencyKey, }?: {
+            idempotencyKey?: string;
+        }) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        update: (id: string, input: z.input<typeof updateNodeSchema>) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        trash: (id: string, expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        restore: (id: string, expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            parentId: string | null;
+            name: string;
+            kind: "file" | "folder";
+            state: "active" | "trashed" | "purging";
+            restricted: boolean;
+            revision: number;
+            currentVersionId: string | null;
+            metadata: Record<string, string>;
+            createdAt: string;
+            updatedAt: string;
+            role: "viewer" | "editor" | "admin";
+            size: number | null;
+            contentType: string | null;
+        }>;
+        purge: (id: string, expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            targetId: string | null;
+            kind: "purge" | "delete_version";
+            status: "queued" | "running" | "succeeded" | "failed";
+            completed: number;
+            total: number;
+            error: string | null;
+            createdAt: string;
+            updatedAt: string;
+            canRetry: boolean;
+        }>;
+        download: (id: string, options?: {
+            versionId?: string;
+            preview?: boolean;
+        }) => Promise<{
+            url: string;
+            expiresAt: string;
+            preview: boolean;
+        }>;
+        versions: (id: string, options?: {
+            before?: number;
+            limit?: number;
+        }) => Promise<{
+            items: {
+                id: string;
+                fileId: string;
+                revision: number;
+                size: number;
+                checksum: string;
+                contentType: string;
+                createdAt: string;
+                createdBy: string;
+                state: "active" | "purging";
+            }[];
+            nextRevision: number | null;
+        }>;
+        restoreVersion: (id: string, versionId: string, expectedRevision: number) => Promise<{
+            id: string;
+            fileId: string;
+            revision: number;
+            size: number;
+            checksum: string;
+            contentType: string;
+            createdAt: string;
+            createdBy: string;
+            state: "active" | "purging";
+        }>;
+        deleteVersion: (id: string, versionId: string, expectedRevision: number) => Promise<{
+            id: string;
+            workspaceId: string;
+            targetId: string | null;
+            kind: "purge" | "delete_version";
+            status: "queued" | "running" | "succeeded" | "failed";
+            completed: number;
+            total: number;
+            error: string | null;
+            createdAt: string;
+            updatedAt: string;
+            canRetry: boolean;
+        }>;
+        access: (id?: string) => Promise<{
+            revision: number;
+            restricted: boolean;
+            grants: {
+                type: "user" | "group" | "organization" | "service_account";
+                id: string;
+                role: "viewer" | "editor" | "admin";
+            }[];
+            owner: string | null;
+            inherited: boolean;
+            workspaceAdminOverride: true;
+            displayNames: Record<string, string>;
+        }>;
+        setAccess: (input: z.input<typeof updateStorageAccessSchema>, id?: string) => Promise<{
+            revision: number;
+            restricted: boolean;
+            grants: {
+                type: "user" | "group" | "organization" | "service_account";
+                id: string;
+                role: "viewer" | "editor" | "admin";
+            }[];
+            owner: string | null;
+            inherited: boolean;
+            workspaceAdminOverride: true;
+            displayNames: Record<string, string>;
+        }>;
+        transferOwner: (principal: {
+            type: "user" | "service_account";
+            id: string;
+        }, expectedRevision: number) => Promise<{
+            revision: number;
+            restricted: boolean;
+            grants: {
+                type: "user" | "group" | "organization" | "service_account";
+                id: string;
+                role: "viewer" | "editor" | "admin";
+            }[];
+            owner: string | null;
+            inherited: boolean;
+            workspaceAdminOverride: true;
+            displayNames: Record<string, string>;
+        }>;
+        operations: (options?: {
+            before?: string;
+            limit?: number;
+            scope?: StorageOperationScope;
+        }) => Promise<{
+            items: {
+                id: string;
+                workspaceId: string;
+                targetId: string | null;
+                kind: "purge" | "delete_version";
+                status: "queued" | "running" | "succeeded" | "failed";
+                completed: number;
+                total: number;
+                error: string | null;
+                createdAt: string;
+                updatedAt: string;
+                canRetry: boolean;
+            }[];
+            nextCursor: string | null;
+        }>;
+        retryOperation: (id: string) => Promise<{
+            id: string;
+            workspaceId: string;
+            targetId: string | null;
+            kind: "purge" | "delete_version";
+            status: "queued" | "running" | "succeeded" | "failed";
+            completed: number;
+            total: number;
+            error: string | null;
+            createdAt: string;
+            updatedAt: string;
+            canRetry: boolean;
+        }>;
+        uploads: {
+            start: (input: StartStorageUpload) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            get: (id: string) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            /** `resume` passes the CRC32C it computed; pass your own when transferring bytes yourself. */
+            complete: (id: string, input?: CompleteStorageUpload) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            abort: (id: string) => Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            resume(id: string, source: StorageUploadSource, options?: StorageTransferOptions & {
+                size?: number;
+            }): Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+            /**
+             * Start, transfer and complete in one call. A failure after the session
+             * starts aborts it (best effort) to release its reservation; pass
+             * `keepSessionOnFailure` to keep it for a manual `resume`.
+             */
+            put(input: Omit<StartStorageUpload, "idempotencyKey"> & {
+                /** Defaults to a fresh key per put, reused across its start retries. */
+                idempotencyKey?: string;
+            }, source: StorageUploadSource, { keepSessionOnFailure, ...options }?: StorageTransferOptions & {
+                keepSessionOnFailure?: boolean;
+            }): Promise<{
+                id: string;
+                fileId: string;
+                uploadUrl: string | null;
+                expiresAt: string;
+                state: "pending" | "complete" | "aborted";
+                versionId: string | null;
+                maxBytes: number;
+            }>;
+        };
+    };
+};
+export type StorageClient = ReturnType<typeof storageClient>;
+export declare function createStorageClient({ baseUrl, getToken, getHeaders, fetch: fetcher, permissionsRetry, requestTimeoutMs, }: {
+    baseUrl: string;
+    getToken?: () => string | Promise<string>;
+    getHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+    fetch?: typeof fetch;
+    permissionsRetry?: StoragePermissionsRetry;
+    /**
+     * Per metadata request, including reading the reply; 0 disables it. Byte
+     * transfer goes to the provider directly and is not bounded by this.
+     */
+    requestTimeoutMs?: number;
+}): StorageClient;