@sylphx/contract 0.3.0 → 0.4.0

package/dist/schemas/storage.js

@@ -1,174 +1,193 @@
 /**
- * Storage — BaaS plane file upload / download. Uses presigned URLs per AWS
- * S3 convention. Mirrors `@sylphx/sdk/storage.ts`.
+ * Storage — BaaS plane object storage. Per ADR-100.
  *
- * Shape policy (ADR-084 Wave 2d): schemas here are the UNION superset of
- * all production SDK / OpenAPI-generated wire shapes. Any field that is not
- * universally present on the wire is `optional`, so contract consumers
- * never have to narrow to parse a legitimate server response. When the
- * server response narrows in future, tighten the optional in a dedicated
- * wave — never break existing callers by removing a field.
+ * Wire is one resource (`uploads`) plus the existing `files` resource. No
+ * polymorphic POSTs, no vendor-namespaced wire envelopes, no historical
+ * field aliases. Every endpoint has exactly one request and one response
+ * schema.
+ *
+ * Storage backends (B2, R2) are abstracted by `apps/storage-gateway`. The
+ * BaaS handler returns presigned URLs against `storage.sylphx.com`; the
+ * client uploads bytes there directly. Mid-flow tenant subdomain hops are
+ * forbidden (ADR-083.1).
  */
 import { Schema } from 'effect';
+// ============================================================================
+// Branded identifiers
+// ============================================================================
 export const FileId = Schema.String.pipe(Schema.brand('FileId'));
+export const UploadId = Schema.String.pipe(Schema.brand('UploadId'));
+export const FileVersionId = Schema.String.pipe(Schema.brand('FileVersionId'));
+// ============================================================================
+// Enumerations
+// ============================================================================
+export const FileVisibility = Schema.Literal('public', 'private');
+export const SignedUrlDisposition = Schema.Literal('attachment', 'inline');
+/** Method discriminator on the upload-create response. */
+export const UploadMethod = Schema.Literal('PUT', 'MULTIPART');
+// ============================================================================
+// Core types
+// ============================================================================
 /**
- * File metadata superset — reconciles three historical shapes:
- *
- * - SDK `FileInfo` interface: `{ id, url, name, size, contentType,
- *   isPrivate, createdAt }`
- * - Generated OpenAPI `FileInfo` / `GetFileResponse`: `{ id, filename,
- *   path, url, mimeType, size, metadata, createdAt }`
- * - Previous contract shape: `{ id, key, size, contentType, url?,
- *   uploadedAt }`
- *
- * Every historical field is preserved as optional so older and newer
- * clients can both parse server responses. `id` and `size` are the only
- * guaranteed-present fields across all three shapes.
+ * Canonical file metadata. Single shape — no aliases, no nullable hacks
+ * for legacy callers. ADR-100 §2.6.
  */
