@printhive/api 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.4.0
+
+- Add typed `printers.search` and `filaments.search`, with bounded integer pagination and catalog `filamentId` values.
+- Reuse the web palette printer matcher and the filament picker ranking through narrow partner routes.
+- Add `acceptedByCreate` using the same catalog lookup and admission predicate as print-job creation. Global, unsynced, and invalid-color rows remain searchable with the flag false.
+- Require Read scope on the existing `/v1/search` and `/v1/materials/command-search` API-key routes. Empty-scope keys receive 403.
+
+## 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.

package/README.md

@@ -4,6 +4,8 @@ A TypeScript client for Print Hive's REST API. Version 0.2.0 has zero runtime de
 
 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
@@ -26,11 +28,31 @@ 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.
+`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`, `acceptEngineSettingUpdates`, `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.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.
+
+## Source preparation opt-ins
+
+The opt-ins grant separate permissions. `acceptEngineSettingUpdates` permits eligible stock-setting updates; it does not permit an unqualified printer conversion. The separate `allowUnqualifiedConversion` control is being added in [#5083](https://github.com/PrintHive/hive/pull/5083) and is unavailable until that PR merges. Its conversion consent does not approve customised engine-setting changes. When both controls are available, a request can enable both; each still applies its own checks.
+
+`acceptEngineSettingUpdates` has OpenAPI `default: false` for JSON and multipart creates. For source preparation, `true` accepts engine changes only to settings absent from the source's `different_settings_to_system` customisation list and backed by nonempty `inherits_group` entries for their presets. Missing diff metadata, a missing diff entry, or missing or empty preset inheritance makes the setting customised and it holds. An empty diff entry counts as stock only with inheritance evidence. Empty source setting values do not exempt customised settings. Accepted changes appear in the prepared plate's `lineage.acceptedEngineSettingChanges`.
+
+An engine review hold includes `changes`, `sourceRelease`, and `engineRelease`, alongside the existing `detail`. Each change has `key`, `sourceValue`, `engineValue`, and `slots`. Array values identify changed slots using one-based source slot numbers. Scalar settings have an empty `slots` array. A setting removed by the engine has `engineValue: null`.
+
+Call `printJobs.approveReview(requestId, { changes, sourceRelease, engineRelease })` with the reported values to re-slice. This requires `control` scope. It returns `{ approved: true }` with HTTP 202. Repeating the same approval returns 202 while that submitted review still covers the current pending or ready slice, without starting another slice. This includes Cloud Slice retries that change the slice ID while retaining the plate's approval. A stale or mismatched review returns HTTP 409 `review_conflict`. Approval accepts those changes for those releases, including customised settings. The create-time stock opt-in continues to accept eligible stock changes after approval. Other changes hold again. Poll the receipt again after approval.
+
+For `release: "manual"` requests held by an engine review or another preparation reason, `/release` now returns HTTP 409 `manual_release_not_available` instead of 202. It keeps the holds and does not authorize manual release. Resolve the preparation holds first, then call `/release` when the only hold is `manual_release_required`.
+
+Use the HTTP release/cancel operations described in the [integration reference](../../docs/integrations/printie/planned-production.md) when needed.
+
+## Observe created jobs
+
+`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
 
@@ -79,19 +101,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.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.
+The current source covers creation and request polling under `/v1/print-jobs/create`, partner printer and filament search at `/v1/printers/search` and `/v1/filaments/search`, 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 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.
+`apps/api/scripts/export-openapi.ts` builds a schema-only Fastify app from the real partner search, 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.
 
