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