# `schemas/schemas` — public Zod request/response surface

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## Purpose

Carries the full public Zod surface used by the route handlers and any
external client (CLI tool, integration test, browser app) that wants to
validate or generate import requests / responses without depending on
the route module itself. Every body, query, and response shape that
crosses the HTTP boundary is declared here so the OpenAPI document and
the runtime validators stay in lockstep.

Keeping these schemas in their own module means consumers can import
them without pulling in the Hono/OpenAPI route builder, which is
important for browser clients and shared validation libraries.

## Features

- `ImportFormatSchema` / `ImportStatusSchema` — Zod enums mirroring the
  cross-module type unions.
- `ColumnMappingSchema` — wire-form of a column mapping (functions
  intentionally omitted; transforms are server-side only).
- `PreviewRequestSchema` / `PreviewResponseSchema` — `POST /preview`.
- `CreateImportJobSchema` — `POST /` body.
- `ImportJobResponseSchema` — every job-shape response.
- `ImportJobListQuerySchema` — `GET /` querystring with `z.coerce`
  for the numeric fields so query strings parse without hand-rolling.

## Usage: Basic Example

```ts
import { CreateImportJobSchema } from "@suaveplan/api-plugin-import";

const result = CreateImportJobSchema.safeParse({
    format: "csv",
    data: "name\nAda",
    mappings: [{ sourceColumn: "name", targetField: "displayName" }],
});
if (!result.success) throw new Error(result.error.message);
```

## Usage: Advanced Example

```ts
import { ImportJobResponseSchema, type ImportJobResponseShape } from "@suaveplan/api-plugin-import";

async function fetchJob(id: string): Promise<ImportJobResponseShape> {
    const res = await fetch(`/imports/${id}`);
    const json = await res.json();
    return ImportJobResponseSchema.parse(json);
}
```

## API Reference

- `ImportFormatSchema`, `type ImportFormatInput`
- `ImportStatusSchema`, `type ImportStatusInput`
- `ColumnMappingSchema`, `type ColumnMappingInput`
- `PreviewRequestSchema`, `type PreviewRequestInput`
- `PreviewResponseSchema`, `type PreviewResponseShape`
- `CreateImportJobSchema`, `type CreateImportJobInput`
- `ImportJobResponseSchema`, `type ImportJobResponseShape`
- `ImportJobListQuerySchema`, `type ImportJobListQueryInput`
- `RowErrorSchema`

## Implementation Notes

- `ColumnMappingSchema` omits the `transform` callback — transforms are
  authored in TypeScript on the server, not over the wire. Wire-form
  mappings are pure renames + required flags.
- `PreviewResponseSchema.sampleRows` uses `z.record(z.string(),
  z.unknown())` so heterogeneous row shapes survive validation.
- `ImportJobListQuerySchema` uses `z.coerce.number()` because Hono
  delivers query parameters as strings — the coerce ensures `?limit=20`
  parses to a number without manual `parseInt`.
- `CreateImportJobSchema.mappings` requires `min(1)` because zero
  mappings is the service-layer `IMPORT.VALIDATION` failure; rejecting
  it at the Zod boundary saves a service round-trip.