first commit

docs/api-stack/api/api-plugin-file-upload/src/schemas/routes/single-shot.md

@@ -0,0 +1,44 @@
+# `single-shot.ts`
+
+## Purpose
+
+Defines the typed JSON response returned by both `POST /uploads` (single-shot) and `POST /uploads/{uploadId}/complete` (chunked finalisation). Centralising the response shape keeps the OpenAPI doc in lockstep across the two surfaces — clients written against `POST /uploads` work unchanged against the chunked `complete` route.
+
+## Features
+
+- 64-char SHA-256 length constraint catches obvious truncation bugs at the schema boundary.
+- Non-negative `size` so a zero-byte upload still validates cleanly.
+- `mimeType` is required because the validator always populates it (declared or sniffed).
+
+## Usage: Basic
+
+```ts
+import { SingleShotResponseSchema } from "@suaveplan/api-plugin-file-upload/schemas/routes";
+
+const parsed = SingleShotResponseSchema.parse(await response.json());
+console.log(parsed.uploadId, parsed.sha256);
+```
+
+## Usage: Advanced
+
+```ts
+import {
+    SingleShotResponseSchema,
+    type SingleShotResponse,
+} from "@suaveplan/api-plugin-file-upload";
+
+function describeUpload(rec: SingleShotResponse): string {
+    return `Uploaded ${rec.fileName} (${rec.size} bytes, sha256=${rec.sha256.slice(0, 8)}…)`;
+}
+const ok: SingleShotResponse = SingleShotResponseSchema.parse(json);
+```
+
+## API Reference
+
+- `SingleShotResponseSchema` — Zod object schema.
+- `SingleShotResponse` — `z.infer<typeof SingleShotResponseSchema>` type alias.
+
+## Implementation Notes
+
+- Reusing the same shape across two routes is a deliberate ergonomic choice: callers that switch from a small single-shot file to a large chunked upload do not have to adjust their response parsing.
+- The schema omits `storageKey` and `principalId` from the response so internal storage layout and ownership metadata never leak through the wire surface.