Skip to content

client-recipes.md

Latest commit

 

History

History
276 lines (228 loc) · 28.3 KB

client-recipes.md

File metadata and controls

276 lines (228 loc) · 28.3 KB

Client Recipes

This page maps the public contract surface to concrete client-side usage patterns.

Environment model

The example client snippets assume these environment variables:

  • N1HUB_BASE_URL Base URL of the validator service, for example https://example.n1hub.dev
  • N1HUB_TOKEN Bearer token for the validator HTTP surface

Quick navigator

If you are starting cold and do not yet know which snippet family to open first, inspect ../examples/client/recipe-index.json.

That file is the machine-readable map for this directory. It groups every non-Markdown client artifact by runtime and consumption path, and it also provides task-oriented entrypoints such as:

  • live validator calls for validate, batch, fix, gates, and stats
  • source-level request and response readers
  • raw-schema Ajv validation and structural rejection checks
  • compact-reference and OpenAPI discovery
  • installed-package runtime and TypeScript entrypoints
  • public G16 integrity proof flows

The groups[*].recommended_start field gives the shortest human-safe file to open for each runtime lane. The task_entrypoints[*] section then maps common intents to one recommended file, cross-runtime alternatives, and the supporting docs that explain the surrounding contract.

If you need the navigator itself as a bounded machine-readable contract instead of trusting prose or ad hoc object assumptions, pair ../examples/client/recipe-index.json with ../schemas/client-recipe-index.schema.json, ../examples/client/zod-parse-client-recipe-index.ts, ../examples/client/ajv-validate-client-recipe-index.mjs, ../examples/client/cjs-package-ajv-validate-client-recipe-index.cjs, ../examples/client/esm-package-ajv-validate-client-recipe-index.mjs, or ../examples/client/ts-package-ajv-validate-client-recipe-index.ts.

Fast starts

If you want the quickest path instead of reading the whole directory:

Runtime lanes

If you already know your runtime, the shortest entry files are:

cURL recipes

Ready-to-read examples live under ../examples/client/:

These scripts show the request method, route, auth header, and when applicable the local payload file to send.

Node recipes

Minimal Node fetch-based examples also live under ../examples/client/:

They are intentionally small and avoid framework assumptions while covering all published validator routes.

TypeScript and Zod recipes

Source-level consumer examples also live under ../examples/client/:

These recipes demonstrate how to consume the published projection layer under ../projections/ when you want typed interfaces or Zod parsing in addition to raw JSON Schema, and how to inspect or generate from the strongest published OpenAPI route surface directly when compact summaries are too lossy. Together they cover the published client-recipe navigator as typed contract data, single, batch, and fix validate request families, source-level TypeScript builders plus source-level typed reading of the published request samples, a direct OpenAPI route-summary path, a repo-local OpenAPI code-generation path through openapi-typescript, a typed live-client bridge for all published validator routes backed by the shared route projection and the bounded stats query path, a typed validator envelope-family discovery path backed by the shared envelope-family projection, a typed validator route-behavior discovery path backed by the shared route projection and compact route pack, typed/parsing paths for the published pass, fail, batch, and fix response families, the published gates / stats support responses, and the bounded shared generic, unauthorized, forbidden, conflict, and rate-limit error envelopes. They also now cover repo-relative TypeScript and Zod parsing for the published archive-bundle portability contract.

Raw JSON Schema recipes

If you want direct structural validation against the published schemas, inspect:

These recipes demonstrate how to validate public examples against the raw JSON Schema layer with Ajv, how to validate the client-recipe navigator against its bounded schema contract, how to validate the archive-bundle portability sample against its published export/replay contract, how to consume the same contracts as single-file schema bundles, and how to confirm that intentionally invalid archive, client-recipe navigator, capsule, and validator-envelope fixtures are rejected for the documented structural reasons, without relying on the projection layer or live validator API calls.

Integrity recipes

If you need the public G16 sealing rule instead of only schema shape, inspect:

These recipes demonstrate how to recompute integrity_sha3_512 over the published four-root payload, verify that the positive examples are sealed correctly, and repair the intentional G16 teaching example without depending on private runtime helpers.

Python recipes

If you need a cross-language raw-asset consumption path outside the Node runtime, inspect:

These recipes demonstrate how Python consumers can read the published client-recipe navigator and archive-bundle sample, read compact contract-reference JSON files, read the strongest published OpenAPI surface directly, use the published route pack as one reusable full-route live-client bridge, inspect curated raw capsule assets, prepare validator-envelope request flows for validate, batch, and fix, call the published gates and stats support routes including the bounded stats query path, parse published validator response families plus bounded shared and route-specific error envelopes, and recompute integrity_sha3_512 directly from the published four-root payload, both from a repo checkout and from an extracted packed artifact.

Package recipes

If you want package-style consumption instead of file-relative source imports, also inspect:

These recipes demonstrate the repo-owned package-export layer for CommonJS, ESM, and TypeScript consumers after npm run build:projections or from a locally packed artifact, including installed-package direct consumption of the machine-readable client-recipe navigator, installed-package direct OpenAPI reading plus installed-package OpenAPI type generation through openapi-typescript across CommonJS, ESM, and TypeScript consumer styles, installed-package runtime parsing plus installed-package TypeScript typed construction and typed reading for the published single, batch, and fix validator request families, installed-package CommonJS, ESM, and TypeScript live-client bridges for all published validator routes backed by the shared route projection and the bounded stats query path, installed-package typed discovery of the published validator envelope-family map, installed-package parsing and typing for the published pass, fail, batch, and fix validator response families, the compact reference-pack JSON exports, installed-package parsing of gates and stats support responses, installed-package parsing and typing for the bounded shared generic, unauthorized, forbidden, conflict, rate-limit, and route-specific stats-computation error envelopes, positive raw-schema Ajv consumption, archive-bundle schema validation, client-recipe navigator schema validation and rejection across CommonJS, ESM, and TypeScript package-consumer styles, bundled single-file schema consumption, package-level rejection of intentionally invalid archive, client-recipe navigator, capsule, and validator-envelope fixtures through package subpaths, and package-level recomputation of integrity seals for G16-sensitive flows. If you need the same public JSON artifacts from Python instead of Node imports, use the extracted-artifact path documented in python-consumption.md.

Route mapping

  • curl-validate-single.sh and node-validate-single.mjs Use POST /api/validate
  • curl-validate-batch.sh and node-validate-batch.mjs Use POST /api/validate/batch
  • curl-validate-fix.sh and node-validate-fix.mjs Use POST /api/validate/fix
  • curl-get-gates.sh, node-get-gates.mjs, and python-get-gates.py Use GET /api/validate/gates
  • curl-get-stats.sh, node-get-stats.mjs, and python-get-stats.py Use GET /api/validate/stats, including the optional bounded limit query parameter
  • python-validate-single.py, python-validate-batch.py, and python-validate-fix.py Mirror the three published POST validator routes from a cross-language raw-JSON path
  • python-parse-validate-responses.py, python-parse-error-responses.py, and python-parse-support-responses.py Inspect the published validate, bounded error-envelope, and support response families without requiring live credentials
  • python-live-validator-client.py Bridges the full published validator route family from one reusable Python client backed by the shared route pack and bounded stats query metadata

Why these recipes exist

The JSON request and response examples show contract shape. The client recipes show how a consumer actually sends or reads those payloads across every published validator route. Together they reduce the gap between “the contract is documented” and “an external integrator can use it quickly.”