@instruments/materialgraph 0.37.3 → 0.39.0

package/operations.generated.js

@@ -0,0 +1,189 @@
+// GENERATED by apps/web/scripts/generate-openapi-v1.ts. Do not edit.
+export const MATERIALGRAPH_API_VERSION = "0.8.0";
+const OPERATION_DEFINITIONS = [
+    [
+        "colors.nearestPaints",
+        "GET",
+        "/api/v1/colors/nearest-paints",
+        "find_nearest_paints",
+    ],
+    [
+        "getCatalogueGeneration",
+        "GET",
+        "/api/v1/catalog/generation",
+        "get_catalogue_generation",
+    ],
+    ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"],
+    [
+        "catalogPages",
+        "GET",
+        "/api/v1/catalogs/{catalogId}/pages",
+        "list_catalog_pages",
+    ],
+    [
+        "catalogPageRepresentation",
+        "GET",
+        "/api/v1/catalog-pages/{pageId}/representation",
+        "get_catalog_page_representation",
+    ],
+    [
+        "catalogReferences",
+        "GET",
+        "/api/v1/catalogs/{catalogId}/references",
+        "list_catalog_product_references",
+    ],
+    [
+        "samplizeCatalogue",
+        "GET",
+        "/api/v1/catalogues/samplize/products",
+        "samplize_catalogue_products",
+    ],
+    [
+        "catalogueReferences",
+        "POST",
+        "/api/v1/catalogues/references",
+        "get_catalogue_references_batch",
+    ],
+    [
+        "catalogueCollections",
+        "GET",
+        "/api/v1/catalogues/collections",
+        "list_catalogue_channel_collections",
+    ],
+    [
+        "catalogueDocumentAccess",
+        "GET",
+        "/api/v1/catalogues/documents/{documentId}",
+        "get_catalogue_document_access",
+    ],
+    [
+        "materialBlocks",
+        "GET",
+        "/api/v1/materials/{variantId}/blocks",
+        "list_material_blocks",
+    ],
+    [
+        "listVariantAssets",
+        "GET",
+        "/api/v1/variants/{variantId}/assets",
+        "list_variant_assets",
+    ],
+    [
+        "materialDocuments",
+        "GET",
+        "/api/v1/materials/{variantId}/documents",
+        "list_material_documents",
+    ],
+    [
+        "schema",
+        "GET",
+        "/api/v1/schema/value-dictionaries",
+        "list_schema_value_dictionaries",
+    ],
+    [
+        "pairings",
+        "GET",
+        "/api/v1/materials/{variantId}/pairings",
+        "get_material_pairings",
+    ],
+    [
+        "associatedFinishes",
+        "GET",
+        "/api/v1/associated/finishes",
+        "list_associated_finishes",
+    ],
+    [
+        "associatedProducts",
+        "GET",
+        "/api/v1/associated/products",
+        "list_associated_products",
+    ],
+    ["applicability", "GET", "/api/v1/applicability", "get_applicability"],
+    ["listVariants", "GET", "/api/v1/variants", "list_variants"],
+    [
+        "listVariantFacets",
+        "POST",
+        "/api/v1/variants/facets",
+        "list_variant_facets",
+    ],
+    ["searchVariants", "POST", "/api/v1/variants/search", "search_variants"],
+    [
+        "findVariantsByColor",
+        "GET",
+        "/api/v1/variants/by-color",
+        "find_variants_by_color",
+    ],
+    [
+        "findVariantsByVector",
+        "POST",
+        "/api/v1/variants/by-vector",
+        "find_variants_by_vector",
+    ],
+    [
+        "findSampledTogether",
+        "GET",
+        "/api/v1/variants/sampled-together",
+        "find_sampled_together",
+    ],
+    ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"],
+    ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"],
+    [
+        "resolveColor",
+        "GET",
+        "/api/v1/search/colors/resolve",
+        "resolve_color_name",
+    ],
+    [
+        "listAttributes",
+        "GET",
+        "/api/v1/catalog/attributes",
+        "catalog_list_attributes",
+    ],
+    [
+        "listEnumValues",
+        "GET",
+        "/api/v1/catalog/enum-values",
+        "catalog_list_enum_values",
+    ],
+    ["categories.list", "GET", "/api/v1/categories", "list_categories"],
+    ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"],
+    ["whoami", "GET", "/api/v1/whoami", "whoami"],
+    [
+        "colors.profiles",
+        "GET",
+        "/api/v1/colors/profiles",
+        "get_category_color_profiles",
+    ],
+    [
+        "extractPalette",
+        "POST",
+        "/api/v1/search/palettes/extract",
+        "extract_image_palette",
+    ],
+    ["brands", "GET", "/api/v1/brands", "list_brands"],
+    [
+        "uploadSourceMaterial",
+        "POST",
+        "/api/v1/source-material",
+        "upload_source_material",
+    ],
+    [
+        "workflows.start",
+        "POST",
+        "/api/v1/workflows/{workflowId}/runs",
+        "create_public_run",
+    ],
+    [
+        "workflows.run",
+        "GET",
+        "/api/v1/workflows/{workflowId}/runs/{runId}",
+        "get_public_run",
+    ],
+    [
+        "workflows.streamRunEvents",
+        "GET",
+        "/api/v1/workflows/{workflowId}/runs/{runId}/events",
+        "list_public_run_events",
+    ],
+];
+export const SDK_OPERATIONS = Object.freeze(OPERATION_DEFINITIONS.map(([clientMethod, method, path, operationId]) => Object.freeze({ clientMethod, method, operationId, path })));

