@anyformat/sdk 0.1.0

package/README.md

@@ -0,0 +1,55 @@
+# @anyformat/sdk
+
+TypeScript SDK for the AnyFormat API. Mirrors the Python SDK's fluent flow.
+
+```ts
+import { Anyformat, Schema } from "@anyformat/sdk";
+
+const af = new Anyformat({ apiKey: process.env.ANYFORMAT_API_KEY! });
+
+const result = await af
+  .workflow("Invoice")
+  .parse()
+  .extract([
+    Schema.string("vendor", "Vendor name on the invoice."),
+    Schema.float("total", "Grand total amount."),
+    Schema.enum("currency", "Currency of the totals.", [
+      Schema.option("USD", "US Dollar."),
+      Schema.option("EUR", "Euro."),
+    ]),
+  ])
+  .run(file)
+  .wait();
+
+result.field("vendor")?.value; // -> "Acme Corp"
+```
+
+## How it's built
+
+The wire types and the low-level HTTP client are **generated** from the API's
+OpenAPI spec with [Hey API](https://heyapi.dev) — they are not hand-written and
+must not be edited. Everything in `src/sdk/` is generated; the hand-written
+ergonomic layer (`Schema`, `WorkflowBuilder`, `Result`, `Anyformat`) wraps it.
+
+## Regenerating (and the drift guard)
+
+```bash
+npm run gen          # dump the v2 OpenAPI offline + regenerate src/sdk
+npm run gen:check    # regenerate and fail if the committed output drifted
+```
+
+`gen:check` runs in CI and as a pre-commit hook (scoped to changes under
+`anyformat/services/api` and `anyformat/workflow`) so the committed SDK can
+never fall behind the backend. The SDK's own `tsc` then fails to compile if a
+backend model change alters a type the hand-written layer relies on — drift is
+caught as a type error, not just a diff.
+
+## Scripts
+
+| script | what |
+| --- | --- |
+| `npm run gen` | dump spec + regenerate `src/sdk` |
+| `npm run gen:check` | regenerate + assert no drift |
+| `npm run build` | bundle to `dist/` (ESM + CJS + types) via tsup |
+| `npm run typecheck` | `tsc --noEmit` |
+| `npm test` | vitest |