first commit

docs/api-stack/api/api-plugin-import/src/schemas/schemas.md

@@ -0,0 +1,81 @@
+# `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.