package/operations.js

@@ -1,180 +1,6 @@
 import { MaterialGraphError } from "./errors.js";
-export const MATERIALGRAPH_API_VERSION = "0.8.0";
-const OPERATION_DEFINITIONS = [
-    ["catalogs", "GET", "/api/v1/catalogs", "list_catalog_documents"],
-    [
-        "catalogPages",
-        "GET",
-        "/api/v1/catalogs/{catalogId}/pages",
-        "list_catalog_pages",
-    ],
-    [
-        "catalogPageRepresentation",
-        "GET",
-        "/api/v1/catalog-pages/{pageId}/representation",
-        "get_catalog_page_representation",
-    ],
-    [
-        "catalogReferences",
-        "GET",
-        "/api/v1/catalogs/{catalogId}/references",
-        "list_catalog_product_references",
-    ],
-    [
-        "samplizeCatalogue",
-        "GET",
-        "/api/v1/catalogues/samplize/products",
-        "samplize_catalogue_products",
-    ],
-    [
-        "catalogueReferences",
-        "POST",
-        "/api/v1/catalogues/references",
-        "get_catalogue_references_batch",
-    ],
-    [
-        "catalogueCollections",
-        "GET",
-        "/api/v1/catalogues/collections",
-        "list_catalogue_channel_collections",
-    ],
-    [
-        "catalogueDocumentAccess",
-        "GET",
-        "/api/v1/catalogues/documents/{documentId}",
-        "get_catalogue_document_access",
-    ],
-    [
-        "materialBlocks",
-        "GET",
-        "/api/v1/materials/{variantId}/blocks",
-        "list_material_blocks",
-    ],
-    [
-        "listVariantAssets",
-        "GET",
-        "/api/v1/variants/{variantId}/assets",
-        "list_variant_assets",
-    ],
-    [
-        "materialDocuments",
-        "GET",
-        "/api/v1/materials/{variantId}/documents",
-        "list_material_documents",
-    ],
-    [
-        "schema",
-        "GET",
-        "/api/v1/schema/value-dictionaries",
-        "list_schema_value_dictionaries",
-    ],
-    [
-        "pairings",
-        "GET",
-        "/api/v1/materials/{variantId}/pairings",
-        "get_material_pairings",
-    ],
-    [
-        "associatedFinishes",
-        "GET",
-        "/api/v1/associated/finishes",
-        "list_associated_finishes",
-    ],
-    [
-        "associatedProducts",
-        "GET",
-        "/api/v1/associated/products",
-        "list_associated_products",
-    ],
-    ["applicability", "GET", "/api/v1/applicability", "get_applicability"],
-    ["listVariants", "GET", "/api/v1/variants", "list_variants"],
-    [
-        "listVariantFacets",
-        "POST",
-        "/api/v1/variants/facets",
-        "list_variant_facets",
-    ],
-    ["searchVariants", "POST", "/api/v1/variants/search", "search_variants"],
-    [
-        "findVariantsByColor",
-        "POST",
-        "/api/v1/variants/by-color",
-        "find_variants_by_color",
-    ],
-    [
-        "findVariantsByVector",
-        "POST",
-        "/api/v1/variants/by-vector",
-        "find_variants_by_vector",
-    ],
-    [
-        "findSampledTogether",
-        "POST",
-        "/api/v1/variants/sampled-together",
-        "find_sampled_together",
-    ],
-    ["resolveVariant", "POST", "/api/v1/variants/resolve", "resolve_variant"],
-    ["getVariant", "GET", "/api/v1/variants/{variantId}", "get_variant"],
-    [
-        "resolveColor",
-        "GET",
-        "/api/v1/search/colors/resolve",
-        "resolve_color_name",
-    ],
-    [
-        "listAttributes",
-        "GET",
-        "/api/v1/catalog/attributes",
-        "catalog_list_attributes",
-    ],
-    [
-        "listEnumValues",
-        "GET",
-        "/api/v1/catalog/enum-values",
-        "catalog_list_enum_values",
-    ],
-    ["categories.list", "GET", "/api/v1/categories", "list_categories"],
-    ["categories.get", "GET", "/api/v1/categories/{id}", "get_category"],
-    ["whoami", "GET", "/api/v1/whoami", "whoami"],
-    [
-        "colors.profiles",
-        "GET",
-        "/api/v1/colors/profiles",
-        "get_category_color_profiles",
-    ],
-    [
-        "extractPalette",
-        "POST",
-        "/api/v1/search/palettes/extract",
-        "extract_image_palette",
-    ],
-    ["brands", "GET", "/api/v1/brands", "list_brands"],
-    [
-        "uploadSourceMaterial",
-        "POST",
-        "/api/v1/source-material",
-        "upload_source_material",
-    ],
-    [
-        "workflows.start",
-        "POST",
-        "/api/v1/workflows/{workflowId}/runs",
-        "create_public_run",
-    ],
-    [
-        "workflows.run",
-        "GET",
-        "/api/v1/workflows/{workflowId}/runs/{runId}",
-        "get_public_run",
-    ],
-    [
-        "workflows.streamRunEvents",
-        "GET",
-        "/api/v1/workflows/{workflowId}/runs/{runId}/events",
-        "list_public_run_events",
-    ],
-];
-export const SDK_OPERATIONS = Object.freeze(OPERATION_DEFINITIONS.map(([clientMethod, method, path, operationId]) => Object.freeze({ clientMethod, method, operationId, path })));
+import { SDK_OPERATIONS, } from "./operations.generated.js";
+export { MATERIALGRAPH_API_VERSION, SDK_OPERATIONS, } from "./operations.generated.js";
 /** Look up a registered operation by its OpenAPI `operationId`. */
 export const findSdkOperation = (operationId) => SDK_OPERATIONS.find((candidate) => candidate.operationId === operationId);
 /**
@@ -187,7 +13,13 @@ export const resolveOperation = (operationId) => {
     if (!match) {
         throw MaterialGraphError.unexpected(`Unknown SDK operation: ${operationId}`);
     }
-    return match;
+    return { ...match, operationId };
 };
 /** Substitute `{param}` path placeholders with percent-encoded values. */
