# `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.