@sylphx/contract 0.2.1 → 0.4.0

package/dist/endpoints/storage.d.ts

@@ -1,165 +1,223 @@
 /**
- * Storage endpoints — BaaS plane. Paths mirror `@sylphx/sdk/storage.ts`.
+ * Storage endpoints — BaaS plane. Per ADR-100.
+ *
+ * One resource (`uploads`) for upload sessions, one resource (`files`) for
+ * everything else. Verb suffix `:action` on `files` follows Google AIP-136.
+ *
+ * No legacy aliases. No polymorphic POSTs. Mirrors `@sylphx/sdk/storage.ts`.
  */
 import { Schema } from 'effect';
 export declare const storageEndpoints: {
-    /**
-     * Mint an upload token for client-direct uploads. Returns either a
-     * simple `{ uploadUrl, publicUrl }` pair or a Vercel-Blob-style
-     * `{ uploadEndpoint, clientPayload, instructions }` envelope.
-     * This is the SDK's primary upload path (`uploadFile` / `uploadAvatar`).
-     */
-    readonly upload: import("../endpoint.js").Endpoint<"POST", "/storage/upload", Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
-        filename: typeof Schema.String;
-        contentType: Schema.optional<typeof Schema.String>;
-        size: Schema.optional<typeof Schema.Number>;
-        path: Schema.optional<typeof Schema.String>;
-        type: Schema.optional<Schema.Literal<["file", "avatar"]>>;
-        userId: Schema.optional<typeof Schema.String>;
+    readonly createUpload: import("../endpoint.js").Endpoint<"POST", "/storage/uploads", Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        filename: Schema.filter<typeof Schema.String>;
+        contentType: Schema.filter<typeof Schema.String>;
+        size: Schema.filter<typeof Schema.Number>;
+        folder: Schema.optional<typeof Schema.String>;
+        visibility: Schema.optional<Schema.Literal<["public", "private"]>>;
         metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+        checksumSha256: Schema.optional<typeof Schema.String>;
+        ifNoneMatch: Schema.optional<Schema.Literal<["*"]>>;
+    }>, Schema.Union<[Schema.Struct<{
+        method: Schema.Literal<["PUT"]>;
+        uploadId: Schema.brand<typeof Schema.String, "UploadId">;
+        fileId: Schema.brand<typeof Schema.String, "FileId">;
+        url: typeof Schema.String;
+        headers: Schema.Record$<typeof Schema.String, typeof Schema.String>;
+        expiresAt: typeof Schema.DateFromString;
+    }>, Schema.Struct<{
+        method: Schema.Literal<["MULTIPART"]>;
+        uploadId: Schema.brand<typeof Schema.String, "UploadId">;
+        fileId: Schema.brand<typeof Schema.String, "FileId">;
+        partSize: typeof Schema.Number;
+        partCount: typeof Schema.Number;
+        parts: Schema.Array$<Schema.Struct<{
+            partNumber: Schema.filter<typeof Schema.Number>;
+            url: typeof Schema.String;
+            expiresAt: typeof Schema.DateFromString;
+        }>>;
+        expiresAt: typeof Schema.DateFromString;
+    }>]>>;
+    readonly abortUpload: import("../endpoint.js").Endpoint<"DELETE", "/storage/uploads/:uploadId", Schema.Struct<{
+        uploadId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{}>>;
+    readonly presignUploadPart: import("../endpoint.js").Endpoint<"POST", "/storage/uploads/:uploadId/parts/:partNumber", Schema.Struct<{
+        uploadId: typeof Schema.String;
+        partNumber: typeof Schema.NumberFromString;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        url: typeof Schema.String;
+        expiresAt: typeof Schema.DateFromString;
+    }>>;
+    readonly completeUpload: import("../endpoint.js").Endpoint<"POST", "/storage/uploads/:uploadId:complete", Schema.Struct<{
+        uploadId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        parts: Schema.Array$<Schema.Struct<{
+            partNumber: Schema.filter<typeof Schema.Number>;
+            etag: Schema.filter<typeof Schema.String>;
+        }>>;
     }>, Schema.Struct<{
-        uploadUrl: Schema.optional<typeof Schema.String>;
-        publicUrl: Schema.optional<typeof Schema.String>;
-        fileId: Schema.optional<typeof Schema.String>;
-        expiresAt: Schema.optional<typeof Schema.String>;
-        presignedUrl: Schema.optional<typeof Schema.String>;
-        storageKey: Schema.optional<typeof Schema.String>;
-        tokenPayload: Schema.optional<typeof Schema.String>;
-        url: Schema.optional<typeof Schema.String>;
-        uploadEndpoint: Schema.optional<typeof Schema.String>;
-        clientPayload: Schema.optional<typeof Schema.String>;
-        maxSize: Schema.optional<typeof Schema.Number>;
-        maxMultipartSize: Schema.optional<typeof Schema.Number>;
-        multipartThreshold: Schema.optional<typeof Schema.Number>;
-        allowedContentTypes: Schema.optional<Schema.Array$<typeof Schema.String>>;
-        instructions: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+        fileId: Schema.brand<typeof Schema.String, "FileId">;
+        url: Schema.NullOr<typeof Schema.String>;
+        size: typeof Schema.Number;
+        etag: typeof Schema.String;
+        checksumSha256: typeof Schema.String;
     }>>;
-    readonly presignedUrl: import("../endpoint.js").Endpoint<"POST", "/storage/upload-url", Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+    readonly listFiles: import("../endpoint.js").Endpoint<"GET", "/storage/files", Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        folder: Schema.optional<typeof Schema.String>;
+        cursor: Schema.optional<typeof Schema.String>;
+        limit: Schema.optional<typeof Schema.Number>;
+        includeDeleted: Schema.optional<typeof Schema.Boolean>;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        files: Schema.Array$<Schema.Struct<{
+            id: Schema.brand<typeof Schema.String, "FileId">;
+            filename: typeof Schema.String;
+            contentType: typeof Schema.String;
+            size: typeof Schema.Number;
+            checksumSha256: typeof Schema.String;
+            etag: typeof Schema.String;
+            visibility: Schema.Literal<["public", "private"]>;
+            folder: Schema.NullOr<typeof Schema.String>;
+            metadata: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+            url: Schema.NullOr<typeof Schema.String>;
+            isDeleted: typeof Schema.Boolean;
+            createdAt: typeof Schema.DateFromString;
+            updatedAt: typeof Schema.DateFromString;
+        }>>;
+        nextCursor: Schema.NullOr<typeof Schema.String>;
+    }>>;
+    readonly getFile: import("../endpoint.js").Endpoint<"GET", "/storage/files/:fileId", Schema.Struct<{
+        fileId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        id: Schema.brand<typeof Schema.String, "FileId">;
         filename: typeof Schema.String;
         contentType: typeof Schema.String;
-        size: Schema.optional<typeof Schema.Number>;
-    }>, Schema.Struct<{
-        uploadUrl: typeof Schema.String;
+        size: typeof Schema.Number;
+        checksumSha256: typeof Schema.String;
+        etag: typeof Schema.String;
+        visibility: Schema.Literal<["public", "private"]>;
+        folder: Schema.NullOr<typeof Schema.String>;
+        metadata: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+        url: Schema.NullOr<typeof Schema.String>;
+        isDeleted: typeof Schema.Boolean;
+        createdAt: typeof Schema.DateFromString;
+        updatedAt: typeof Schema.DateFromString;
+    }>>;
+    readonly deleteFile: import("../endpoint.js").Endpoint<"DELETE", "/storage/files/:fileId", Schema.Struct<{
         fileId: typeof Schema.String;
-        expiresAt: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        id: Schema.brand<typeof Schema.String, "FileId">;
+        isDeleted: Schema.Literal<[true]>;
+    }>>;
+    readonly restoreFile: import("../endpoint.js").Endpoint<"POST", "/storage/files/:fileId:restore", Schema.Struct<{
+        fileId: typeof Schema.String;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        id: Schema.brand<typeof Schema.String, "FileId">;
+        filename: typeof Schema.String;
+        contentType: typeof Schema.String;
+        size: typeof Schema.Number;
+        checksumSha256: typeof Schema.String;
+        etag: typeof Schema.String;
+        visibility: Schema.Literal<["public", "private"]>;
+        folder: Schema.NullOr<typeof Schema.String>;
+        metadata: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+        url: Schema.NullOr<typeof Schema.String>;
+        isDeleted: typeof Schema.Boolean;
+        createdAt: typeof Schema.DateFromString;
+        updatedAt: typeof Schema.DateFromString;
     }>>;