-export const operationPath = (sdkOperation, pathParams = {}) => Object.entries(pathParams).reduce((path, [name, value]) => path.replace(`{${name}}`, encodeURIComponent(value)), sdkOperation.path);
+export const operationPath = (sdkOperation, pathParams = {}) => {
+    let path = sdkOperation.path;
+    for (const [name, value] of Object.entries(pathParams)) {
+        path = path.replace(`{${name}}`, encodeURIComponent(value));
+    }
+    return path;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@instruments/materialgraph",
-  "version": "0.37.3",
+  "version": "0.39.0",
   "type": "module",
   "exports": {
     ".": {
@@ -21,7 +21,7 @@
     }
   },
   "dependencies": {
-    "@instruments/colorscope": "^10.2.0"
+    "@instruments/colorscope": "^10.2.1"
   },
   "license": "Proprietary",
   "engines": {

package/parse-operation-response.d.ts

@@ -0,0 +1,5 @@
+import type { JsonOperationId, OperationResponses } from "./operation-responses.js";
+import type { JsonSchema } from "./response-schemas.js";
+/** Evaluate the JSON Schema keywords used by the published response contracts. */
+export declare const matchesResponseSchema: (value: unknown, schema: unknown, root: JsonSchema) => boolean;
+export declare const parseOperationResponse: <K extends JsonOperationId>(operationId: K, value: unknown) => Promise<OperationResponses[K]>;

package/parse-operation-response.js

@@ -0,0 +1,202 @@
+import { openClientResponseEnums } from "./client-response-schema.js";
+import { MaterialGraphError } from "./errors.js";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const sameJson = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const matchesType = (value, type) => {
+    if (Array.isArray(type)) {
+        return type.some((candidate) => matchesType(value, candidate));
+    }
+    switch (type) {
+        case undefined: {
+            return true;
+        }
+        case "null": {
+            return value === null;
+        }
+        case "array": {
+            return Array.isArray(value);
+        }
+        case "object": {
+            return isRecord(value);
+        }
+        case "integer": {
+            return typeof value === "number" && Number.isInteger(value);
+        }
+        case "number": {
+            return typeof value === "number" && Number.isFinite(value);
+        }
+        case "string": {
+            return typeof value === "string";
+        }
+        case "boolean": {
+            return typeof value === "boolean";
+        }
+        default: {
+            return false;
+        }
+    }
+};
+const matchesNumberKeywords = (value, schema) => {
+    if (typeof value === "number") {
+        if (typeof schema.minimum === "number" && value < schema.minimum) {
+            return false;
+        }
+        if (typeof schema.maximum === "number" && value > schema.maximum) {
+            return false;
+        }
+        if (typeof schema.exclusiveMinimum === "number" &&
+            value <= schema.exclusiveMinimum) {
+            return false;
+        }
+        if (typeof schema.exclusiveMaximum === "number" &&
+            value >= schema.exclusiveMaximum) {
+            return false;
+        }
+    }
+    return true;
+};
+const matchesStringKeywords = (value, schema) => {
+    if (typeof value === "string") {
+        let length = 0;
+        for (const _codePoint of value) {
+            length += 1;
+        }
+        if (typeof schema.minLength === "number" && length < schema.minLength) {
+            return false;
+        }
+        if (typeof schema.maxLength === "number" && length > schema.maxLength) {
+            return false;
+        }
+        if (typeof schema.pattern === "string" &&
+            !new RegExp(schema.pattern, "u").test(value)) {
+            return false;
+        }
+    }
+    return true;
+};
+const matchesArrayKeywords = (value, schema, root) => {
+    if (Array.isArray(value)) {
+        if (typeof schema.minItems === "number" && value.length < schema.minItems) {
+            return false;
+        }
+        if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
+            return false;
+        }
+        const prefix = Array.isArray(schema.prefixItems) ? schema.prefixItems : [];
+        for (const [index, item] of value.entries()) {
+            const itemSchema = index < prefix.length ? prefix[index] : schema.items;
+            if (itemSchema !== undefined &&
+                !matchesResponseSchema(item, itemSchema, root)) {
+                return false;
+            }
+        }
+    }
+    return true;
+};
+const matchesObjectKeywords = (value, schema, root) => {
+    if (isRecord(value)) {
+        if (Array.isArray(schema.required) &&
+            !schema.required.every((key) => typeof key === "string" && Object.hasOwn(value, key))) {
+            return false;
+        }
+        const properties = isRecord(schema.properties) ? schema.properties : {};
+        for (const [key, item] of Object.entries(value)) {
+            if (schema.propertyNames !== undefined &&
+                !matchesResponseSchema(key, schema.propertyNames, root)) {
+                return false;
+            }
+            const property = Object.hasOwn(properties, key)
+                ? properties[key]
+                : schema.additionalProperties;
+            if (property !== undefined &&
+                !matchesResponseSchema(item, property, root)) {
+                return false;
+            }
+        }
+    }
+    return true;
+};
+const matchesResponseReference = (value, schema, root) => {
+    if (typeof schema.$ref === "string") {
+        if (!schema.$ref.startsWith("#/$defs/")) {
+            return false;
+        }
+        const name = schema.$ref
+            .slice(8)
+            .replaceAll("~1", "/")
+            .replaceAll("~0", "~");
+        if (!isRecord(root.$defs) ||
+            !matchesResponseSchema(value, root.$defs[name], root)) {
+            return false;
+        }
+    }
+    return true;
+};
+const matchesResponseValue = (value, schema) => {
+    if ("const" in schema && !sameJson(value, schema.const)) {
+        return false;
+    }
+    if (Array.isArray(schema.enum) &&
+        !schema.enum.some((candidate) => sameJson(candidate, value))) {
+        return false;
+    }
+    return true;
+};
+/** Evaluate the JSON Schema keywords used by the published response contracts. */
+export const matchesResponseSchema = (value, schema, root) => {
+    if (typeof schema === "boolean") {
+        return schema;
+    }
+    if (!isRecord(schema)) {
+        return false;
+    }
+    if (!matchesResponseReference(value, schema, root)) {
+        return false;
+    }
+    if (!matchesType(value, schema.type)) {
+        return false;
+    }
+    if (!matchesResponseValue(value, schema)) {
+        return false;
+    }
+    if (Array.isArray(schema.anyOf) &&
+        !schema.anyOf.some((candidate) => matchesResponseSchema(value, candidate, root))) {
+        return false;
+    }
+    if ("not" in schema && matchesResponseSchema(value, schema.not, root)) {
+        return false;
+    }
+    if (!matchesNumberKeywords(value, schema)) {
+        return false;
+    }
+    if (!matchesStringKeywords(value, schema)) {
+        return false;
+    }
+    if (!matchesArrayKeywords(value, schema, root)) {
+        return false;
+    }
+    if (!matchesObjectKeywords(value, schema, root)) {
+        return false;
+    }
+    return true;
+};
+const schemas = new Map();
+/** The operation's published schema, rather than a caller's type argument, proves its response. */
+const isOperationResponse = (operationId, value) => {
+    const schema = schemas.get(operationId);
+    return schema !== undefined && matchesResponseSchema(value, schema, schema);
+};
+export const parseOperationResponse = async (operationId, value) => {
+    let schema = schemas.get(operationId);
+    if (!schema) {
+        // oxlint-disable-next-line howells/no-runtime-dynamic-imports -- Load the large response schema bundle only when a response needs validation.
+        const { responseSchema } = await import("./response-schemas.js");
+        schema = responseSchema(operationId);
+        openClientResponseEnums(schema);
+        schemas.set(operationId, schema);
+    }
+    if (!isOperationResponse(operationId, value)) {
+        throw MaterialGraphError.unexpected(`MaterialGraph ${operationId} returned an invalid response`);
+    }
+    return value;
+};

package/response-schemas.generated.d.ts

@@ -1,5 +1,5 @@
 /** The API contract version the schemas were generated from. */
 export declare const RESPONSE_SCHEMA_API_VERSION = "0.8.0";
 /** Every SDK operation whose success response has a published JSON Schema. */
-export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["list_catalog_documents", "list_catalog_pages", "get_catalog_page_representation", "list_catalog_product_references", "samplize_catalogue_products", "get_catalogue_references_batch", "list_catalogue_channel_collections", "get_catalogue_document_access", "list_material_blocks", "list_variant_assets", "list_material_documents", "list_schema_value_dictionaries", "get_material_pairings", "list_associated_finishes", "list_associated_products", "get_applicability", "list_variants", "list_variant_facets", "search_variants", "find_variants_by_color", "find_variants_by_vector", "find_sampled_together", "resolve_variant", "get_variant", "resolve_color_name", "catalog_list_attributes", "catalog_list_enum_values", "list_categories", "get_category", "whoami", "get_category_color_profiles", "extract_image_palette", "list_brands", "upload_source_material", "create_public_run", "get_public_run"];
+export declare const RESPONSE_SCHEMA_OPERATION_IDS: readonly ["find_nearest_paints", "get_catalogue_generation", "list_catalog_documents", "list_catalog_pages", "get_catalog_page_representation", "list_catalog_product_references", "samplize_catalogue_products", "get_catalogue_references_batch", "list_catalogue_channel_collections", "get_catalogue_document_access", "list_material_blocks", "list_variant_assets", "list_material_documents", "list_schema_value_dictionaries", "get_material_pairings", "list_associated_finishes", "list_associated_products", "get_applicability", "list_variants", "list_variant_facets", "search_variants", "find_variants_by_color", "find_variants_by_vector", "find_sampled_together", "resolve_variant", "get_variant", "resolve_color_name", "catalog_list_attributes", "catalog_list_enum_values", "list_categories", "get_category", "whoami", "get_category_color_profiles", "extract_image_palette", "list_brands", "upload_source_material", "create_public_run", "get_public_run"];
 export declare const RESPONSE_SCHEMA_CATALOGUE_JSON: string;