# `initiate.ts`

## Purpose

Defines the request body and response shape for `POST /uploads/initiate`, the chunked upload bootstrap endpoint. The client declares the file's total size, SHA-256 hash, and optional MIME type up-front; the server returns the `uploadId`, server-chosen `chunkSize`, and `totalChunks` so the client can deterministically slice the file.

## Features

- Client-declared `totalSha256` is the contract the server later verifies on `complete` — mismatch raises `UPLOAD.HASH_MISMATCH` (HTTP 422).
- `mimeType` defaults to `application/octet-stream` so clients uploading binary payloads need not guess.
- `chunkSize` may be overridden by the client; absent, the server uses the configured `defaultChunkSize`.
- 255-char `fileName` cap matches POSIX `NAME_MAX`.

## Usage: Basic

```ts
import { InitiateUploadBodySchema } from "@suaveplan/api-plugin-file-upload/schemas/routes";

const body = InitiateUploadBodySchema.parse(await c.req.json());
```

## Usage: Advanced

```ts
import { InitiateUploadBodySchema } from "@suaveplan/api-plugin-file-upload";
import fc from "fast-check";

fc.assert(
    fc.property(
        fc.record({
            fileName: fc.string({ minLength: 1, maxLength: 255 }),
            totalSize: fc.integer({ min: 1, max: 1024 * 1024 * 1024 }),
            totalSha256: fc.hexaString({ minLength: 64, maxLength: 64 }),
        }),
        (input) => InitiateUploadBodySchema.safeParse(input).success
    ),
    { numRuns: 200 }
);
```

## API Reference

- `InitiateUploadBodySchema` — Zod schema for the request body.
- `InitiateUploadResponseSchema` — Zod schema for the success response (`uploadId`, `chunkSize`, `totalChunks`).
- `InitiateUploadBody` / `InitiateUploadResponse` — `z.infer` aliases.

## Implementation Notes

- The server intentionally trusts the client-declared `totalSha256` only as a verification target — the actual hash is computed server-side from the assembled bytes. A mismatch surfaces as a 422 so clients can re-derive and retry without rebuilding the entire upload state.
- `chunkSize` is server-bounded by `defaultChunkSize` to prevent pathological tiny-chunk attacks; the validator at the service layer caps client-supplied values.