@printhive/api 0.1.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.3.2
+
+- Add `printJobs.get` for live job polling after creation, including the API's waiting-reason snapshot.
+
+## 0.3.1
+
+- Add `cause` to generated filament waiting reasons and export `FilamentWaitingReason`. Reasons include only unmet source slots at creation and claim recheck.
+
+## 0.3.0
+
+- Add partner catalog upsert, filtered list and read methods; `preparation_disabled` is not retried as a transient 503.
+- Generate preparation contracts and validators from the current API routes.
+- Add typed preparation creation, reads, total-deadline polling and signed-download metadata.
+- Preserve idempotency keys, immutable retry bodies and typed target refusal reasons.
+- Migrate the Printie simulator from its local preparation wrapper to the SDK.
+
+## 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,43 @@
 # @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.
+
+Preparation support in this source tree is unreleased. See the [changelog](CHANGELOG.md) for released capabilities and the [release procedure](#release) for publishing. Order methods (#4631) remain outside this client.
 
 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.
+
+`printJobs.get(jobId, signal?)` reads `GET /v1/print-jobs/{id}` and returns the inner job snapshot. It requires a positive safe-integer ID. After a create receipt reaches `created` with a non-null job, read that job separately to observe its current status and `print_options.filament_waiting_reasons`. A created job may still wait for materials or printer readiness. Keep polling the live job rather than treating its creation receipt as a current material assessment. A deleted or inaccessible job returns the API's error; the retained create receipt does not recreate it.
+
+The sample and simulator upgrade audit is [SDK upgrade from npm 0.2.0](../../tools/printie-simulator/SDK-UPGRADE.md). The local 0.3.2 build includes the live job read and the merged #4945 waiting-reason types. It is not an npm release. Reasons list only unmet filaments; the optional `cause` remains advisory because a material-type mismatch can still report `color_distance`.
+
 ## Upload a Printie design
 
 Install `@printhive/api` after its first npm release. Before release, build and pack this workspace for local installation.
@@ -53,19 +85,67 @@ for await (const source of hive.models.listSourceFiles(model.modelId)) {
 }
 ```
 
+## Prepare selected plates
+
+Preparation requires `production:upload` for creation and `production:read` for reads and downloads, plus the organization's preparation feature flag.
+
+```ts
+const preparation = await hive.preparations.create({
+  idempotencyKey: "printie:order-1234",
+  items: [
+    {
+      sourceVersionId: source.sourceVersionId,
+      plates: [2],
+      quantity: 3,
+      materialMappings: [{ sourceSlot: 1, material: "PETG", color: "#1F6FEB" }],
+      target: { printerId: "<qualified printer UUID>" },
+    },
+  ],
+});
+const outcome = await hive.preparations.waitUntilSettled(
+  preparation.preparationId,
+  {
+    timeoutMs: 120_000,
+    intervalMs: 1000,
+  }
+);
+for (const item of outcome.items) {
+  for (const plate of item.preparedPlates) {
+    if (plate.status === "ready") {
+      const info = await hive.preparations.downloadInfo(
+        outcome.preparationId,
+        plate.plateId
+      );
+      // info contains url, expiresAt, filename, bytes and sha256.
+      // Fetch the signed URL without sending the Hive API key.
+    }
+  }
+}
+```
+
+Creation accepts at most 20 items. Generated request validation rejects larger arrays locally with `TypeError` before sending HTTP. The API continues to return `422 request_too_large` with limit metadata for oversized raw HTTP requests.
+
+Each item names either `sourceVersionId` or `externalId`. Creation returns the preparation plus the supplied or generated `idempotencyKey`, just like upload. Persist a caller-supplied key before sending when recovery must survive process restarts. A replay returns the original preparation identity. Request JSON is snapshotted before sending and stays unchanged across retries.
+
+`preparations.get(id, signal?)` returns the full preparation. `waitUntilSettled` resolves on `ready`, `held`, or `failed`. Holds and failures remain in the returned items and plates. Its total deadline aborts active reads, retry delays, and poll delays. A timeout leaves the creation outcome intact; resume reads using the preparation ID instead of creating replacement work. `downloadInfo(id, plateId, signal?)` retains all signed-download metadata without fetching the artifact.
+
+`materialMappings[].sourceSlot` is one-based. Ambiguous palettes require explicit source-version or SHA-bound bindings; color order alone cannot establish source slots. Pin `sourceVersionId` after validating a binding. `target.printerId` names the exact qualified target. Preparation creates no print job and never authorizes printer motion.
+
+Public preparation types, including `PartnerPreparationItemInput`, `PartnerMaterialMapping`, `PartnerPreparedPlate`, `PartnerPreparationDownload`, and `PartnerPreparationTargetReason`, derive from the current API export.
+
 ## Handle failures and retries
 
-`PrintHiveApiError` exposes HTTP `status`, the response's `error` as `code`, optional `limit` with `name`, `max`, and `observed`, `retryAfterMs`, and `requestId`. Its optional `body` exposes the validated error envelope, preserving additional fields as JSON values for callers to narrow. Invalid envelopes leave `body` undefined. Error messages omit response bodies and credentials. `PrintHiveNetworkError.reason` distinguishes `network`, `timeout`, and `aborted` failures.
+`PrintHiveApiError` exposes HTTP `status`, the response's `error` as `code`, optional `limit` with `name`, `max`, and `observed`, `retryAfterMs`, and `requestId`. For `target_not_qualified`, `reasons` exposes validated, typed printer qualification reasons. Its optional `body` exposes the validated error envelope, preserving additional fields as JSON values for callers to narrow. Invalid envelopes leave `body` undefined. Error messages omit response bodies and credentials. `PrintHiveNetworkError.reason` distinguishes `network`, `timeout`, and `aborted` failures.
 
 The API can answer `411 content_length_required`, `413 upload_too_large`, `429 upload_capacity_reached`, `409 external_id_conflict`, or `409 idempotency_conflict`. Inspection failures resolve through the source's `failed` status and include their own error and optional restriction limit.
 
-Only 429, 503, and network failures retry. GET requests are idempotent. Upload retries retain their idempotency key and require replayable bytes or a path. One-shot streams never retry. Timeouts and caller aborts never retry. Retries use exponential backoff with jitter and wait at least `Retry-After`, supporting both seconds and HTTP dates. If `Retry-After` exceeds 60 seconds, the client throws the API error with `retryAfterMs` so the caller can schedule the retry. It never retries before that delay. `maxRetries: 0` disables retries. Request timeouts apply per attempt; polling also has a total deadline.
+Only 429, 503, and network failures retry. Permanent `preparation_disabled` never retries, including HTTP 503. GET requests are idempotent. Preparation JSON and upload retries retain their idempotency key and require replayable bytes or a path. One-shot streams never retry. Timeouts and caller aborts never retry. Retries use exponential backoff with jitter and wait at least `Retry-After`, supporting both seconds and HTTP dates. If `Retry-After` exceeds 60 seconds, the client throws the API error with `retryAfterMs` so the caller can schedule the retry. It never retries before that delay. `maxRetries: 0` disables retries. Request timeouts apply per attempt; polling also has a total deadline.
 
 ## 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.
+The current source covers creation and request polling under `/v1/print-jobs/create`, customer printer list and detail reads at `/v1/printers` and `/v1/printers/{id}`, plus preparation creation, reads, polling and download metadata, 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 +155,71 @@ 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);
+}
+```
+
+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.
+
+## Sync your filament catalog
+
+Use a Control API key to sync each partner record. Repeating an external id
+updates the same organization-owned material, including concurrent retries.
+The external id namespace belongs to the organization, so coordinate ids across
+integrations. Reads require Read scope. Hive trims surrounding whitespace from `externalId`
+and `sku` on writes and list filters; neither field can be blank.
+
+```ts
+const filament = await hive.filamentCatalog.upsert({
+  externalId: "printie-pla-blue",
+  brand: "Printie",
+  material: "PLA",
+  colorName: "Blue",
+  colorHex: "#0000FF",
+  sku: "PLA-BLUE",
+  replacementFilamentId: null,
+});
+console.log(filament.id, filament.sku);
+const page = await hive.filamentCatalog.list({ sku: "PLA-BLUE", limit: 100 });
+const saved = await hive.filamentCatalog.get(filament.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.
+`POST /v1/filament-catalog` accepts the fields above and returns 200 with the
+material row. `hex` is an alias for `colorHex`; both must agree when supplied.
+`replacementFilamentId` is retained as partner metadata, not resolved as a Hive id.
+`GET /v1/filament-catalog` filters by exact `externalId` and `sku`, with `limit`
+(1–200, default 100) and `offset` (default 0). Results are ordered by Hive id.
+It returns `{ materials, total }`. `GET /v1/filament-catalog/:id` returns one row.
+All operations enforce organization ownership. Returned rows include `id`, `sku`,
+`material_type`, `color`, and partner metadata.
+
+Errors include 400 `invalid_catalog_input`, 400 `conflicting_color_hex`, 403 `API_KEY_SCOPE_REQUIRED`,
+404 `catalog_filament_not_found`, 409 `catalog_conflict` for uniqueness conflicts,
+and 500 `catalog_store_failed`. Invalid bodies return the API validation error.
+Print requests can reference synced filaments once #4920 lands.