-    /**
-     * Generate a time-limited signed URL for accessing a private file.
-     * Signed URLs avoid exposing permanent credentials and can be scoped
-     * to a specific user via the `userId` field.
-     */
-    readonly signedUrl: import("../endpoint.js").Endpoint<"POST", "/storage/signed-url", Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+    readonly signFileUrl: import("../endpoint.js").Endpoint<"POST", "/storage/files/:fileId:signedUrl", Schema.Struct<{
         fileId: typeof Schema.String;
-        expiresIn: Schema.optional<typeof Schema.Number>;
+    }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
+        expiresIn: Schema.optional<Schema.filter<typeof Schema.Number>>;
         disposition: Schema.optional<Schema.Literal<["attachment", "inline"]>>;
         userId: Schema.optional<typeof Schema.String>;
     }>, Schema.Struct<{
         url: typeof Schema.String;
-        expiresAt: typeof Schema.String;
+        expiresAt: typeof Schema.DateFromString;
         file: Schema.Struct<{
-            id: typeof Schema.String;
+            id: Schema.brand<typeof Schema.String, "FileId">;
             filename: typeof Schema.String;
-            mimeType: typeof Schema.String;
-            sizeBytes: typeof Schema.Number;
-            isPrivate: typeof Schema.Boolean;
+            contentType: typeof Schema.String;
+            size: typeof Schema.Number;
+            checksumSha256: typeof Schema.String;
+            etag: typeof Schema.String;
+            visibility: Schema.Literal<["public", "private"]>;
+            folder: Schema.NullOr<typeof Schema.String>;
+            metadata: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+            url: Schema.NullOr<typeof Schema.String>;
+            isDeleted: typeof Schema.Boolean;
+            createdAt: typeof Schema.DateFromString;
+            updatedAt: typeof Schema.DateFromString;
         }>;
     }>>;
