@printhive/api 0.3.2 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.1
+
+- Document print-job creation's 503 `catalog_store_failed` response, including optional per-slot failure details, in the generated OpenAPI contract. Runtime behavior is unchanged.
+- Global filament search results now have `acceptedByCreate: true` when the organization's global-filament setting and shared catalog admission allow creation. Disabled global IDs remain unavailable to create and are excluded from search. Search and create use one admission operation.
+- Accept enabled global filament IDs on print-job creation and normalize single-color catalog choices with the shared material color rules. Reject ambiguous colors and failed setting reads. Return `merged_into` on merged-filament slot errors. Existing catalog CRUD routes can still return merge tombstones.
+
+## 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` for the catalog admission rules in 0.4.0. At that release, global, unsynced, and invalid-color rows were flagged false. Global support is added in 0.4.1.
+- 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,129 @@ 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 the catalog row.
+Explicit `material` and `color` must agree with the row. Material comparisons
+ignore case, and colors accept a leading `#` and either case.
+
+Create also accepts global filament IDs. Global filaments are platform-managed
+`materials` rows with no organization owner. Search reports their
+`organization_id` as `"global"`. The organization's `materials.global_filaments_enabled`
+setting must be enabled. The setting defaults to enabled when absent, as in the
+web material picker and Smart Queue. Organization-owned rows still require a
+`partner-catalog:` import source. Other organization materials are not admitted
+through this catalog contract.
+
+A contradiction returns 422 `filament_catalog_conflict` with the `sourceSlot` in
+`filaments[]`. An unknown or foreign catalog ID, a merge tombstone, an organization
+row outside the partner catalog, or a global ID when globals are disabled returns 422
+`catalog_filament_not_found` with the slot. Catalog rows without a material or a
+readable color return 422 `invalid_catalog_filament`. The material must be at most
+100 characters. Hive reads `metadata.colors`, falling back to `color`, and normalizes
+named colors and 8-digit hex colors to `#RRGGBB`. Multiple distinct colors, unreadable
+colors, or disagreement between `metadata.colors` and `color` are rejected. Duplicate
+representations of the same RGB color are accepted; alpha is discarded.
+
+For an accessible merge tombstone, the slot error includes `merged_into`, the
+replacement material ID. A setting read error returns 503 `catalog_store_failed`;
+only a missing setting defaults to enabled.
+
+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 diameter is intentionally outside the typed requirement snapshot. Global,
+partner-catalog, and manual requirements continue to match by material and color;
+this change does not add an exact-product or filament-diameter constraint.
+
+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 same catalog
+admission operation used by creation, including the organization's global-filament
+setting, ownership, material, and normalized color 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"`. In SDK 0.4.1, eligible global rows have
+`acceptedByCreate: true` and their IDs can be used in `filaments[].filamentId` on
+`POST /v1/print-jobs/create`. When globals are disabled, search excludes those
+rows and creation rejects their IDs with `catalog_filament_not_found`.
+
+Organization-owned rows require `partner-catalog:` provenance. Unsynced rows,
+merge tombstones, rows without a usable material or color, and rows with ambiguous
+or conflicting colors have `acceptedByCreate: false` when returned by search.
+The material must be at most 100 characters, and the color must normalize to one
+RGB hex value under the shared material color rules. Named and 8-digit colors
+are supported. Search does not otherwise filter out ineligible catalog rows.
+An admission-setting read error returns 503; only a missing setting defaults to
+enabled.
+
+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.