@printhive/api 0.3.2 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # 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.

package/README.md

@@ -28,11 +28,27 @@ 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.
 
@@ -143,9 +159,9 @@ Only 429, 503, and network failures retry. Permanent `preparation_disabled` neve
 
 ## Coverage and contract maintenance
 
-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.
+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.
 
@@ -222,4 +238,100 @@ All operations enforce organization ownership. Returned rows include `id`, `sku`
 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.
+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.