-    readonly list: import("../endpoint.js").Endpoint<"GET", "/storage/files", Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
-        prefix: Schema.optional<typeof Schema.String>;
-        limit: Schema.optional<typeof Schema.String>;
-        cursor: Schema.optional<typeof Schema.String>;
+    readonly copyFile: import("../endpoint.js").Endpoint<"POST", "/storage/files/:fileId:copy", Schema.Struct<{
+        fileId: typeof Schema.String;
     }>, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
-        files: Schema.Array$<Schema.Struct<{
-            id: typeof Schema.String;
-            size: typeof Schema.Number;
-            name: Schema.optional<typeof Schema.String>;
-            filename: Schema.optional<typeof Schema.String>;
-            path: Schema.optional<typeof Schema.String>;
-            key: Schema.optional<typeof Schema.String>;
-            url: Schema.optional<Schema.NullOr<typeof Schema.String>>;
-            contentType: Schema.optional<typeof Schema.String>;
-            mimeType: Schema.optional<typeof Schema.String>;
-            isPrivate: Schema.optional<typeof Schema.Boolean>;
-            metadata: Schema.optional<Schema.NullOr<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>>;
-            createdAt: Schema.optional<typeof Schema.String>;
-            uploadedAt: Schema.optional<typeof Schema.String>;
-        }>>;
-        nextCursor: Schema.NullOr<typeof Schema.String>;
-        hasMore: Schema.optional<typeof Schema.Boolean>;
-    }>>;
-    readonly get: import("../endpoint.js").Endpoint<"GET", "/storage/files/:id", Schema.Struct<{
-        id: typeof Schema.String;
-    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
-        id: typeof Schema.String;
-        size: typeof Schema.Number;
-        name: Schema.optional<typeof Schema.String>;
+        folder: Schema.optional<typeof Schema.String>;
         filename: Schema.optional<typeof Schema.String>;
-        path: Schema.optional<typeof Schema.String>;
-        key: Schema.optional<typeof Schema.String>;
-        url: Schema.optional<Schema.NullOr<typeof Schema.String>>;
-        contentType: Schema.optional<typeof Schema.String>;
-        mimeType: Schema.optional<typeof Schema.String>;
-        isPrivate: Schema.optional<typeof Schema.Boolean>;
-        metadata: Schema.optional<Schema.NullOr<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>>;
-        createdAt: Schema.optional<typeof Schema.String>;
-        uploadedAt: Schema.optional<typeof Schema.String>;
-    }>>;
-    readonly delete: import("../endpoint.js").Endpoint<"DELETE", "/storage/files/:id", Schema.Struct<{
-        id: typeof Schema.String;
-    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
-        success: typeof Schema.Boolean;
+        visibility: Schema.optional<Schema.Literal<["public", "private"]>>;
+        metadata: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
+    }>, Schema.Struct<{
+        id: Schema.brand<typeof Schema.String, "FileId">;
+        filename: typeof Schema.String;
+        contentType: typeof Schema.String;
+        size: typeof Schema.Number;
+        checksumSha256: typeof Schema.String;
+        etag: typeof Schema.String;
+        visibility: Schema.Literal<["public", "private"]>;
+        folder: Schema.NullOr<typeof Schema.String>;
+        metadata: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+        url: Schema.NullOr<typeof Schema.String>;
+        isDeleted: typeof Schema.Boolean;
+        createdAt: typeof Schema.DateFromString;
+        updatedAt: typeof Schema.DateFromString;
     }>>;