-export const FileInfo = Schema.Struct({
-    id: Schema.String,
+export const File = Schema.Struct({
+    id: FileId,
+    filename: Schema.String,
+    contentType: Schema.String,
     size: Schema.Number,
-    /** SDK-native filename (preferred). Alias of `filename` on newer servers. */
-    name: Schema.optional(Schema.String),
-    /** OpenAPI-native filename. Alias of `name` on older servers. */
-    filename: Schema.optional(Schema.String),
-    /** Folder path or storage key. */
-    path: Schema.optional(Schema.String),
-    /** Legacy storage object key (contract v1). */
-    key: Schema.optional(Schema.String),
-    /** Public URL — null for private files, absent on some delete responses. */
-    url: Schema.optional(Schema.NullOr(Schema.String)),
-    /** SDK-native MIME type. */
-    contentType: Schema.optional(Schema.String),
-    /** OpenAPI-native MIME type (alias of `contentType`). */
-    mimeType: Schema.optional(Schema.String),
-    /** Private/public visibility flag. Absent => treat as public. */
-    isPrivate: Schema.optional(Schema.Boolean),
-    /** Arbitrary caller-attached metadata. */
-    metadata: Schema.optional(Schema.NullOr(Schema.Record({ key: Schema.String, value: Schema.Unknown }))),
-    /** SDK-native creation timestamp (ISO string). */
-    createdAt: Schema.optional(Schema.String),
-    /** Legacy contract v1 upload timestamp (alias of createdAt). */
-    uploadedAt: Schema.optional(Schema.String),
+    checksumSha256: Schema.String,
+    etag: Schema.String,
+    visibility: FileVisibility,
+    folder: Schema.NullOr(Schema.String),
+    metadata: Schema.Record({ key: Schema.String, value: Schema.Unknown }),
+    /** Public URL when `visibility === 'public'`; `null` otherwise. Use `:signedUrl` for private files. */
+    url: Schema.NullOr(Schema.String),
+    isDeleted: Schema.Boolean,
+    createdAt: Schema.DateFromString,
+    updatedAt: Schema.DateFromString,
+});
+export const FileVersion = Schema.Struct({
+    id: FileVersionId,
+    fileId: FileId,
+    versionNumber: Schema.Number,
+    size: Schema.Number,
+    contentType: Schema.String,
+    checksumSha256: Schema.String,
+    etag: Schema.String,
+    createdAt: Schema.DateFromString,
+    createdBy: Schema.NullOr(Schema.String),
+    isCurrent: Schema.Boolean,
+});
+// ============================================================================
+// Upload session — POST /v1/storage/uploads
+// ============================================================================
+export const UploadCreateRequest = Schema.Struct({
+    filename: Schema.String.pipe(Schema.minLength(1)),
+    contentType: Schema.String.pipe(Schema.minLength(1)),
+    size: Schema.Number.pipe(Schema.greaterThanOrEqualTo(0)),
+    folder: Schema.optional(Schema.String),
+    visibility: Schema.optional(FileVisibility),
+    metadata: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+    /** Pre-computed SHA-256 (hex); verified server-side on `:complete` (multipart) or after PUT (single). */
+    checksumSha256: Schema.optional(Schema.String),
+    /** S3-style precondition; if `'*'`, fail when a file already exists at (folder, filename). */
+    ifNoneMatch: Schema.optional(Schema.Literal('*')),
+});
+export const UploadPart = Schema.Struct({
+    partNumber: Schema.Number.pipe(Schema.greaterThanOrEqualTo(1)),
+    url: Schema.String,
+    expiresAt: Schema.DateFromString,
 });
 /**
- * Input for the richer `/storage/upload` token flow used by the SDK for
- * client-direct uploads (Vercel Blob pattern). Server mints an upload
- * endpoint + client payload, and the SDK performs the actual PUT against
- * storage. Superset of `UploadUrlInput`.
+ * Single-part response — the request body fits in one PUT. Client uploads
+ * the whole blob to `url` with the supplied `headers`, captures the `ETag`
+ * response header, then calls `:complete` with `parts: [{partNumber: 1,
+ * etag}]` to finalise. The `:complete` step is non-optional even for
+ * single-part uploads because it is what writes the file row to the
+ * database and consumes quota — without it the storage object is
+ * orphaned and reclaimed by the multipart-aborts sweeper after
+ * `expiresAt`.
  */
-export const UploadTokenInput = Schema.Struct({
-    filename: Schema.String,
-    contentType: Schema.optional(Schema.String),
-    size: Schema.optional(Schema.Number),
-    /** Folder path for organizing the file. */
-    path: Schema.optional(Schema.String),
-    /** `file` | `avatar` — avatars apply user-scoped policy. */
-    type: Schema.optional(Schema.Literal('file', 'avatar')),
-    /** User ID (required for `type: 'avatar'`). */
-    userId: Schema.optional(Schema.String),
-    /** Arbitrary caller-attached metadata persisted alongside the blob. */
-    metadata: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
+export const UploadCreateSinglePartResult = Schema.Struct({
+    method: Schema.Literal('PUT'),
+    uploadId: UploadId,
+    fileId: FileId,
+    url: Schema.String,
+    headers: Schema.Record({ key: Schema.String, value: Schema.String }),
+    expiresAt: Schema.DateFromString,
 });
 /**
- * Upload token response. Supports both the simple `{ uploadUrl, publicUrl,
- * fileId, expiresAt }` shape and the richer Vercel-Blob-style
- * `{ uploadEndpoint, clientPayload, instructions, ... }` shape.
+ * Multipart response — client PUTs each part to its presigned URL, then
+ * calls `POST /uploads/{uploadId}:complete` with the per-part etags.
  */
-export const UploadTokenResult = Schema.Struct({
-    // Simple flow
-    uploadUrl: Schema.optional(Schema.String),
-    publicUrl: Schema.optional(Schema.String),
-    fileId: Schema.optional(Schema.String),
-    expiresAt: Schema.optional(Schema.String),
-    // Presigned S3 flow returned by the Effect-native upload handler
-    presignedUrl: Schema.optional(Schema.String),
-    storageKey: Schema.optional(Schema.String),
-    tokenPayload: Schema.optional(Schema.String),
-    url: Schema.optional(Schema.String),
-    // Vercel Blob client-upload flow
-    uploadEndpoint: Schema.optional(Schema.String),
-    clientPayload: Schema.optional(Schema.String),
-    maxSize: Schema.optional(Schema.Number),
-    maxMultipartSize: Schema.optional(Schema.Number),
-    multipartThreshold: Schema.optional(Schema.Number),
-    allowedContentTypes: Schema.optional(Schema.Array(Schema.String)),
-    instructions: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
-});
-export const UploadUrlInput = Schema.Struct({
-    filename: Schema.String,
-    contentType: Schema.String,
-    size: Schema.optional(Schema.Number),
+export const UploadCreateMultipartResult = Schema.Struct({
+    method: Schema.Literal('MULTIPART'),
+    uploadId: UploadId,
+    fileId: FileId,
+    partSize: Schema.Number,
+    partCount: Schema.Number,
+    parts: Schema.Array(UploadPart),
+    expiresAt: Schema.DateFromString,
+});
+/**
+ * Discriminated union on `method`. SDK narrows via the literal; downstream
+ * code never has to inspect optional fields.
+ */
+export const UploadCreateResult = Schema.Union(UploadCreateSinglePartResult, UploadCreateMultipartResult);
+// ============================================================================
+// Multipart support
+// ============================================================================
+/** Refresh a single part presigned URL — used when an upload pauses past `expiresAt`. */
+export const UploadPartPresignResult = Schema.Struct({
+    url: Schema.String,
+    expiresAt: Schema.DateFromString,
+});
+export const UploadCompletePart = Schema.Struct({
+    partNumber: Schema.Number.pipe(Schema.greaterThanOrEqualTo(1)),
+    etag: Schema.String.pipe(Schema.minLength(1)),
 });
-export const UploadUrlResult = Schema.Struct({
-    uploadUrl: Schema.String,
-    fileId: Schema.String,
-    expiresAt: Schema.String,
+export const UploadCompleteRequest = Schema.Struct({
+    parts: Schema.Array(UploadCompletePart),
+});
+export const UploadCompleteResult = Schema.Struct({
+    fileId: FileId,
+    url: Schema.NullOr(Schema.String),
+    size: Schema.Number,
+    etag: Schema.String,
+    checksumSha256: Schema.String,
 });
+// ============================================================================
+// Files resource
+// ============================================================================
 export const ListFilesQuery = Schema.Struct({
-    prefix: Schema.optional(Schema.String),
-    limit: Schema.optional(Schema.String),
+    folder: Schema.optional(Schema.String),
     cursor: Schema.optional(Schema.String),
+    /** Page size; clamped server-side to [1, 100]; default 25. */
+    limit: Schema.optional(Schema.Number),
+    includeDeleted: Schema.optional(Schema.Boolean),
 });
 export const ListFilesResult = Schema.Struct({
-    files: Schema.Array(FileInfo),
+    files: Schema.Array(File),
     nextCursor: Schema.NullOr(Schema.String),
-    /** True if there are more files beyond this page. */
-    hasMore: Schema.optional(Schema.Boolean),
 });
-export const DeleteFileResult = Schema.Struct({ success: Schema.Boolean });
-/**
- * Signed download URL input. Returns a short-lived URL for private files
- * without exposing permanent credentials.
- */
-export const SignedUrlInput = Schema.Struct({
-    fileId: Schema.String,
-    /** Seconds until the URL expires (default: 3600, max: 604800 = 7 days). */
-    expiresIn: Schema.optional(Schema.Number),
-    /** `attachment` forces download, `inline` displays in browser. */
-    disposition: Schema.optional(Schema.Literal('attachment', 'inline')),
-    /** Restrict URL access to a specific user. */
+export const SoftDeleteFileResult = Schema.Struct({
+    id: FileId,
+    isDeleted: Schema.Literal(true),
+});
+export const RestoreFileResult = File;
+// ============================================================================
+// Signed URLs
+// ============================================================================
+export const SignedUrlRequest = Schema.Struct({
+    expiresIn: Schema.optional(Schema.Number.pipe(Schema.greaterThanOrEqualTo(1))),
+    disposition: Schema.optional(SignedUrlDisposition),
+    /** Restrict the signed URL to a specific authenticated user (claim baked into the signature). */
     userId: Schema.optional(Schema.String),
 });
 export const SignedUrlResult = Schema.Struct({
     url: Schema.String,
-    expiresAt: Schema.String,
-    file: Schema.Struct({
-        id: Schema.String,
-        filename: Schema.String,
-        mimeType: Schema.String,
-        sizeBytes: Schema.Number,
-        isPrivate: Schema.Boolean,
-    }),
+    expiresAt: Schema.DateFromString,
+    file: File,
 });
 // ============================================================================
-// ADR-089 Phase 5.8 — Versioning
+// Copy
 // ============================================================================
-/**
- * A single version of a file. Append-only per-file history — every
- * upload creates one row with a monotonic `versionNumber`. Restore
- * creates a NEW version row pointing at the old object (never mutates
- * history).
- */
-export const StorageFileVersion = Schema.Struct({
-    id: Schema.String,
-    fileId: Schema.String,
-    versionNumber: Schema.Number,
-    sizeBytes: Schema.Number,
-    contentType: Schema.NullOr(Schema.String),
-    checksumSha256: Schema.NullOr(Schema.String),
-    createdAt: Schema.String,
-    createdBy: Schema.NullOr(Schema.String),
-    isCurrent: Schema.Boolean,
+export const CopyFileRequest = Schema.Struct({
+    folder: Schema.optional(Schema.String),
+    filename: Schema.optional(Schema.String),
+    visibility: Schema.optional(FileVisibility),
+    metadata: Schema.optional(Schema.Record({ key: Schema.String, value: Schema.Unknown })),
 });
+export const CopyFileResult = File;
+// ============================================================================
+// Versions
+// ============================================================================
 export const ListFileVersionsResult = Schema.Struct({
-    versions: Schema.Array(StorageFileVersion),
+    versions: Schema.Array(FileVersion),
 });
 export const RestoreVersionResult = Schema.Struct({
-    success: Schema.Literal(true),
-    version: StorageFileVersion,
-});
-export const RestoreFileResult = Schema.Struct({
-    success: Schema.Literal(true),
-    file: FileInfo,
+    file: File,
+    version: FileVersion,
 });

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sylphx/contract",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Sylphx Platform contract — Effect Schema SSOT for every API endpoint (ADR-084).",
 	"type": "module",
 	"sideEffects": false,