@printhive/api 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.0
+
+- Add `printJobs.create` for multipart project preparation and existing JSON artifact creation.
+- Add creation receipt reads and `waitUntilCreated`, including typed stopped-request errors.
+- Return created receipts even when their referenced job has been deleted.
+- Preserve idempotency keys across retries and include public creation routes in the generated OpenAPI contract.
+
 ## 0.1.0
 
 Initial partner-production client for server-side integrations such as Printie. Version 0.1.0 covers uploads and model reads only, including source inspection polling and source-file listing. Preparation methods (#4764) and order methods (#4631) will come in later versions.

package/README.md

@@ -1,11 +1,37 @@
 # @printhive/api
 
-A TypeScript client for Print Hive's partner-production REST API. Version 0.1.0 has zero runtime dependencies and uses global `fetch`. It supports Node 20+, Bun, and Deno with npm compatibility. File paths require the runtime's Node filesystem compatibility. ESM, CommonJS, and TypeScript declarations ship together.
+A TypeScript client for Print Hive's REST API. Version 0.2.0 has zero runtime dependencies and uses global `fetch`. It supports Node 20+, Bun, and Deno with npm compatibility. File paths require the runtime's Node filesystem compatibility. ESM, CommonJS, and TypeScript declarations ship together.
 
-Version 0.1.0 covers uploads and model reads only, including source inspection polling and source-file listing. Preparation methods (#4764) and order methods (#4631) will come in later versions.
+Version 0.2.0 adds public single-plate print creation and creation-request polling alongside customer printer reads, partner source uploads, and model reads.
 
 Partner API keys belong on your server. Never bundle a key into a browser, mobile app, or other distributed client. Printie's browser calls Printie's backend; that backend calls Print Hive.
 
+## Create a print job
+
+Use an API key with `control` to create and `read` to poll. See [ADR 0071](../../docs/adr/0071-public-print-job-requests.md) for target selection and filament semantics.
+
+```ts
+import { PrintHive } from "@printhive/api";
+
+const hive = new PrintHive({ apiKey: process.env.PRINTHIVE_API_KEY! });
+const request = await hive.printJobs.create({
+  file: "/srv/designs/project.3mf",
+  filename: "project.3mf",
+  plate: 2,
+  filaments: [{ sourceSlot: 0, material: "PETG", color: "#FF0000" }],
+  printer_id: "00000000-0000-4000-8000-000000000001",
+  idempotencyKey: "storefront:print-1234",
+});
+const created = await hive.printJobs.waitUntilCreated(request.requestId);
+console.log(created.job);
+```
+
+`printJobs.create` sends multipart to `/v1/print-jobs/create` for a file path or `Uint8Array` plus `filename`. `plate` and typed `filaments` are required; `targetSlot` is optional. Other inputs include `printer_id`, `name`, `externalId`, `release`, `on_filament_mismatch`, and existing `print_options`. This method reads file paths into memory, copies byte inputs, and can retry the multipart body safely. It returns the server's `202` request fields plus `idempotencyKey`. Persist your own key before calling when retries must survive process restarts. Changed metadata or bytes with the same key conflict.
+
+For an existing artifact, `printJobs.create({ name, model_file_id, ... })` sends JSON and returns the existing `201` response with `job` and eligibility fields plus `idempotencyKey`. The client generates an idempotency key once per call if omitted.
+
+`printJobs.getCreateRequest(requestId)` reads the current receipt. `waitUntilCreated(requestId, { intervalMs?, timeoutMs?, signal? })` polls while `preparing`, defaults to a 120-second total deadline, and returns when `created`, including a retained receipt with `job: null` after the job was deleted. `PrintJobCreateStoppedError.request` exposes a `held`, `failed`, or `cancelled` receipt, including its required actions or failure reasons. It does not authorize a held request automatically. Use the HTTP release/cancel operations described in the [integration reference](../../docs/integrations/printie/planned-production.md) when needed.
+
 ## Upload a Printie design
 
 Install `@printhive/api` after its first npm release. Before release, build and pack this workspace for local installation.
@@ -63,9 +89,9 @@ Only 429, 503, and network failures retry. GET requests are idempotent. Upload r
 
 ## Coverage and contract maintenance
 
-Version 0.1.0 covers only uploads, source reads and polling, external-id model lookup, and source-file listing under `/v1/partner-production/`. It offers no generic request method for other routes.
+Version 0.2.0 covers creation and request polling under `/v1/print-jobs/create`, customer printer list and detail reads at `/v1/printers` and `/v1/printers/{id}`, plus uploads, source reads and polling, external-id model lookup, and source-file listing under `/v1/partner-production/`. It offers no generic request method for other routes.
 
-`apps/api/scripts/export-openapi.ts` builds a schema-only Fastify app from the real partner route plugin, without listening, worker startup, database calls, or queue startup. It uses stub environment values. This intentionally exports authenticated partner routes directly. The Swagger UI's public-operation filter would remove them, and generic error enrichment would lose partner restriction details.
+`apps/api/scripts/export-openapi.ts` builds a schema-only Fastify app from the real printer, file-compatibility, print-job, and partner route plugins, without listening, worker startup, database calls, or queue startup. It uses stub environment values. This intentionally exports authenticated partner routes directly. The Swagger UI's public-operation filter would remove them, and generic error enrichment would lose partner restriction details.
 
 `bun run generate` filters that export by the prefix list in `scripts/contracts.mjs`, commits `openapi.json`, and generates TypeScript types and standalone response validators. AJV compiles the validators during development; the build bundles their small runtime helpers. `openapi-typescript` is a development dependency because it generates OpenAPI 3 union types without adding runtime dependencies. `bun run check:drift` reexports and compares the snapshot. Types and standalone validators regenerate in ignored `.temp` build output on every check. `bun run test` builds the distribution and runs its HTTP tests against `dist`, including in the release workflow. `api-client-check.yml` also runs when API or client sources change, so drift checks do not depend on Turbo selecting the client as affected.
 
@@ -75,6 +101,34 @@ Run `bun run build`, `bun run check-types`, and `bun run test` in this package.
 
 ## Release
 
-The manual `api-client-publish.yml` workflow builds, verifies, checks npm version availability, and publishes with `npm publish --access public` using `NPM_TOKEN`. It never runs on push. The `@printhive` npm organization must exist before the first release. Creating it and dispatching a release are maintainer actions.
+The manual `api-client-publish.yml` workflow builds, verifies, checks npm version availability, and publishes with `npm publish --access public`. It never runs on push. npm trusted publishing authorizes the release: npm trusts that workflow file in `PrintHive/hive`, so the workflow needs no stored npm token. Package maintainers can still publish by hand with their own npm credentials. To bump the version, change `version` in `package.json`, merge, and dispatch the workflow. Dispatching a release is a maintainer action.
+
+Provenance is disabled because the source repository is private. It can be enabled later through a matching public source mirror and its publishing workflow. The package's `repository` field names `PrintHive/hive`, because trusted publishing from GitHub requires `repository.url` to match the publishing repository. Outside readers see only the URL.
+
+### Read organization printers
+
+Use a customer API key with the `read` tier or higher. Keys with any
+`production:*` scope cannot call these routes, including mixed-scope keys.
+
+```ts
+const customer = new PrintHive({
+  apiKey: process.env.PRINT_HIVE_CUSTOMER_API_KEY!,
+});
+const page = await customer.printers.list({ limit: 50 });
+if (page.printers[0]) {
+  const printer = await customer.printers.get(page.printers[0].id);
+}
+```
 
-Provenance is intentionally disabled because the source repository is private. It can be enabled later through a matching public source mirror and its publishing workflow. The package omits a repository field pointing at the private monorepo.
+List returns `{ printers, nextCursor }`. Pass `nextCursor` as `cursor` until
+it is null. Detail returns 404 for missing or foreign-organization printers.
+Each printer includes model, connection, status, and `readyMarked`, the stored
+readiness flag. It does not guarantee an empty bed or authorize dispatch.
+`loadedFilament` uses Smart Queue's material source. Each slot includes
+`address: { ams_id, slot_id }`, material, color, and a `state` of `loaded`,
+`empty`, or `unknown`. AMS IDs and tray IDs are zero based; external spools
+use AMS ID 255 and slot ID 254 or 255. Reads return stored observations and
+never contact a printer.
+
+`readiness.ready` reports the stored ready flag. `readiness.bedClear` reports
+the flag only when its source is `bed_occupancy_verified`; otherwise it is null.