-    readonly listVersions: import("../endpoint.js").Endpoint<"GET", "/storage/files/:id/versions", Schema.Struct<{
-        id: typeof Schema.String;
+    readonly listFileVersions: import("../endpoint.js").Endpoint<"GET", "/storage/files/:fileId/versions", Schema.Struct<{
+        fileId: typeof Schema.String;
     }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
         versions: Schema.Array$<Schema.Struct<{
-            id: typeof Schema.String;
-            fileId: typeof Schema.String;
+            id: Schema.brand<typeof Schema.String, "FileVersionId">;
+            fileId: Schema.brand<typeof Schema.String, "FileId">;
             versionNumber: typeof Schema.Number;
-            sizeBytes: typeof Schema.Number;
-            contentType: Schema.NullOr<typeof Schema.String>;
-            checksumSha256: Schema.NullOr<typeof Schema.String>;
-            createdAt: typeof Schema.String;
+            size: typeof Schema.Number;
+            contentType: typeof Schema.String;
+            checksumSha256: typeof Schema.String;
+            etag: typeof Schema.String;
+            createdAt: typeof Schema.DateFromString;
             createdBy: Schema.NullOr<typeof Schema.String>;
             isCurrent: typeof Schema.Boolean;
         }>>;
     }>>;
-    readonly restoreVersion: import("../endpoint.js").Endpoint<"POST", "/storage/files/:id/versions/:versionId/restore", Schema.Struct<{
-        id: typeof Schema.String;
+    readonly restoreFileVersion: import("../endpoint.js").Endpoint<"POST", "/storage/files/:fileId/versions/:versionId:restore", Schema.Struct<{
+        fileId: typeof Schema.String;
         versionId: typeof Schema.String;
     }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
-        success: Schema.Literal<[true]>;
+        file: Schema.Struct<{
+            id: Schema.brand<typeof Schema.String, "FileId">;
+            filename: typeof Schema.String;
+            contentType: typeof Schema.String;
+            size: typeof Schema.Number;
+            checksumSha256: typeof Schema.String;
+            etag: typeof Schema.String;
+            visibility: Schema.Literal<["public", "private"]>;
+            folder: Schema.NullOr<typeof Schema.String>;
+            metadata: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
+            url: Schema.NullOr<typeof Schema.String>;
+            isDeleted: typeof Schema.Boolean;
+            createdAt: typeof Schema.DateFromString;
+            updatedAt: typeof Schema.DateFromString;
+        }>;
         version: Schema.Struct<{
-            id: typeof Schema.String;
-            fileId: typeof Schema.String;
+            id: Schema.brand<typeof Schema.String, "FileVersionId">;
+            fileId: Schema.brand<typeof Schema.String, "FileId">;
             versionNumber: typeof Schema.Number;
-            sizeBytes: typeof Schema.Number;
-            contentType: Schema.NullOr<typeof Schema.String>;
-            checksumSha256: Schema.NullOr<typeof Schema.String>;
-            createdAt: typeof Schema.String;
+            size: typeof Schema.Number;
+            contentType: typeof Schema.String;
+            checksumSha256: typeof Schema.String;
+            etag: typeof Schema.String;
+            createdAt: typeof Schema.DateFromString;
             createdBy: Schema.NullOr<typeof Schema.String>;
             isCurrent: typeof Schema.Boolean;
         }>;
     }>>;
