@printhive/api 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -1,10 +1,16 @@
 # 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` using the same catalog lookup and admission predicate as print-job creation. Global, unsynced, and invalid-color rows remain searchable with the flag false.
+- 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

package/README.md

@@ -240,20 +240,40 @@ Errors include 400 `invalid_catalog_input`, 400 `conflicting_color_hex`, 403 `AP
 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.
+`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 returns 422
+`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
-six-digit hex color return 422 `invalid_catalog_filament`.
+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`,
@@ -316,18 +336,27 @@ readiness; `printers.get(id)` returns stored printer details.
 `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
+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"`. 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.
+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

package/dist/index.d.cts

@@ -1983,7 +1983,7 @@ interface paths {
                             sourceSlot: number;
                             /**
                              * Format: uuid
-                             * @description Organization catalog filament ID. Derives material and color; explicit values must agree.
+                             * @description Organization partner-catalog filament ID, or a global filament ID when materials.global_filaments_enabled is enabled (default true only when absent). Requires a material of at most 100 characters and one unambiguous color, normalized to #RRGGBB using shared material color rules. Named and 8-digit colors are supported; metadata.colors must agree with color. Merge tombstones are unavailable and include a merged_into replacement hint. Explicit material and color must agree.
                              */
                             filamentId?: string;
                             material?: string;
@@ -2027,7 +2027,7 @@ interface paths {
                             sourceSlot: number;
                             /**
                              * Format: uuid
-                             * @description Organization catalog filament ID. Derives material and color; explicit values must agree.
+                             * @description Organization partner-catalog filament ID, or a global filament ID when materials.global_filaments_enabled is enabled (default true only when absent). Requires a material of at most 100 characters and one unambiguous color, normalized to #RRGGBB using shared material color rules. Named and 8-digit colors are supported; metadata.colors must agree with color. Merge tombstones are unavailable and include a merged_into replacement hint. Explicit material and color must agree.
                              */
                             filamentId?: string;
                             material?: string;
@@ -2289,6 +2289,11 @@ interface paths {
                             message?: string;
                             filaments?: {
                                 sourceSlot?: number;
+                                /**
+                                 * Format: uuid
+                                 * @description Replacement material ID when an accessible catalog filament was merged.
+                                 */
+                                merged_into?: string;
                                 /** @enum {string} */
                                 reason?: "filament_catalog_conflict" | "catalog_filament_not_found" | "invalid_catalog_filament" | "missing_material" | "color_distance" | "slot_empty" | "slot_conflict";
                             }[];
@@ -2307,6 +2312,28 @@ interface paths {
                         };
                     };
                 };
+                /** @description Print creation is temporarily unavailable. catalog_store_failed indicates a failed organization-setting or catalog read and can include the affected source slot. */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @description catalog_store_failed for catalog availability failures, or another existing print-creation availability error code. */
+                            error: string;
+                            message: string;
+                            filaments?: ({
+                                sourceSlot: number;
+                                /** @enum {string} */
+                                reason: "catalog_store_failed";
+                            } & {
+                                [key: string]: unknown;
+                            })[];
+                        } & {
+                            [key: string]: unknown;
+                        };
+                    };
+                };
             };
         };
         delete?: never;

package/dist/index.d.ts

@@ -1983,7 +1983,7 @@ interface paths {
                             sourceSlot: number;
                             /**
                              * Format: uuid
-                             * @description Organization catalog filament ID. Derives material and color; explicit values must agree.
+                             * @description Organization partner-catalog filament ID, or a global filament ID when materials.global_filaments_enabled is enabled (default true only when absent). Requires a material of at most 100 characters and one unambiguous color, normalized to #RRGGBB using shared material color rules. Named and 8-digit colors are supported; metadata.colors must agree with color. Merge tombstones are unavailable and include a merged_into replacement hint. Explicit material and color must agree.
                              */
                             filamentId?: string;
                             material?: string;
@@ -2027,7 +2027,7 @@ interface paths {
                             sourceSlot: number;
                             /**
                              * Format: uuid
-                             * @description Organization catalog filament ID. Derives material and color; explicit values must agree.
+                             * @description Organization partner-catalog filament ID, or a global filament ID when materials.global_filaments_enabled is enabled (default true only when absent). Requires a material of at most 100 characters and one unambiguous color, normalized to #RRGGBB using shared material color rules. Named and 8-digit colors are supported; metadata.colors must agree with color. Merge tombstones are unavailable and include a merged_into replacement hint. Explicit material and color must agree.
                              */
                             filamentId?: string;
                             material?: string;
@@ -2289,6 +2289,11 @@ interface paths {
                             message?: string;
                             filaments?: {
                                 sourceSlot?: number;
+                                /**
+                                 * Format: uuid
+                                 * @description Replacement material ID when an accessible catalog filament was merged.
+                                 */
+                                merged_into?: string;
                                 /** @enum {string} */
                                 reason?: "filament_catalog_conflict" | "catalog_filament_not_found" | "invalid_catalog_filament" | "missing_material" | "color_distance" | "slot_empty" | "slot_conflict";
                             }[];
@@ -2307,6 +2312,28 @@ interface paths {
                         };
                     };
                 };
+                /** @description Print creation is temporarily unavailable. catalog_store_failed indicates a failed organization-setting or catalog read and can include the affected source slot. */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": {
+                            /** @description catalog_store_failed for catalog availability failures, or another existing print-creation availability error code. */
+                            error: string;
+                            message: string;
+                            filaments?: ({
+                                sourceSlot: number;
+                                /** @enum {string} */
+                                reason: "catalog_store_failed";
+                            } & {
+                                [key: string]: unknown;
+                            })[];
+                        } & {
+                            [key: string]: unknown;
+                        };
+                    };
+                };
             };
         };
         delete?: never;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printhive/api",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "private": false,
   "type": "module",
   "description": "Print Hive REST API client",