@@ -132,3 +202,136 @@ 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);
+```
+
+`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.
+Pass the returned `id` as `filaments[].filamentId` in JSON or multipart print-job
+creation. A slot can contain only `{ sourceSlot, filamentId }`, plus an optional
+`targetSlot`. Hive derives material and color from that organization catalog row.
+Explicit `material` and `color` must agree with the row. Material comparisons
+ignore case, and colors accept a leading `#` and either case.
+
+A contradiction returns 422 `filament_catalog_conflict` with the `sourceSlot` in
+`filaments[]`. An unknown or foreign catalog ID returns 422
+`catalog_filament_not_found` with the slot. Catalog rows without a material or a
+six-digit hex color return 422 `invalid_catalog_filament`.
+
+Stored requirements, waiting reasons, and load-step requirements retain
+`filamentId`, `brand`, `name`, `colorName`, `material`, and `colorHex`. Catalog
+identity is a snapshot. Multipart retries reuse the first saved catalog snapshot,
+even if the catalog changes. Matching still uses material and color proximity.
+Requests and stored jobs without `filamentId` keep their existing shape.
+
+Catalog validation errors in JSON or multipart creation do not reserve a new
+idempotency key or `externalId`. For JSON requests that include `filamentId`,
+the same applies to every other validation error that Hive returns
+before it accepts the request. Correct the request, or add the missing catalog
+entry, and retry with the same identity. Existing created or failed receipts
+replay before a new catalog lookup. Once Hive accepts the request, changes to
+its submitted fields or uploaded bytes return 409. Requests without `filamentId`
+keep their existing receipt behavior.
+Filament search returns catalog IDs and `acceptedByCreate`. A result with
+`acceptedByCreate: true` satisfies the current catalog admission checks for
+print-job filament requirements. Other create admission checks still apply.
+
+## Search printers and filaments
+
+Both methods require an organization API key with the `read` tier or higher.
+The API derives organization ownership from the authenticated key.
+
+The existing `GET /v1/search` and `GET /v1/materials/command-search` routes
+also require the `read` tier or higher for API keys. Empty-scope API keys now
+receive 403 on those routes. JWT authentication keeps its existing membership
+checks.
+
+```ts
+const printerPage = await hive.printers.search({ query: "Boo P1S", limit: 10 });
+const filamentPage = await hive.filaments.search({
+  query: "black PETG",
+  limit: 20,
+});
+const redFilaments = await hive.filaments.search({ query: "bambu red" });
+```
+
+| Method                                                  | Return type                   | API route                        |
+| ------------------------------------------------------- | ----------------------------- | -------------------------------- |
+| `printers.search({ query, limit?, offset?, signal? })`  | `Promise<PrinterSearchPage>`  | `GET /v1/printers/search?q=...`  |
+| `filaments.search({ query, limit?, offset?, signal? })` | `Promise<FilamentSearchPage>` | `GET /v1/filaments/search?q=...` |
+
+`SearchOptions` contains the string `query`, optional integer `limit` and
+`offset`, and an optional `AbortSignal`. Both methods return one page and use
+the client's normal GET retry policy. Invalid response shapes throw `TypeError`.
+Missing authentication returns 401. Insufficient API-key scope returns 403.
+Fractional or out-of-range pagination returns 400. `limit` accepts 1–50, with
+default 20. `offset` accepts 0–10,000, with default 0.
+
+`PrinterSearchPage` contains `printers`, `total`, and `query`. Each
+`PrinterSearchResult` includes `id`, name, model, serial, status, location,
+`score`, and `match`. The API reads organization-scoped stored observations
+and uses the same shared candidate builder and ranking code as the web
+palette. Queries contain 1–256 characters. Ranking happens before pagination.
+Each request reads every organization printer in batches of up to 1,000 before
+ranking and pagination. These reads have no per-organization cache. Large
+fleets and frequent queries therefore increase database read work. The SDK
+does not debounce or cache requests.
+
+No printer search index is involved, and no printer is contacted. Printer `id`
+is the identity for explicit printer placement. Search does not guarantee
+readiness; `printers.get(id)` returns stored printer details.
+
+`FilamentSearchPage` contains `filaments`, `total`, `hasMore`, `matchMode`, and
+`originalQuery`. Each `FilamentSearchResult` includes `id`, `filamentId`, name,
+brand, material type, color, diameter, category, organization, and optional SKU.
+`filamentId` equals the catalog material row's `id`. It is not an inventory item
+ID. `acceptedByCreate` reports whether the row satisfies the current partner
+catalog identity and material checks. It does not promise that a print job
+passes file, plate, target, or dispatch admission.
+
+Filament search reuses the web Material Command Search picker, including its
+ranked database query and the organization's global-filament setting. It can
+return organization filaments and enabled global catalog filaments. Global
+rows have `organization_id: "global"`. Results also include unsynced organization
+rows and rows without a color. These rows do not satisfy the current partner
+catalog contract for `filaments[].filamentId` on `POST /v1/print-jobs/create`.
+These rows have `acceptedByCreate: false`. The contract requires an organization-owned partner catalog row, a material
+family, and a six-digit hex color. Search does not filter out other rows.
+
+Queries contain at most 100 characters. An empty query browses the catalog.
+Set the next offset to the previous offset plus the returned filament count
+while `hasMore` is true. When no strict filament match exists, the picker
+returns a broader catalog page with `matchMode: "broadened"` and retains the
+sanitized `originalQuery`. Callers can display that distinction and ask users
+to choose a filament. Neither search method selects a result or creates a job.