-    readonly restoreFile: import("../endpoint.js").Endpoint<"POST", "/storage/files/:id/restore", Schema.Struct<{
-        id: typeof Schema.String;
-    }>, Schema.Schema.AnyNoContext | undefined, Schema.Schema.AnyNoContext | undefined, Schema.Struct<{
-        success: Schema.Literal<[true]>;
-        file: Schema.Struct<{
-            id: typeof Schema.String;
-            size: typeof Schema.Number;
-            name: Schema.optional<typeof Schema.String>;
-            filename: Schema.optional<typeof Schema.String>;
-            path: Schema.optional<typeof Schema.String>;
-            key: Schema.optional<typeof Schema.String>;
-            url: Schema.optional<Schema.NullOr<typeof Schema.String>>;
-            contentType: Schema.optional<typeof Schema.String>;
-            mimeType: Schema.optional<typeof Schema.String>;
-            isPrivate: Schema.optional<typeof Schema.Boolean>;
-            metadata: Schema.optional<Schema.NullOr<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>>;
-            createdAt: Schema.optional<typeof Schema.String>;
-            uploadedAt: Schema.optional<typeof Schema.String>;
-        }>;
-    }>>;
 };
 //# sourceMappingURL=storage.d.ts.map

package/dist/endpoints/storage.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/endpoints/storage.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAwB/B,eAAO,MAAM,gBAAgB;IAC5B;;;;;OAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IAmBH;;;;OAIG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiEM,CAAA"}
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/endpoints/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAgC/B,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwInB,CAAA"}

package/dist/endpoints/storage.js

@@ -1,106 +1,143 @@
 /**
- * Storage endpoints — BaaS plane. Paths mirror `@sylphx/sdk/storage.ts`.
+ * Storage endpoints — BaaS plane. Per ADR-100.
+ *
+ * One resource (`uploads`) for upload sessions, one resource (`files`) for
+ * everything else. Verb suffix `:action` on `files` follows Google AIP-136.
+ *
+ * No legacy aliases. No polymorphic POSTs. Mirrors `@sylphx/sdk/storage.ts`.
  */
 import { Schema } from 'effect';
 import { defineEndpoint } from '../endpoint.js';
