Initial Commit

packages/api-stack/api/api-plugin-file-upload/src/schemas/routes/status.md

@@ -0,0 +1,60 @@
+# `status.ts`
+
+## Purpose
+
+Defines the path-parameter and response shapes for the remaining chunked-upload routes: `PUT /uploads/{uploadId}/chunks/{chunkIndex}`, `POST /uploads/{uploadId}/complete`, `GET /uploads/{uploadId}`, and `DELETE /uploads/{uploadId}`. The status response is the resume contract: clients call `GET` after a crash and pick up from the next missing chunk.
+
+## Features
+
+- `ChunkParamsSchema` constrains `chunkIndex` to a non-negative integer via regex — invalid values reject at the boundary so the handler never sees malformed paths.
+- `CompleteUploadBodySchema` allows an optional `totalSha256` override for clients that recomputed the hash mid-flight.
+- `UploadStatusResponseSchema` exposes a discriminated `state` literal so consumers can switch on `"in-progress"` vs `"complete"` without ambiguity.
+
+## Usage: Basic
+
+```ts
+import { UploadStatusResponseSchema } from "@suaveplan/api-plugin-file-upload/schemas/routes";
+
+const status = UploadStatusResponseSchema.parse(await response.json());
+const missing: number[] = [];
+for (let i = 0; i < status.totalChunks; i++) {
+    if (!status.receivedChunks.includes(i)) missing.push(i);
+}
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    ChunkParamsSchema,
+    UploadStatusResponseSchema,
+} from "@suaveplan/api-plugin-file-upload";
+
+async function resume(uploadId: string, fetchFn: typeof fetch) {
+    const status = UploadStatusResponseSchema.parse(
+        await (await fetchFn(`/uploads/${uploadId}`)).json()
+    );
+    if (status.state === "complete") return;
+    for (let i = 0; i < status.totalChunks; i++) {
+        if (status.receivedChunks.includes(i)) continue;
+        const params = ChunkParamsSchema.parse({
+            uploadId,
+            chunkIndex: String(i),
+        });
+        await uploadChunk(params, sliceFor(i));
+    }
+}
+```
+
+## API Reference
+
+- `UploadIdParamsSchema` — path parameter `{ uploadId }`.
+- `ChunkParamsSchema` — path parameter `{ uploadId, chunkIndex }`.
+- `CompleteUploadBodySchema` — optional body with `totalSha256` override; defaults to `{}` when omitted.
+- `UploadStatusResponseSchema` — `{ uploadId, totalChunks, receivedChunks, state }`.
+- `AppendChunkResponseSchema` — `{ uploadId, chunkIndex, receivedChunks }` (the count, not the set).
+
+## Implementation Notes
+
+- `chunkIndex` is a string in the params (URL paths are strings) and parsed to a number in the handler — the schema enforces only that the path segment is decimal-digit-only.
+- The status response returns `receivedChunks` as an array, not a set, so it serialises cleanly through JSON; clients reconstruct the set if needed.