-import { DeleteFileResult, FileInfo, ListFilesQuery, ListFilesResult, ListFileVersionsResult, RestoreFileResult, RestoreVersionResult, SignedUrlInput, SignedUrlResult, UploadTokenInput, UploadTokenResult, UploadUrlInput, UploadUrlResult, } from '../schemas/storage.js';
-const IdPath = Schema.Struct({ id: Schema.String });
+import { CopyFileRequest, CopyFileResult, File, ListFilesQuery, ListFilesResult, ListFileVersionsResult, RestoreFileResult, RestoreVersionResult, SignedUrlRequest, SignedUrlResult, SoftDeleteFileResult, UploadCompleteRequest, UploadCompleteResult, UploadCreateRequest, UploadCreateResult, UploadPartPresignResult, } from '../schemas/storage.js';
+const FileIdPath = Schema.Struct({ fileId: Schema.String });
+const UploadIdPath = Schema.Struct({ uploadId: Schema.String });
+const UploadPartPath = Schema.Struct({
+    uploadId: Schema.String,
+    partNumber: Schema.NumberFromString,
+});
 const FileVersionPath = Schema.Struct({
-    id: Schema.String,
+    fileId: Schema.String,
     versionId: Schema.String,
 });
 export const storageEndpoints = {
-    /**
-     * Mint an upload token for client-direct uploads. Returns either a
-     * simple `{ uploadUrl, publicUrl }` pair or a Vercel-Blob-style
-     * `{ uploadEndpoint, clientPayload, instructions }` envelope.
-     * This is the SDK's primary upload path (`uploadFile` / `uploadAvatar`).
-     */
-    upload: defineEndpoint({
+    // --------------------------------------------------------------------------
+    // Upload sessions
+    // --------------------------------------------------------------------------
+    createUpload: defineEndpoint({
         method: 'POST',
-        path: '/storage/upload',
-        body: UploadTokenInput,
-        response: UploadTokenResult,
+        path: '/storage/uploads',
+        body: UploadCreateRequest,
+        response: UploadCreateResult,
         plane: 'baas',
-        summary: 'Mint an upload token for client-direct file uploads',
+        summary: 'Create an upload session. Returns a single-part PUT or a multipart plan based on size.',
         tags: ['storage'],
     }),
-    presignedUrl: defineEndpoint({
+    abortUpload: defineEndpoint({
+        method: 'DELETE',
+        path: '/storage/uploads/:uploadId',
+        params: UploadIdPath,
+        response: Schema.Struct({}),
+        plane: 'baas',
+        summary: 'Abort an in-progress upload session and release its parts.',
+        tags: ['storage'],
+    }),
+    presignUploadPart: defineEndpoint({
         method: 'POST',
-        path: '/storage/upload-url',
-        body: UploadUrlInput,
-        response: UploadUrlResult,
+        path: '/storage/uploads/:uploadId/parts/:partNumber',
+        params: UploadPartPath,
+        response: UploadPartPresignResult,
         plane: 'baas',
-        summary: 'Mint a short-lived presigned upload URL',
+        summary: 'Mint a fresh presigned URL for a single multipart part (used to resume long pauses).',
         tags: ['storage'],
     }),
-    /**
-     * Generate a time-limited signed URL for accessing a private file.
-     * Signed URLs avoid exposing permanent credentials and can be scoped
-     * to a specific user via the `userId` field.
-     */
-    signedUrl: defineEndpoint({
+    completeUpload: defineEndpoint({
         method: 'POST',
-        path: '/storage/signed-url',
-        body: SignedUrlInput,
-        response: SignedUrlResult,
+        path: '/storage/uploads/:uploadId:complete',
+        params: UploadIdPath,
+        body: UploadCompleteRequest,
+        response: UploadCompleteResult,
         plane: 'baas',
-        summary: 'Mint a short-lived signed download URL for a private file',
+        summary: 'Finalise a multipart upload by submitting per-part etags.',
         tags: ['storage'],
     }),
-    list: defineEndpoint({
+    // --------------------------------------------------------------------------
+    // Files resource
+    // --------------------------------------------------------------------------
+    listFiles: defineEndpoint({
         method: 'GET',
         path: '/storage/files',
         query: ListFilesQuery,
         response: ListFilesResult,
         plane: 'baas',
-        summary: 'List files stored by the app (cursor-paginated)',
+        summary: 'List files (cursor-paginated).',
         tags: ['storage'],
     }),
-    get: defineEndpoint({
+    getFile: defineEndpoint({
         method: 'GET',
-        path: '/storage/files/:id',
-        params: IdPath,
-        response: FileInfo,
+        path: '/storage/files/:fileId',
+        params: FileIdPath,
+        response: File,
         plane: 'baas',
-        summary: 'Get file metadata by ID',
+        summary: 'Get file metadata.',
         tags: ['storage'],
     }),
-    delete: defineEndpoint({
+    deleteFile: defineEndpoint({
         method: 'DELETE',
-        path: '/storage/files/:id',
-        params: IdPath,
-        response: DeleteFileResult,
+        path: '/storage/files/:fileId',
+        params: FileIdPath,
+        response: SoftDeleteFileResult,
         plane: 'baas',
-        summary: 'Soft-delete a stored file (ADR-089 Phase 5.8)',
+        summary: 'Soft-delete a file. Restorable via `:restore`.',
         tags: ['storage'],
     }),
-    // ADR-089 Phase 5.8 — versioning + soft-delete restore
-    listVersions: defineEndpoint({
-        method: 'GET',
-        path: '/storage/files/:id/versions',
-        params: IdPath,
-        response: ListFileVersionsResult,
+    restoreFile: defineEndpoint({
+        method: 'POST',
+        path: '/storage/files/:fileId:restore',
+        params: FileIdPath,
+        response: RestoreFileResult,
         plane: 'baas',
-        summary: 'List all versions of a file, newest first',
+        summary: 'Restore a soft-deleted file.',
         tags: ['storage'],
     }),
-    restoreVersion: defineEndpoint({
+    signFileUrl: defineEndpoint({
         method: 'POST',
-        path: '/storage/files/:id/versions/:versionId/restore',
-        params: FileVersionPath,
-        response: RestoreVersionResult,
+        path: '/storage/files/:fileId:signedUrl',
+        params: FileIdPath,
+        body: SignedUrlRequest,
+        response: SignedUrlResult,
         plane: 'baas',
-        summary: 'Restore an older version as the current version',
+        summary: 'Mint a short-lived signed download URL for a private file.',
         tags: ['storage'],
     }),
-    restoreFile: defineEndpoint({
+    copyFile: defineEndpoint({
         method: 'POST',
-        path: '/storage/files/:id/restore',
-        params: IdPath,
-        response: RestoreFileResult,
+        path: '/storage/files/:fileId:copy',
+        params: FileIdPath,
+        body: CopyFileRequest,
+        response: CopyFileResult,
+        plane: 'baas',
+        summary: 'Server-side copy (no client bandwidth).',
+        tags: ['storage'],
+    }),
+    // --------------------------------------------------------------------------
+    // Versions
+    // --------------------------------------------------------------------------
+    listFileVersions: defineEndpoint({
+        method: 'GET',
+        path: '/storage/files/:fileId/versions',
+        params: FileIdPath,
+        response: ListFileVersionsResult,
+        plane: 'baas',
+        summary: 'List versions of a file (newest first).',
+        tags: ['storage'],
+    }),
+    restoreFileVersion: defineEndpoint({
+        method: 'POST',
+        path: '/storage/files/:fileId/versions/:versionId:restore',
+        params: FileVersionPath,
+        response: RestoreVersionResult,
         plane: 'baas',
-        summary: 'Restore a soft-deleted file',
+        summary: 'Restore an older version as the current version (append-only history).',
         tags: ['storage'],
     }),
 };