@purveyors/sdk 0.3.0 → 0.4.0

package/dist/index.d.ts

@@ -115,14 +115,14 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/v1/catalog/access": {
+    "/v1/api-keys": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        /** Catalog capabilities and visibility for the caller */
+        /** List API keys for the authenticated user */
         get: {
             parameters: {
                 query?: never;
@@ -132,13 +132,22 @@ interface paths {
             };
             requestBody?: never;
             responses: {
-                /** @description Resolved catalog access policy for the caller's principal */
+                /** @description API keys owned by the authenticated user */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["CatalogAccessResponse"];
+                        "application/json": components["schemas"]["ApiKeyListResponse"];
+                    };
+                };
+                /** @description Invalid API-key request */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -159,81 +168,60 @@ interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
+                /** @description API key not found for the authenticated user */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description API key storage is unavailable */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
             };
         };
         put?: never;
-        post?: never;
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
-    "/v1/catalog": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        /**
-         * List public catalog coffees
-         * @description Public catalog listing. Excludes wholesale-restricted rows and returns only public fields. API-key callers are capped to their plan's per-call row limit. Requesting entitlement-gated params (price/score ranges, process facets, advanced sorts) you are not entitled to is handled per PADR-0013 §7: strict callers (API keys, bearer-session JWTs) receive a 401/403; lenient callers (anonymous, first-party web) get the params stripped with a `meta.notices` entry. Send `Prefer: handling=strict` to opt into strict enforcement; `Prefer: handling=lenient` is honored only for callers already lenient-eligible and cannot downgrade a strict caller's enforcement.
-         */
-        get: {
+        /** Create an API key for the authenticated user */
+        post: {
             parameters: {
-                query?: {
-                    page?: number;
-                    limit?: number;
-                    stocked?: "true" | "false" | "all";
-                    sort?: string;
-                    order?: "asc" | "desc";
-                    showWholesale?: "true" | "false";
-                    wholesaleOnly?: "true" | "false";
-                    origin?: string;
-                    continent?: string;
-                    country?: string | string[];
-                    region?: string;
-                    source?: string | string[];
-                    name?: string;
-                    processing?: string;
-                    variety?: string;
-                    type?: string;
-                    grade?: string;
-                    appearance?: string;
-                    supplier?: string;
-                    dryingMethod?: string;
-                    flavorKeywords?: string | string[];
-                    arrivalDate?: string;
-                    stockedDate?: string;
-                    stockedDays?: number;
-                    coffeeIds?: string;
-                    scoreValueMin?: number | null;
-                    scoreValueMax?: number | null;
-                    pricePerLbMin?: number | null;
-                    pricePerLbMax?: number | null;
-                    processing_base_method?: string;
-                    fermentation_type?: string;
-                    process_additive?: string;
-                    has_additives?: "true" | "false";
-                    processing_disclosure_level?: string;
-                    processing_confidence_min?: number | null;
-                };
-                header?: {
-                    Prefer?: string;
-                };
+                query?: never;
+                header?: never;
                 path?: never;
                 cookie?: never;
             };
-            requestBody?: never;
+            requestBody: {
+                content: {
+                    "application/json": {
+                        name: string;
+                        scopes?: "catalog:read"[];
+                    };
+                };
+            };
             responses: {
-                /** @description A page of public catalog rows with pagination + meta */
-                200: {
+                /** @description API key created. The raw key is returned only once. */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["CatalogListResponse"];
+                        "application/json": components["schemas"]["ApiKeyCreateResponse"];
+                    };
+                };
+                /** @description Invalid API-key request */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -254,77 +242,70 @@ interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
+                /** @description API key not found for the authenticated user */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description API key storage is unavailable */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
             };
         };
-        put?: never;
-        post?: never;
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    "/v1/catalog/facets": {
+    "/v1/api-keys/{id}": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        /**
-         * Catalog filter metadata and counted facets
-         * @description Returns access-aware catalog filter metadata. Values are computed after visibility and entitled content filters are applied; premium process metadata is included only for member sessions and paid API tiers. Requesting entitlement-gated filters you are not entitled to is handled per PADR-0013 §7: strict callers (API keys, bearer-session JWTs) receive a 401/403; lenient callers (anonymous, first-party web) get the filters stripped with a `meta.notices` entry. Send `Prefer: handling=strict` to opt into strict enforcement; `Prefer: handling=lenient` is honored only for callers already lenient-eligible and cannot downgrade a strict caller's enforcement.
-         */
-        get: {
+        get?: never;
+        put?: never;
+        post?: never;
+        /** Revoke an API key owned by the authenticated user */
+        delete: {
             parameters: {
-                query?: {
-                    stocked?: "true" | "false" | "all";
-                    showWholesale?: "true" | "false";
-                    wholesaleOnly?: "true" | "false";
-                    origin?: string;
-                    continent?: string;
-                    country?: string | string[];
-                    region?: string;
-                    source?: string | string[];
-                    name?: string;
-                    processing?: string;
-                    variety?: string;
-                    type?: string;
-                    grade?: string;
-                    appearance?: string;
-                    supplier?: string;
-                    dryingMethod?: string;
-                    flavorKeywords?: string | string[];
-                    arrivalDate?: string;
-                    stockedDate?: string;
-                    stockedDays?: number;
-                    coffeeIds?: string | string[];
-                    scoreValueMin?: number | null;
-                    scoreValueMax?: number | null;
-                    pricePerLbMin?: number | null;
-                    pricePerLbMax?: number | null;
-                    processing_base_method?: string;
-                    fermentation_type?: string;
-                    process_additive?: string;
-                    has_additives?: "true" | "false";
-                    processing_disclosure_level?: string;
-                    processing_confidence_min?: number | null;
-                };
-                header?: {
-                    Prefer?: string;
+                query?: never;
+                header?: never;
+                path: {
+                    id: string;
                 };
-                path?: never;
                 cookie?: never;
             };
             requestBody?: never;
             responses: {
-                /** @description Access-aware catalog filter metadata */
+                /** @description API key revoked */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["CatalogFacetsResponse"];
+                        "application/json": components["schemas"]["ApiKeyMutationResponse"];
+                    };
+                };
+                /** @description Invalid API-key request */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -345,46 +326,68 @@ interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
+                /** @description API key not found for the authenticated user */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description API key storage is unavailable */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
             };
         };
-        put?: never;
-        post?: never;
-        delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    "/v1/catalog/origin-price-stats": {
+    "/v1/api-keys/{id}/rotate": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        /**
-         * Live catalog price context by origin
-         * @description Returns per-origin live catalog price percentiles over the caller-visible stocked catalog. Used by first-party surfaces to compare a lot's visible display price against origin peers.
-         */
-        get: {
+        get?: never;
+        put?: never;
+        /** Rotate an API key owned by the authenticated user */
+        post: {
             parameters: {
-                query?: {
-                    showWholesale?: "true" | "false";
-                    wholesaleOnly?: "true" | "false";
-                };
+                query?: never;
                 header?: never;
-                path?: never;
+                path: {
+                    id: string;
+                };
                 cookie?: never;
             };
             requestBody?: never;
             responses: {
-                /** @description Per-origin price context for caller-visible catalog rows */
-                200: {
+                /** @description Old API key revoked and replacement created. The raw replacement key is returned only once. */
+                201: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["CatalogOriginPriceStatsResponse"];
+                        "application/json": components["schemas"]["ApiKeyCreateResponse"];
+                    };
+                };
+                /** @description Invalid API-key request */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -405,27 +408,40 @@ interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
+                /** @description API key not found for the authenticated user */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description API key storage is unavailable */
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
             };
         };
-        put?: never;
-        post?: never;
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    "/v1/catalog/proof-coverage": {
+    "/v1/catalog/access": {
         parameters: {
             query?: never;
             header?: never;
             path?: never;
             cookie?: never;
         };
-        /**
-         * Aggregate proof-coverage over the public catalog
-         * @description Aggregate-only proof coverage (no row-level evidence) computed over the stocked public catalog.
-         */
+        /** Catalog capabilities and visibility for the caller */
         get: {
             parameters: {
                 query?: never;
@@ -435,13 +451,13 @@ interface paths {
             };
             requestBody?: never;
             responses: {
-                /** @description Proof-coverage summary with per-family buckets and gaps */
+                /** @description Resolved catalog access policy for the caller's principal */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["CatalogProofCoverageResponse"];
+                        "application/json": components["schemas"]["CatalogAccessResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -472,7 +488,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/v1/price-index": {
+    "/v1/catalog": {
         parameters: {
             query?: never;
             header?: never;
@@ -480,34 +496,63 @@ interface paths {
             cookie?: never;
         };
         /**
-         * Parchment Price Index (aggregate snapshots)
-         * @description Aggregate-only price index over price_index_snapshots. Requires an API key with Parchment Intelligence (ppiAccess).
+         * List public catalog coffees
+         * @description Public catalog listing. Excludes wholesale-restricted rows and returns only public fields. API-key callers are capped to their plan's per-call row limit. Requesting entitlement-gated params (price/score ranges, process facets, advanced sorts) you are not entitled to is handled per PADR-0013 §7: strict callers (API keys, bearer-session JWTs) receive a 401/403; lenient callers (anonymous, first-party web) get the params stripped with a `meta.notices` entry. Send `Prefer: handling=strict` to opt into strict enforcement; `Prefer: handling=lenient` is honored only for callers already lenient-eligible and cannot downgrade a strict caller's enforcement.
          */
         get: {
             parameters: {
                 query?: {
                     page?: number;
                     limit?: number;
+                    stocked?: "true" | "false" | "all";
+                    sort?: string;
+                    order?: "asc" | "desc";
+                    showWholesale?: "true" | "false";
+                    wholesaleOnly?: "true" | "false";
                     origin?: string;
-                    process?: string;
+                    continent?: string;
+                    country?: string | string[];
+                    region?: string;
+                    source?: string | string[];
+                    name?: string;
+                    processing?: string;
+                    variety?: string;
+                    type?: string;
                     grade?: string;
-                    from?: string;
-                    to?: string;
-                    wholesale?: "true" | "false";
+                    appearance?: string;
+                    supplier?: string;
+                    dryingMethod?: string;
+                    flavorKeywords?: string | string[];
+                    arrivalDate?: string;
+                    stockedDate?: string;
+                    stockedDays?: number;
+                    coffeeIds?: string;
+                    scoreValueMin?: number | null;
+                    scoreValueMax?: number | null;
+                    pricePerLbMin?: number | null;
+                    pricePerLbMax?: number | null;
+                    processing_base_method?: string;
+                    fermentation_type?: string;
+                    process_additive?: string;
+                    has_additives?: "true" | "false";
+                    processing_disclosure_level?: string;
+                    processing_confidence_min?: number | null;
+                };
+                header?: {
+                    Prefer?: string;
                 };
-                header?: never;
                 path?: never;
                 cookie?: never;
             };
             requestBody?: never;
             responses: {
-                /** @description A page of aggregate price-index snapshots */
+                /** @description A page of public catalog rows with pagination + meta */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["PriceIndexResponse"];
+                        "application/json": components["schemas"]["CatalogListResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -538,7 +583,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/v1/catalog/{id}/similar": {
+    "/v1/catalog/facets": {
         parameters: {
             query?: never;
             header?: never;
@@ -546,41 +591,59 @@ interface paths {
             cookie?: never;
         };
         /**
-         * Find catalog coffees similar to a target coffee
-         * @description Vector-similarity matches for a target catalog coffee, with deterministic identity gating, supplier-diversity re-ranking, and a canonical/similar split. Requires the bean-matching capability (a member session or a paid API plan).
+         * Catalog filter metadata and counted facets
+         * @description Returns access-aware catalog filter metadata. Values are computed after visibility and entitled content filters are applied; premium process metadata is included only for member sessions and paid API tiers. Requesting entitlement-gated filters you are not entitled to is handled per PADR-0013 §7: strict callers (API keys, bearer-session JWTs) receive a 401/403; lenient callers (anonymous, first-party web) get the filters stripped with a `meta.notices` entry. Send `Prefer: handling=strict` to opt into strict enforcement; `Prefer: handling=lenient` is honored only for callers already lenient-eligible and cannot downgrade a strict caller's enforcement.
          */
         get: {
             parameters: {
                 query?: {
-                    threshold?: string;
-                    limit?: number;
-                    stocked_only?: "true" | "false";
-                    mode?: "all" | "likely_same" | "similar_profile";
+                    stocked?: "true" | "false" | "all";
+                    showWholesale?: "true" | "false";
+                    wholesaleOnly?: "true" | "false";
+                    origin?: string;
+                    continent?: string;
+                    country?: string | string[];
+                    region?: string;
+                    source?: string | string[];
+                    name?: string;
+                    processing?: string;
+                    variety?: string;
+                    type?: string;
+                    grade?: string;
+                    appearance?: string;
+                    supplier?: string;
+                    dryingMethod?: string;
+                    flavorKeywords?: string | string[];
+                    arrivalDate?: string;
+                    stockedDate?: string;
+                    stockedDays?: number;
+                    coffeeIds?: string | string[];
+                    scoreValueMin?: number | null;
+                    scoreValueMax?: number | null;
+                    pricePerLbMin?: number | null;
+                    pricePerLbMax?: number | null;
+                    processing_base_method?: string;
+                    fermentation_type?: string;
+                    process_additive?: string;
+                    has_additives?: "true" | "false";
+                    processing_disclosure_level?: string;
+                    processing_confidence_min?: number | null;
                 };
-                header?: never;
-                path: {
-                    id: string;
+                header?: {
+                    Prefer?: string;
                 };
+                path?: never;
                 cookie?: never;
             };
             requestBody?: never;
             responses: {
-                /** @description Target coffee with grouped similarity matches */
+                /** @description Access-aware catalog filter metadata */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["CatalogSimilarityResponse"];
-                    };
-                };
-                /** @description Invalid path id or query parameter */
-                400: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["ErrorResponse"];
+                        "application/json": components["schemas"]["CatalogFacetsResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -601,15 +664,6 @@ interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description Catalog coffee not found */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["ErrorResponse"];
-                    };
-                };
             };
         };
         put?: never;
@@ -620,7 +674,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/v1/procurement/briefs": {
+    "/v1/catalog/origin-price-stats": {
         parameters: {
             query?: never;
             header?: never;
@@ -628,25 +682,28 @@ interface paths {
             cookie?: never;
         };
         /**
-         * List saved sourcing briefs
-         * @description List the authenticated principal's active sourcing briefs. Requires a member session or a paid (member+) API plan; API keys also need the catalog:read scope.
+         * Live catalog price context by origin
+         * @description Returns per-origin live catalog price percentiles over the caller-visible stocked catalog. Used by first-party surfaces to compare a lot's visible display price against origin peers.
          */
         get: {
             parameters: {
-                query?: never;
+                query?: {
+                    showWholesale?: "true" | "false";
+                    wholesaleOnly?: "true" | "false";
+                };
                 header?: never;
                 path?: never;
                 cookie?: never;
             };
             requestBody?: never;
             responses: {
-                /** @description The principal's active sourcing briefs */
+                /** @description Per-origin price context for caller-visible catalog rows */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["SourcingBriefsListResponse"];
+                        "application/json": components["schemas"]["CatalogOriginPriceStatsResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -670,39 +727,40 @@ interface paths {
             };
         };
         put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/catalog/proof-coverage": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
         /**
-         * Create a sourcing brief
-         * @description Create a saved sourcing brief for the authenticated principal. Requires a member session or a paid (member+) API plan; API keys also need the catalog:read scope.
+         * Aggregate proof-coverage over the public catalog
+         * @description Aggregate-only proof coverage (no row-level evidence) computed over the stocked public catalog.
          */
-        post: {
+        get: {
             parameters: {
                 query?: never;
                 header?: never;
                 path?: never;
                 cookie?: never;
             };
-            requestBody?: {
-                content: {
-                    "application/json": components["schemas"]["SourcingBriefCreateRequest"];
-                };
-            };
+            requestBody?: never;
             responses: {
-                /** @description The created sourcing brief */
-                201: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["SourcingBriefResponse"];
-                    };
-                };
-                /** @description Invalid request body or unsupported criteria */
-                400: {
+                /** @description Proof-coverage summary with per-family buckets and gaps */
+                200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["ErrorResponse"];
+                        "application/json": components["schemas"]["CatalogProofCoverageResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -725,13 +783,15 @@ interface paths {
                 };
             };
         };
+        put?: never;
+        post?: never;
         delete?: never;
         options?: never;
         head?: never;
         patch?: never;
         trace?: never;
     };
-    "/v1/procurement/briefs/{id}": {
+    "/v1/price-index": {
         parameters: {
             query?: never;
             header?: never;
@@ -739,27 +799,34 @@ interface paths {
             cookie?: never;
         };
         /**
-         * Get a sourcing brief
-         * @description Fetch one of the authenticated principal's sourcing briefs by id. Requires a member session or a paid (member+) API plan; API keys also need the catalog:read scope.
+         * Parchment Price Index (aggregate snapshots)
+         * @description Aggregate-only price index over price_index_snapshots. Requires an API key with Parchment Intelligence (ppiAccess).
          */
         get: {
             parameters: {
-                query?: never;
-                header?: never;
-                path: {
-                    id: string;
+                query?: {
+                    page?: number;
+                    limit?: number;
+                    origin?: string;
+                    process?: string;
+                    grade?: string;
+                    from?: string;
+                    to?: string;
+                    wholesale?: "true" | "false";
                 };
+                header?: never;
+                path?: never;
                 cookie?: never;
             };
             requestBody?: never;
             responses: {
-                /** @description The requested sourcing brief */
+                /** @description A page of aggregate price-index snapshots */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["SourcingBriefResponse"];
+                        "application/json": components["schemas"]["PriceIndexResponse"];
                     };
                 };
                 /** @description Authentication required */
@@ -780,15 +847,6 @@ interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description No such brief for this principal */
-                404: {
-                    headers: {
-                        [name: string]: unknown;
-                    };
-                    content: {
-                        "application/json": components["schemas"]["ErrorResponse"];
-                    };
-                };
             };
         };
         put?: never;
@@ -799,7 +857,7 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-    "/v1/procurement/briefs/{id}/matches": {
+    "/v1/catalog/{id}/similar": {
         parameters: {
             query?: never;
             header?: never;
@@ -807,14 +865,16 @@ interface paths {
             cookie?: never;
         };
         /**
-         * Run a sourcing brief against the catalog
-         * @description Return the catalog coffees that satisfy a saved brief's criteria, each annotated with the deterministic reasons it matched. Requires a member session or a paid (member+) API plan; API keys also need the catalog:read scope.
+         * Find catalog coffees similar to a target coffee
+         * @description Vector-similarity matches for a target catalog coffee, with deterministic identity gating, supplier-diversity re-ranking, and a canonical/similar split. Requires the bean-matching capability (a member session or a paid API plan).
          */
         get: {
             parameters: {
                 query?: {
-                    page?: number;
+                    threshold?: string;
                     limit?: number;
+                    stocked_only?: "true" | "false";
+                    mode?: "all" | "likely_same" | "similar_profile";
                 };
                 header?: never;
                 path: {
@@ -824,16 +884,16 @@ interface paths {
             };
             requestBody?: never;
             responses: {
-                /** @description A page of catalog matches for the brief */
+                /** @description Target coffee with grouped similarity matches */
                 200: {
                     headers: {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"]["SourcingBriefMatchesResponse"];
+                        "application/json": components["schemas"]["CatalogSimilarityResponse"];
                     };
                 };
-                /** @description Invalid pagination parameter */
+                /** @description Invalid path id or query parameter */
                 400: {
                     headers: {
                         [name: string]: unknown;
@@ -860,7 +920,7 @@ interface paths {
                         "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                /** @description No such brief for this principal */
+                /** @description Catalog coffee not found */
                 404: {
                     headers: {
                         [name: string]: unknown;
@@ -879,29 +939,288 @@ interface paths {
         patch?: never;
         trace?: never;
     };
-}
-interface components {
-    schemas: {
-        HealthResponse: {
-            /** @enum {string} */
-            status: "ok";
-            /** @enum {string} */
-            service: "parchment-api";
-            version: string;
-            /** Format: date-time */
-            timestamp: string;
-        };
-        DiscoveryResponse: {
-            /** @enum {string} */
-            product: "Parchment";
-            namespace: string;
-            health: string;
-            docs: string;
-            openapi: string;
+    "/v1/procurement/briefs": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
         };
-        MeResponse: {
-            authenticated: boolean;
-            /** @enum {string} */
+        /**
+         * List saved sourcing briefs
+         * @description List the authenticated principal's active sourcing briefs. Requires a member session or a paid (member+) API plan; API keys also need the catalog:read scope.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description The principal's active sourcing briefs */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["SourcingBriefsListResponse"];
+                    };
+                };
+                /** @description Authentication required */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Insufficient entitlement (plan or role) */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        /**
+         * Create a sourcing brief
+         * @description Create a saved sourcing brief for the authenticated principal. Requires a member session or a paid (member+) API plan; API keys also need the catalog:read scope.
+         */
+        post: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: {
+                content: {
+                    "application/json": components["schemas"]["SourcingBriefCreateRequest"];
+                };
+            };
+            responses: {
+                /** @description The created sourcing brief */
+                201: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["SourcingBriefResponse"];
+                    };
+                };
+                /** @description Invalid request body or unsupported criteria */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Authentication required */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Insufficient entitlement (plan or role) */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/procurement/briefs/{id}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Get a sourcing brief
+         * @description Fetch one of the authenticated principal's sourcing briefs by id. Requires a member session or a paid (member+) API plan; API keys also need the catalog:read scope.
+         */
+        get: {
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description The requested sourcing brief */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["SourcingBriefResponse"];
+                    };
+                };
+                /** @description Authentication required */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Insufficient entitlement (plan or role) */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description No such brief for this principal */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/procurement/briefs/{id}/matches": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * Run a sourcing brief against the catalog
+         * @description Return the catalog coffees that satisfy a saved brief's criteria, each annotated with the deterministic reasons it matched. Requires a member session or a paid (member+) API plan; API keys also need the catalog:read scope.
+         */
+        get: {
+            parameters: {
+                query?: {
+                    page?: number;
+                    limit?: number;
+                };
+                header?: never;
+                path: {
+                    id: string;
+                };
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description A page of catalog matches for the brief */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["SourcingBriefMatchesResponse"];
+                    };
+                };
+                /** @description Invalid pagination parameter */
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Authentication required */
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description Insufficient entitlement (plan or role) */
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                /** @description No such brief for this principal */
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        };
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+}
+interface components {
+    schemas: {
+        HealthResponse: {
+            /** @enum {string} */
+            status: "ok";
+            /** @enum {string} */
+            service: "parchment-api";
+            version: string;
+            /** Format: date-time */
+            timestamp: string;
+        };
+        DiscoveryResponse: {
+            /** @enum {string} */
+            product: "Parchment";
+            namespace: string;
+            health: string;
+            docs: string;
+            openapi: string;
+        };
+        MeResponse: {
+            authenticated: boolean;
+            /** @enum {string} */
             authKind: "anonymous" | "session" | "api-key";
             userId: string | null;
             appRoles: string[];
@@ -911,885 +1230,1237 @@ interface components {
             ppiAccess: boolean;
             apiScopes: string[];
         };
-        CatalogAccessResponse: {
-            visibility: {
-                isPrivilegedSession: boolean;
-                publicOnly: boolean;
-                showWholesale: boolean;
-                wholesaleOnly: boolean;
+        ApiKeyRecord: {
+            /** Format: uuid */
+            id: string;
+            name: string;
+            /** Format: date-time */
+            createdAt: string | null;
+            /** Format: date-time */
+            lastUsedAt: string | null;
+            isActive: boolean;
+            scopes: string[];
+        };
+        ApiKeyListResponse: {
+            data: components["schemas"]["ApiKeyRecord"][];
+        };
+        ErrorResponse: {
+            error: {
+                code: string;
+                message: string;
+            };
+        };
+        ApiKeyCreateResponse: {
+            /** @description Raw API key. Returned only once; store the secret client-side. */
+            apiKey: string;
+            key: components["schemas"]["ApiKeyRecord"];
+        };
+        ApiKeyMutationResponse: {
+            key: components["schemas"]["ApiKeyRecord"];
+        };
+        CatalogAccessResponse: {
+            visibility: {
+                isPrivilegedSession: boolean;
+                publicOnly: boolean;
+                showWholesale: boolean;
+                wholesaleOnly: boolean;
+            };
+            capabilities: {
+                canViewPublicCatalog: boolean;
+                canViewFullCatalog: boolean;
+                canViewWholesale: boolean;
+                canUseBasicFilters: boolean;
+                canUseAdvancedFilters: boolean;
+                canUseProcessFacets: boolean;
+                canUsePriceScoreRanges: boolean;
+                canUseAdvancedSorts: boolean;
+                canViewPremiumFilterMetadata: boolean;
+                canUseSemanticSearch: boolean;
+                canUseBeanMatching: boolean;
+                canUseSavedSearches: boolean;
+                canExport: boolean;
+            };
+        };
+        CatalogItem: {
+            id: number;
+            name?: string | null;
+            source?: string | null;
+            continent?: string | null;
+            country?: string | null;
+            region?: string | null;
+            processing?: string | null;
+            cultivar_detail?: string | null;
+            type?: string | null;
+            grade?: string | null;
+            appearance?: string | null;
+            score_value?: number | null;
+            cost_lb?: number | null;
+            price_per_lb?: number | null;
+            price_tiers?: unknown;
+            arrival_date?: string | null;
+            stocked_date?: string | null;
+            stocked?: boolean | null;
+            wholesale?: boolean | null;
+            public_coffee?: boolean | null;
+            purveyor_score?: number | null;
+            purveyor_score_confidence?: number | null;
+            purveyor_score_tier?: string | null;
+            purveyor_score_factors?: unknown;
+            purveyor_score_version?: string | null;
+            purveyor_score_updated_at?: string | null;
+            processing_base_method?: string | null;
+            fermentation_type?: string | null;
+            process_additives?: unknown;
+            process_additive_detail?: string | null;
+            fermentation_duration_hours?: number | null;
+            processing_notes?: string | null;
+            processing_disclosure_level?: string | null;
+            processing_confidence?: number | null;
+            processing_evidence_available?: boolean | null;
+            drying_method?: string | null;
+            farm_notes?: string | null;
+            description_short?: string | null;
+            description_long?: string | null;
+            cupping_notes?: string | null;
+            roast_recs?: string | null;
+            lot_size?: string | null;
+            bag_size?: string | null;
+            packaging?: string | null;
+            link?: string | null;
+            last_updated?: string | null;
+            unstocked_date?: string | null;
+            ai_description?: string | null;
+            ai_tasting_notes?: unknown;
+        };
+        CatalogListResponse: {
+            data: components["schemas"]["CatalogItem"][];
+            pagination: {
+                page: number;
+                limit: number;
+                total: number;
+                totalPages: number;
+                hasNext: boolean;
+                hasPrev: boolean;
+            };
+            meta: {
+                /** @enum {string} */
+                resource: "catalog";
+                /** @enum {string} */
+                namespace: "/v1/catalog";
+                /** @enum {string} */
+                version: "v1";
+                auth: {
+                    /** @enum {string} */
+                    kind: "anonymous" | "session" | "api-key";
+                    /** @enum {string|null} */
+                    role: "viewer" | "member" | "admin" | null;
+                    /** @enum {string|null} */
+                    apiPlan: "viewer" | "member" | "enterprise" | null;
+                };
+                access: {
+                    publicOnly: boolean;
+                    showWholesale: boolean;
+                    wholesaleOnly: boolean;
+                    rowLimit: number | null;
+                    limited: boolean;
+                    totalAvailable: number;
+                };
+                /** @description Present only when requested filters/sorts were stripped because the caller lacked the capability. The request still returns 200 with the entitled subset applied. */
+                notices?: {
+                    status: 401 | 403;
+                    /** @enum {string} */
+                    code: "auth_required" | "entitlement_required";
+                    message: string;
+                    deniedParams: string[];
+                }[];
+            };
+        };
+        CatalogFacetsResponse: {
+            /** @description Compatibility-friendly unique values for dropdown filters. Keys with no values are omitted. */
+            values: {
+                sources?: string[];
+                continents?: string[];
+                countries?: string[];
+                regions?: string[];
+                processing?: string[];
+                cultivar_detail?: string[];
+                type?: string[];
+                grade?: string[];
+                appearance?: string[];
+                arrivalDates?: string[];
+                drying_method?: string[];
+                wholesale?: string[];
+                processing_base_method?: string[];
+                fermentation_type?: string[];
+                process_additives?: string[];
+                processing_disclosure_level?: string[];
+            };
+            /** @description Counted facet values for CLI/agent use. Counts are computed after visibility and entitled query filters are applied. */
+            facets: {
+                sources?: {
+                    value: string;
+                    count: number;
+                }[];
+                continents?: {
+                    value: string;
+                    count: number;
+                }[];
+                countries?: {
+                    value: string;
+                    count: number;
+                }[];
+                regions?: {
+                    value: string;
+                    count: number;
+                }[];
+                processing?: {
+                    value: string;
+                    count: number;
+                }[];
+                cultivar_detail?: {
+                    value: string;
+                    count: number;
+                }[];
+                type?: {
+                    value: string;
+                    count: number;
+                }[];
+                grade?: {
+                    value: string;
+                    count: number;
+                }[];
+                appearance?: {
+                    value: string;
+                    count: number;
+                }[];
+                arrivalDates?: {
+                    value: string;
+                    count: number;
+                }[];
+                drying_method?: {
+                    value: string;
+                    count: number;
+                }[];
+                wholesale?: {
+                    value: string;
+                    count: number;
+                }[];
+                processing_base_method?: {
+                    value: string;
+                    count: number;
+                }[];
+                fermentation_type?: {
+                    value: string;
+                    count: number;
+                }[];
+                process_additives?: {
+                    value: string;
+                    count: number;
+                }[];
+                processing_disclosure_level?: {
+                    value: string;
+                    count: number;
+                }[];
+            };
+            meta: {
+                /** @enum {string} */
+                resource: "catalog-facets";
+                /** @enum {string} */
+                namespace: "/v1/catalog/facets";
+                /** @enum {string} */
+                version: "v1";
+                auth: {
+                    /** @enum {string} */
+                    kind: "session" | "api-key";
+                    /** @enum {string|null} */
+                    role: "viewer" | "member" | "admin" | null;
+                    /** @enum {string|null} */
+                    apiPlan: "viewer" | "member" | "enterprise" | null;
+                };
+                access: {
+                    publicOnly: boolean;
+                    showWholesale: boolean;
+                    wholesaleOnly: boolean;
+                    stocked: boolean | null;
+                    premiumMetadata: boolean;
+                };
+                notices?: {
+                    status: 401 | 403;
+                    /** @enum {string} */
+                    code: "auth_required" | "entitlement_required";
+                    message: string;
+                    deniedParams: string[];
+                }[];
+            };
+        };
+        CatalogOriginPriceStatsResponse: {
+            originPriceStats: {
+                origin: string;
+                median: number;
+                q1: number;
+                q3: number;
+                min: number;
+                max: number;
+                sample_size: number;
+                supplier_count: number;
+            }[];
+            meta: {
+                /** @enum {string} */
+                resource: "catalog-origin-price-stats";
+                /** @enum {string} */
+                namespace: "/v1/catalog/origin-price-stats";
+                /** @enum {string} */
+                version: "v1";
+                auth: {
+                    /** @enum {string} */
+                    kind: "anonymous" | "session" | "api-key";
+                    /** @enum {string|null} */
+                    role: "viewer" | "member" | "admin" | null;
+                    /** @enum {string|null} */
+                    apiPlan: "viewer" | "member" | "enterprise" | null;
+                };
+                access: {
+                    publicOnly: boolean;
+                    showWholesale: boolean;
+                    wholesaleOnly: boolean;
+                    /** @enum {string} */
+                    scope: "retail" | "wholesale" | "all";
+                    totalAvailable: number;
+                };
+            };
+        };
+        CatalogProofCoverageResponse: {
+            meta: {
+                /** @enum {string} */
+                resource: "catalog-proof-coverage";
+                /** @enum {string} */
+                namespace: "/v1/catalog/proof-coverage";
+                /** @enum {string} */
+                version: "v1";
+                auth: {
+                    /** @enum {string} */
+                    kind: "anonymous" | "session" | "api-key";
+                    /** @enum {string|null} */
+                    role: "viewer" | "member" | "admin" | null;
+                    /** @enum {string|null} */
+                    apiPlan: "viewer" | "member" | "enterprise" | null;
+                };
+                access: {
+                    publicOnly: boolean;
+                    sampled: number;
+                    totalAvailable: number;
+                };
+            };
+            coverage: {
+                overall: {
+                    label: string;
+                    count: number;
+                    share: number;
+                }[];
+                families: {
+                    [key: string]: {
+                        label: string;
+                        count: number;
+                        share: number;
+                    }[];
+                };
+                signals: {
+                    [key: string]: number;
+                };
+                top_gaps: {
+                    family: string;
+                    label: string;
+                    count: number;
+                    share: number;
+                }[];
+                limitations: string[];
+            };
+        };
+        PriceIndexItem: {
+            date: string;
+            origin: string;
+            process: string | null;
+            grade: string | null;
+            wholesale: boolean;
+            price: {
+                min: number | null;
+                max: number | null;
+                avg: number | null;
+                median: number | null;
+                p25: number | null;
+                p75: number | null;
+                stdev: number | null;
+            };
+            sample: {
+                suppliers: number;
+                listings: number;
+                aggregationTier: number | null;
+            };
+            provenance: {
+                synthetic: boolean;
+            };
+        };
+        PriceIndexResponse: {
+            data: components["schemas"]["PriceIndexItem"][];
+            pagination: {
+                page: number;
+                limit: number;
+                total: number;
+                totalPages: number;
+                hasNext: boolean;
+                hasPrev: boolean;
+            };
+            meta: {
+                /** @enum {string} */
+                resource: "price-index";
+                /** @enum {string} */
+                namespace: "/v1/price-index";
+                /** @enum {string} */
+                version: "v1";
+                auth: {
+                    /** @enum {string} */
+                    kind: "api-key";
+                    /** @enum {string|null} */
+                    apiPlan: "viewer" | "member" | "enterprise" | null;
+                    /** @enum {boolean} */
+                    ppiAccess: true;
+                };
+                filters: {
+                    origin: string | null;
+                    process: string | null;
+                    grade: string | null;
+                    from: string | null;
+                    to: string | null;
+                    wholesale: boolean | null;
+                };
+                access: {
+                    rowLimit: number | null;
+                    limited: boolean;
+                    totalAvailable: number;
+                };
+                source: {
+                    /** @enum {string} */
+                    table: "price_index_snapshots";
+                    /** @enum {boolean} */
+                    aggregateOnly: true;
+                };
+            };
+        };
+        CatalogSimilarityTarget: {
+            id: number;
+            name: string;
+            source: string | null;
+            origin: string | null;
+            country: string | null;
+            continent: string | null;
+            processing: string | null;
+            processing_base_method: string | null;
+            fermentation_type: string | null;
+            drying_method: string | null;
+            stocked: boolean | null;
+            arrival_date: string | null;
+            stocked_date: string | null;
+            price_per_lb: number | null;
+            price_tiers?: unknown;
+            cost_lb: number | null;
+            pricing: {
+                price_per_lb: number | null;
+                price_tiers?: unknown;
+                cost_lb: number | null;
+                /** @enum {number} */
+                baseline_quantity_lbs: 1;
+                baseline_price_per_lb: number | null;
+                /** @enum {string|null} */
+                baseline_source: "price_per_lb" | "price_tiers" | "cost_lb" | null;
+            };
+            proof: {
+                /** @enum {string} */
+                version: "proof-summary-v1";
+                overall: {
+                    /** @enum {string} */
+                    label: "strong" | "partial" | "limited" | "not_available";
+                    families_with_signals: number;
+                };
+                families: {
+                    process: {
+                        label: string;
+                        confidence: number | null;
+                        signals: string[];
+                        message: string;
+                    };
+                    provenance: {
+                        label: string;
+                        confidence: number | null;
+                        signals: string[];
+                        message: string;
+                    };
+                    freshness: {
+                        label: string;
+                        confidence: number | null;
+                        signals: string[];
+                        message: string;
+                    };
+                    pricing: {
+                        label: string;
+                        confidence: number | null;
+                        signals: string[];
+                        message: string;
+                    };
+                };
+                limitations: string[];
+            };
+        };
+        CatalogSimilarityMatch: {
+            coffee: {
+                id: number;
+                name: string;
+                source: string | null;
+                origin: string | null;
+                country: string | null;
+                continent: string | null;
+                processing: string | null;
+                processing_base_method: string | null;
+                fermentation_type: string | null;
+                drying_method: string | null;
+                stocked: boolean | null;
+                arrival_date: string | null;
+                stocked_date: string | null;
+                proof: {
+                    /** @enum {string} */
+                    version: "proof-summary-v1";
+                    overall: {
+                        /** @enum {string} */
+                        label: "strong" | "partial" | "limited" | "not_available";
+                        families_with_signals: number;
+                    };
+                    families: {
+                        process: {
+                            label: string;
+                            confidence: number | null;
+                            signals: string[];
+                            message: string;
+                        };
+                        provenance: {
+                            label: string;
+                            confidence: number | null;
+                            signals: string[];
+                            message: string;
+                        };
+                        freshness: {
+                            label: string;
+                            confidence: number | null;
+                            signals: string[];
+                            message: string;
+                        };
+                        pricing: {
+                            label: string;
+                            confidence: number | null;
+                            signals: string[];
+                            message: string;
+                        };
+                    };
+                    limitations: string[];
+                };
+            };
+            pricing: {
+                price_per_lb: number | null;
+                price_tiers?: unknown;
+                cost_lb: number | null;
+                /** @enum {number} */
+                baseline_quantity_lbs: 1;
+                baseline_price_per_lb: number | null;
+                /** @enum {string|null} */
+                baseline_source: "price_per_lb" | "price_tiers" | "cost_lb" | null;
+            };
+            price_delta_1lb: {
+                amount: number | null;
+                percent: number | null;
+                /** @enum {string} */
+                currency: "USD";
+            };
+            score: {
+                average: number;
+                dimensions: {
+                    origin: number | null;
+                    processing: number | null;
+                    tasting: number | null;
+                };
+                chunk_matches: number;
+            };
+            match: {
+                /** @enum {string} */
+                category: "likely_same" | "similar_profile";
+                classification: {
+                    /** @enum {string} */
+                    kind: "canonical_candidate" | "similar_recommendation";
+                    /** @enum {string} */
+                    identity_eligibility: "eligible" | "blocked" | "insufficient_evidence";
+                    /** @enum {string} */
+                    confidence: "high_beta" | "medium_beta" | "low_beta";
+                    blockers: {
+                        code: string;
+                        /** @enum {string} */
+                        severity: "hard" | "soft";
+                        target_value: string | null;
+                        candidate_value: string | null;
+                    }[];
+                    evidence: string[];
+                };
+                /** @enum {string} */
+                confidence: "high_beta" | "medium_beta" | "low_beta";
+                /** @enum {boolean} */
+                beta: true;
+                language: string;
+                same_supplier: boolean;
             };
-            capabilities: {
-                canViewPublicCatalog: boolean;
-                canViewFullCatalog: boolean;
-                canViewWholesale: boolean;
-                canUseBasicFilters: boolean;
-                canUseAdvancedFilters: boolean;
-                canUseProcessFacets: boolean;
-                canUsePriceScoreRanges: boolean;
-                canUseAdvancedSorts: boolean;
-                canViewPremiumFilterMetadata: boolean;
-                canUseSemanticSearch: boolean;
-                canUseBeanMatching: boolean;
-                canUseSavedSearches: boolean;
-                canExport: boolean;
+            explanation: {
+                summary: string;
+                signals: string[];
             };
-        };
-        ErrorResponse: {
-            error: {
-                code: string;
-                message: string;
+            compatibility: {
+                cost_lb: number | null;
             };
         };
-        CatalogItem: {
-            id: number;
-            name?: string | null;
-            source?: string | null;
-            continent?: string | null;
-            country?: string | null;
-            region?: string | null;
-            processing?: string | null;
-            cultivar_detail?: string | null;
-            type?: string | null;
-            grade?: string | null;
-            appearance?: string | null;
-            score_value?: number | null;
-            cost_lb?: number | null;
-            price_per_lb?: number | null;
-            price_tiers?: unknown;
-            arrival_date?: string | null;
-            stocked_date?: string | null;
-            stocked?: boolean | null;
-            wholesale?: boolean | null;
-            public_coffee?: boolean | null;
-            purveyor_score?: number | null;
-            purveyor_score_confidence?: number | null;
-            purveyor_score_tier?: string | null;
-            purveyor_score_factors?: unknown;
-            purveyor_score_version?: string | null;
-            purveyor_score_updated_at?: string | null;
-            processing_base_method?: string | null;
-            fermentation_type?: string | null;
-            process_additives?: unknown;
-            process_additive_detail?: string | null;
-            fermentation_duration_hours?: number | null;
-            processing_notes?: string | null;
-            processing_disclosure_level?: string | null;
-            processing_confidence?: number | null;
-            processing_evidence_available?: boolean | null;
-            drying_method?: string | null;
-            farm_notes?: string | null;
-            description_short?: string | null;
-            description_long?: string | null;
-            cupping_notes?: string | null;
-            roast_recs?: string | null;
-            lot_size?: string | null;
-            bag_size?: string | null;
-            packaging?: string | null;
-            link?: string | null;
-            last_updated?: string | null;
-            unstocked_date?: string | null;
-            ai_description?: string | null;
-            ai_tasting_notes?: unknown;
-        };
-        CatalogListResponse: {
-            data: components["schemas"]["CatalogItem"][];
-            pagination: {
-                page: number;
-                limit: number;
-                total: number;
-                totalPages: number;
-                hasNext: boolean;
-                hasPrev: boolean;
+        CatalogSimilarityResponse: {
+            data: {
+                target: components["schemas"]["CatalogSimilarityTarget"];
+                groups: {
+                    canonical_candidates: components["schemas"]["CatalogSimilarityMatch"][];
+                    similar_recommendations: components["schemas"]["CatalogSimilarityMatch"][];
+                };
+                matches: components["schemas"]["CatalogSimilarityMatch"][];
             };
             meta: {
                 /** @enum {string} */
-                resource: "catalog";
+                resource: "catalog-similarity";
                 /** @enum {string} */
-                namespace: "/v1/catalog";
+                namespace: "/v1/catalog/{id}/similar";
                 /** @enum {string} */
                 version: "v1";
+                /** @enum {string} */
+                status: "beta";
                 auth: {
                     /** @enum {string} */
-                    kind: "anonymous" | "session" | "api-key";
+                    kind: "session" | "api-key";
                     /** @enum {string|null} */
                     role: "viewer" | "member" | "admin" | null;
                     /** @enum {string|null} */
                     apiPlan: "viewer" | "member" | "enterprise" | null;
                 };
                 access: {
-                    publicOnly: boolean;
-                    showWholesale: boolean;
-                    wholesaleOnly: boolean;
-                    rowLimit: number | null;
-                    limited: boolean;
-                    totalAvailable: number;
+                    /** @enum {string} */
+                    requiredCapability: "canUseBeanMatching";
+                    /** @enum {boolean} */
+                    canUseBeanMatching: true;
                 };
-                /** @description Present only when requested filters/sorts were stripped because the caller lacked the capability. The request still returns 200 with the entitled subset applied. */
-                notices?: {
-                    status: 401 | 403;
+                query: {
+                    threshold: number;
+                    limit: number;
+                    stockedOnly: boolean;
                     /** @enum {string} */
-                    code: "auth_required" | "entitlement_required";
-                    message: string;
-                    deniedParams: string[];
-                }[];
+                    mode: "all" | "likely_same" | "similar_profile";
+                };
+                copy: {
+                    confidence: string;
+                };
+                /** @enum {string} */
+                classification_version: "canonical-match-v1";
+                /** @enum {string} */
+                query_strategy: "bounded-vector-candidates-v1" | "canonical-vector-aggregated-v2" | "legacy-vector-aggregated-v1";
             };
         };
-        CatalogFacetsResponse: {
-            /** @description Compatibility-friendly unique values for dropdown filters. Keys with no values are omitted. */
-            values: {
-                sources?: string[];
-                continents?: string[];
-                countries?: string[];
-                regions?: string[];
-                processing?: string[];
-                cultivar_detail?: string[];
-                type?: string[];
-                grade?: string[];
-                appearance?: string[];
-                arrivalDates?: string[];
-                drying_method?: string[];
-                wholesale?: string[];
-                processing_base_method?: string[];
-                fermentation_type?: string[];
-                process_additives?: string[];
-                processing_disclosure_level?: string[];
-            };
-            /** @description Counted facet values for CLI/agent use. Counts are computed after visibility and entitled query filters are applied. */
-            facets: {
-                sources?: {
-                    value: string;
-                    count: number;
-                }[];
-                continents?: {
-                    value: string;
-                    count: number;
-                }[];
-                countries?: {
-                    value: string;
-                    count: number;
-                }[];
-                regions?: {
-                    value: string;
-                    count: number;
-                }[];
-                processing?: {
-                    value: string;
-                    count: number;
-                }[];
-                cultivar_detail?: {
-                    value: string;
-                    count: number;
-                }[];
-                type?: {
-                    value: string;
-                    count: number;
-                }[];
-                grade?: {
-                    value: string;
-                    count: number;
-                }[];
-                appearance?: {
-                    value: string;
-                    count: number;
-                }[];
-                arrivalDates?: {
-                    value: string;
-                    count: number;
-                }[];
-                drying_method?: {
-                    value: string;
-                    count: number;
-                }[];
-                wholesale?: {
-                    value: string;
-                    count: number;
-                }[];
-                processing_base_method?: {
-                    value: string;
-                    count: number;
-                }[];
-                fermentation_type?: {
-                    value: string;
-                    count: number;
-                }[];
-                process_additives?: {
-                    value: string;
-                    count: number;
-                }[];
-                processing_disclosure_level?: {
-                    value: string;
-                    count: number;
-                }[];
-            };
+        SourcingBriefCriteria: {
+            /** @enum {number} */
+            version?: 1;
+            country?: string;
+            region?: string;
+            processing?: string;
+            processing_base_method?: string;
+            max_price_per_lb?: number;
+            stocked_only?: boolean;
+            wholesale_only?: boolean;
+            stocked_days?: number;
+        };
+        SourcingBriefResource: {
+            id: string;
+            name: string;
+            criteria: components["schemas"]["SourcingBriefCriteria"] & Record<string, never>;
+            /** @enum {string} */
+            cadence: "manual";
+            isActive: boolean;
+            lastRunAt: string | null;
+            createdAt: string;
+            updatedAt: string;
+        };
+        SourcingBriefsListResponse: {
+            data: components["schemas"]["SourcingBriefResource"][];
             meta: {
                 /** @enum {string} */
-                resource: "catalog-facets";
+                resource: "procurement-briefs";
                 /** @enum {string} */
-                namespace: "/v1/catalog/facets";
+                namespace: "/v1/procurement/briefs";
                 /** @enum {string} */
                 version: "v1";
                 auth: {
                     /** @enum {string} */
                     kind: "session" | "api-key";
                     /** @enum {string|null} */
-                    role: "viewer" | "member" | "admin" | null;
+                    role: "admin" | "member" | "viewer" | null;
                     /** @enum {string|null} */
                     apiPlan: "viewer" | "member" | "enterprise" | null;
                 };
-                access: {
-                    publicOnly: boolean;
-                    showWholesale: boolean;
-                    wholesaleOnly: boolean;
-                    stocked: boolean | null;
-                    premiumMetadata: boolean;
-                };
-                notices?: {
-                    status: 401 | 403;
-                    /** @enum {string} */
-                    code: "auth_required" | "entitlement_required";
-                    message: string;
-                    deniedParams: string[];
-                }[];
             };
         };
-        CatalogOriginPriceStatsResponse: {
-            originPriceStats: {
-                origin: string;
-                median: number;
-                q1: number;
-                q3: number;
-                min: number;
-                max: number;
-                sample_size: number;
-                supplier_count: number;
-            }[];
+        SourcingBriefResponse: {
+            data: components["schemas"]["SourcingBriefResource"];
             meta: {
                 /** @enum {string} */
-                resource: "catalog-origin-price-stats";
+                resource: "procurement-brief";
                 /** @enum {string} */
-                namespace: "/v1/catalog/origin-price-stats";
+                namespace: "/v1/procurement/briefs" | "/v1/procurement/briefs/:id";
                 /** @enum {string} */
                 version: "v1";
                 auth: {
                     /** @enum {string} */
-                    kind: "anonymous" | "session" | "api-key";
+                    kind: "session" | "api-key";
                     /** @enum {string|null} */
-                    role: "viewer" | "member" | "admin" | null;
+                    role: "admin" | "member" | "viewer" | null;
                     /** @enum {string|null} */
                     apiPlan: "viewer" | "member" | "enterprise" | null;
                 };
-                access: {
-                    publicOnly: boolean;
-                    showWholesale: boolean;
-                    wholesaleOnly: boolean;
-                    /** @enum {string} */
-                    scope: "retail" | "wholesale" | "all";
-                    totalAvailable: number;
-                };
             };
         };
-        CatalogProofCoverageResponse: {
+        SourcingBriefCreateRequest: {
+            /** @description Human label, 1-120 chars. */
+            name: string;
+            criteria: components["schemas"]["SourcingBriefCriteria"] & unknown;
+            /** @enum {string} */
+            cadence?: "manual";
+        };
+        SourcingBriefMatch: {
+            id: number;
+            name?: string | null;
+            source?: string | null;
+            continent?: string | null;
+            country?: string | null;
+            region?: string | null;
+            processing?: string | null;
+            processing_base_method?: string | null;
+            fermentation_type?: string | null;
+            drying_method?: string | null;
+            cultivar_detail?: string | null;
+            type?: string | null;
+            grade?: string | null;
+            appearance?: string | null;
+            score_value?: number | null;
+            purveyor_score?: number | null;
+            cost_lb?: number | null;
+            price_per_lb?: number | null;
+            price_tiers?: unknown;
+            arrival_date?: string | null;
+            stocked_date?: string | null;
+            stocked?: boolean | null;
+            wholesale?: boolean | null;
+            public_coffee?: boolean | null;
+            matchReasons: string[];
+        };
+        SourcingBriefMatchesResponse: {
+            data: components["schemas"]["SourcingBriefMatch"][];
+            pagination: {
+                page: number;
+                limit: number;
+                total: number;
+                totalPages: number;
+                hasNext: boolean;
+                hasPrev: boolean;
+            };
             meta: {
                 /** @enum {string} */
-                resource: "catalog-proof-coverage";
+                resource: "procurement-brief-matches";
                 /** @enum {string} */
-                namespace: "/v1/catalog/proof-coverage";
+                namespace: "/v1/procurement/briefs/:id/matches";
                 /** @enum {string} */
                 version: "v1";
+                generatedAt: string;
                 auth: {
                     /** @enum {string} */
-                    kind: "anonymous" | "session" | "api-key";
+                    kind: "session" | "api-key";
                     /** @enum {string|null} */
-                    role: "viewer" | "member" | "admin" | null;
+                    role: "admin" | "member" | "viewer" | null;
                     /** @enum {string|null} */
                     apiPlan: "viewer" | "member" | "enterprise" | null;
                 };
-                access: {
-                    publicOnly: boolean;
-                    sampled: number;
-                    totalAvailable: number;
-                };
+                brief: components["schemas"]["SourcingBriefResource"];
+                criteria: components["schemas"]["SourcingBriefCriteria"] & Record<string, never>;
+                limitations: string[];
             };
-            coverage: {
-                overall: {
-                    label: string;
-                    count: number;
-                    share: number;
-                }[];
-                families: {
-                    [key: string]: {
-                        label: string;
-                        count: number;
-                        share: number;
-                    }[];
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
+interface ParchmentClientOptions {
+    /** Base URL of the Parchment API, e.g. https://api.purveyors.io */
+    baseUrl: string;
+    /**
+     * Optional bearer token (a Supabase JWT or, later, an API key). Sent as
+     * `Authorization: Bearer <token>`. Auth is resolved server-side against the
+     * unified principal model; the SDK only forwards the credential.
+     */
+    token?: string;
+    /** Override the fetch implementation (useful for tests or custom runtimes). */
+    fetch?: ClientOptions["fetch"];
+}
+/** Query parameters for {@link ParchmentClient.catalog.list}. */
+type CatalogListQuery = NonNullable<paths["/v1/catalog"]["get"]["parameters"]["query"]>;
+/** Query parameters for {@link ParchmentClient.catalog.facets}. */
+type CatalogFacetsQuery = NonNullable<paths["/v1/catalog/facets"]["get"]["parameters"]["query"]>;
+/**
+ * Optional headers for {@link ParchmentClient.catalog.list}, notably the
+ * RFC 7240 `Prefer: handling=lenient|strict` override (PADR-0013 §7). Sending
+ * `handling=lenient` opts a strict caller (API key or bearer-session JWT) back
+ * into strip-with-notice degradation instead of a 401/403 hard-deny.
+ */
+type CatalogListHeaders = NonNullable<paths["/v1/catalog"]["get"]["parameters"]["header"]>;
+/** Optional headers for {@link ParchmentClient.catalog.facets}; see {@link CatalogListHeaders}. */
+type CatalogFacetsHeaders = NonNullable<paths["/v1/catalog/facets"]["get"]["parameters"]["header"]>;
+/** Query parameters for {@link ParchmentClient.catalog.originPriceStats}. */
+type CatalogOriginPriceStatsQuery = NonNullable<paths["/v1/catalog/origin-price-stats"]["get"]["parameters"]["query"]>;
+/** Query parameters for {@link ParchmentClient.catalog.similar}. */
+type CatalogSimilarQuery = NonNullable<paths["/v1/catalog/{id}/similar"]["get"]["parameters"]["query"]>;
+/** Query parameters for {@link ParchmentClient.priceIndex.list}. */
+type PriceIndexQuery = NonNullable<paths["/v1/price-index"]["get"]["parameters"]["query"]>;
+/** Query parameters for {@link ParchmentClient.procurement.briefs.matches}. */
+type BriefMatchesQuery = NonNullable<paths["/v1/procurement/briefs/{id}/matches"]["get"]["parameters"]["query"]>;
+/** Request body for {@link ParchmentClient.procurement.briefs.create}. */
+type SourcingBriefCreateRequest = components["schemas"]["SourcingBriefCreateRequest"];
+/** Request body for {@link ParchmentClient.apiKeys.create}. */
+type ApiKeyCreateRequest = NonNullable<paths["/v1/api-keys"]["post"]["requestBody"]>["content"]["application/json"];
+/**
+ * Create a typed Parchment API client.
+ *
+ * The generated core (openapi-fetch over the generated `paths` types) is the
+ * contract truth; the named helpers below are the hand-maintained ergonomic
+ * layer and grow as endpoints land. `raw` always exposes the underlying typed
+ * client for direct path access to anything not yet wrapped.
+ */
+declare function createParchmentClient(options: ParchmentClientOptions): {
+    /** The underlying typed openapi-fetch client for direct path access. */
+    raw: openapi_fetch.Client<paths, `${string}/${string}`>;
+    /** Liveness and service identity. */
+    health: () => Promise<openapi_fetch.FetchResponse<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
                 };
-                signals: {
-                    [key: string]: number;
+                content: {
+                    "application/json": components["schemas"]["HealthResponse"];
                 };
-                top_gaps: {
-                    family: string;
-                    label: string;
-                    count: number;
-                    share: number;
-                }[];
-                limitations: string[];
             };
         };
-        PriceIndexItem: {
-            date: string;
-            origin: string;
-            process: string | null;
-            grade: string | null;
-            wholesale: boolean;
-            price: {
-                min: number | null;
-                max: number | null;
-                avg: number | null;
-                median: number | null;
-                p25: number | null;
-                p75: number | null;
-                stdev: number | null;
+    }, openapi_fetch.FetchOptions<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["HealthResponse"];
+                };
             };
-            sample: {
-                suppliers: number;
-                listings: number;
-                aggregationTier: number | null;
+        };
+    }> | undefined, `${string}/${string}`>>;
+    /** Resolved principal and entitlements for the caller. */
+    me: () => Promise<openapi_fetch.FetchResponse<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MeResponse"];
+                };
             };
-            provenance: {
-                synthetic: boolean;
+        };
+    }, openapi_fetch.FetchOptions<{
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MeResponse"];
+                };
             };
         };
-        PriceIndexResponse: {
-            data: components["schemas"]["PriceIndexItem"][];
-            pagination: {
-                page: number;
-                limit: number;
-                total: number;
-                totalPages: number;
-                hasNext: boolean;
-                hasPrev: boolean;
+    }> | undefined, `${string}/${string}`>>;
+    apiKeys: {
+        /** List API keys owned by the authenticated session user. */
+        list: () => Promise<openapi_fetch.FetchResponse<{
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
             };
-            meta: {
-                /** @enum {string} */
-                resource: "price-index";
-                /** @enum {string} */
-                namespace: "/v1/price-index";
-                /** @enum {string} */
-                version: "v1";
-                auth: {
-                    /** @enum {string} */
-                    kind: "api-key";
-                    /** @enum {string|null} */
-                    apiPlan: "viewer" | "member" | "enterprise" | null;
-                    /** @enum {boolean} */
-                    ppiAccess: true;
+            requestBody?: never;
+            responses: {
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ApiKeyListResponse"];
+                    };
                 };
-                filters: {
-                    origin: string | null;
-                    process: string | null;
-                    grade: string | null;
-                    from: string | null;
-                    to: string | null;
-                    wholesale: boolean | null;
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
-                access: {
-                    rowLimit: number | null;
-                    limited: boolean;
-                    totalAvailable: number;
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
-                source: {
-                    /** @enum {string} */
-                    table: "price_index_snapshots";
-                    /** @enum {boolean} */
-                    aggregateOnly: true;
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
             };
-        };
-        CatalogSimilarityTarget: {
-            id: number;
-            name: string;
-            source: string | null;
-            origin: string | null;
-            country: string | null;
-            continent: string | null;
-            processing: string | null;
-            processing_base_method: string | null;
-            fermentation_type: string | null;
-            drying_method: string | null;
-            stocked: boolean | null;
-            arrival_date: string | null;
-            stocked_date: string | null;
-            price_per_lb: number | null;
-            price_tiers?: unknown;
-            cost_lb: number | null;
-            pricing: {
-                price_per_lb: number | null;
-                price_tiers?: unknown;
-                cost_lb: number | null;
-                /** @enum {number} */
-                baseline_quantity_lbs: 1;
-                baseline_price_per_lb: number | null;
-                /** @enum {string|null} */
-                baseline_source: "price_per_lb" | "price_tiers" | "cost_lb" | null;
+        }, openapi_fetch.FetchOptions<{
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
             };
-            proof: {
-                /** @enum {string} */
-                version: "proof-summary-v1";
-                overall: {
-                    /** @enum {string} */
-                    label: "strong" | "partial" | "limited" | "not_available";
-                    families_with_signals: number;
+            requestBody?: never;
+            responses: {
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ApiKeyListResponse"];
+                    };
                 };
-                families: {
-                    process: {
-                        label: string;
-                        confidence: number | null;
-                        signals: string[];
-                        message: string;
+                400: {
+                    headers: {
+                        [name: string]: unknown;
                     };
-                    provenance: {
-                        label: string;
-                        confidence: number | null;
-                        signals: string[];
-                        message: string;
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
-                    freshness: {
-                        label: string;
-                        confidence: number | null;
-                        signals: string[];
-                        message: string;
+                };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
                     };
-                    pricing: {
-                        label: string;
-                        confidence: number | null;
-                        signals: string[];
-                        message: string;
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
-                limitations: string[];
-            };
-        };
-        CatalogSimilarityMatch: {
-            coffee: {
-                id: number;
-                name: string;
-                source: string | null;
-                origin: string | null;
-                country: string | null;
-                continent: string | null;
-                processing: string | null;
-                processing_base_method: string | null;
-                fermentation_type: string | null;
-                drying_method: string | null;
-                stocked: boolean | null;
-                arrival_date: string | null;
-                stocked_date: string | null;
-                proof: {
-                    /** @enum {string} */
-                    version: "proof-summary-v1";
-                    overall: {
-                        /** @enum {string} */
-                        label: "strong" | "partial" | "limited" | "not_available";
-                        families_with_signals: number;
+                403: {
+                    headers: {
+                        [name: string]: unknown;
                     };
-                    families: {
-                        process: {
-                            label: string;
-                            confidence: number | null;
-                            signals: string[];
-                            message: string;
-                        };
-                        provenance: {
-                            label: string;
-                            confidence: number | null;
-                            signals: string[];
-                            message: string;
-                        };
-                        freshness: {
-                            label: string;
-                            confidence: number | null;
-                            signals: string[];
-                            message: string;
-                        };
-                        pricing: {
-                            label: string;
-                            confidence: number | null;
-                            signals: string[];
-                            message: string;
-                        };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
-                    limitations: string[];
                 };
             };
-            pricing: {
-                price_per_lb: number | null;
-                price_tiers?: unknown;
-                cost_lb: number | null;
-                /** @enum {number} */
-                baseline_quantity_lbs: 1;
-                baseline_price_per_lb: number | null;
-                /** @enum {string|null} */
-                baseline_source: "price_per_lb" | "price_tiers" | "cost_lb" | null;
-            };
-            price_delta_1lb: {
-                amount: number | null;
-                percent: number | null;
-                /** @enum {string} */
-                currency: "USD";
+        }> | undefined, `${string}/${string}`>>;
+        /** Create an API key. The raw secret is returned only once. */
+        create: (body: ApiKeyCreateRequest) => Promise<openapi_fetch.FetchResponse<{
+            parameters: {
+                query?: never;
+                header?: never;
+                path?: never;
+                cookie?: never;
             };
-            score: {
-                average: number;
-                dimensions: {
-                    origin: number | null;
-                    processing: number | null;
-                    tasting: number | null;
+            requestBody: {
+                content: {
+                    "application/json": {
+                        name: string;
+                        scopes?: "catalog:read"[];
+                    };
                 };
-                chunk_matches: number;
             };
-            match: {
-                /** @enum {string} */
-                category: "likely_same" | "similar_profile";
-                classification: {
-                    /** @enum {string} */
-                    kind: "canonical_candidate" | "similar_recommendation";
-                    /** @enum {string} */
-                    identity_eligibility: "eligible" | "blocked" | "insufficient_evidence";
-                    /** @enum {string} */
-                    confidence: "high_beta" | "medium_beta" | "low_beta";
-                    blockers: {
-                        code: string;
-                        /** @enum {string} */
-                        severity: "hard" | "soft";
-                        target_value: string | null;
-                        candidate_value: string | null;
-                    }[];
-                    evidence: string[];
+            responses: {
+                201: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ApiKeyCreateResponse"];
+                    };
                 };
-                /** @enum {string} */
-                confidence: "high_beta" | "medium_beta" | "low_beta";
-                /** @enum {boolean} */
-                beta: true;
-                language: string;
-                same_supplier: boolean;
-            };
-            explanation: {
-                summary: string;
-                signals: string[];
-            };
-            compatibility: {
-                cost_lb: number | null;
-            };
-        };
-        CatalogSimilarityResponse: {
-            data: {
-                target: components["schemas"]["CatalogSimilarityTarget"];
-                groups: {
-                    canonical_candidates: components["schemas"]["CatalogSimilarityMatch"][];
-                    similar_recommendations: components["schemas"]["CatalogSimilarityMatch"][];
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
-                matches: components["schemas"]["CatalogSimilarityMatch"][];
-            };
-            meta: {
-                /** @enum {string} */
-                resource: "catalog-similarity";
-                /** @enum {string} */
-                namespace: "/v1/catalog/{id}/similar";
-                /** @enum {string} */
-                version: "v1";
-                /** @enum {string} */
-                status: "beta";
-                auth: {
-                    /** @enum {string} */
-                    kind: "session" | "api-key";
-                    /** @enum {string|null} */
-                    role: "viewer" | "member" | "admin" | null;
-                    /** @enum {string|null} */
-                    apiPlan: "viewer" | "member" | "enterprise" | null;
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
-                access: {
-                    /** @enum {string} */
-                    requiredCapability: "canUseBeanMatching";
-                    /** @enum {boolean} */
-                    canUseBeanMatching: true;
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
-                query: {
-                    threshold: number;
-                    limit: number;
-                    stockedOnly: boolean;
-                    /** @enum {string} */
-                    mode: "all" | "likely_same" | "similar_profile";
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
-                copy: {
-                    confidence: string;
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
-                /** @enum {string} */
-                classification_version: "canonical-match-v1";
-                /** @enum {string} */
-                query_strategy: "bounded-vector-candidates-v1" | "canonical-vector-aggregated-v2" | "legacy-vector-aggregated-v1";
             };
-        };
-        SourcingBriefCriteria: {
-            /** @enum {number} */
-            version?: 1;
-            country?: string;
-            region?: string;
-            processing?: string;
-            processing_base_method?: string;
-            max_price_per_lb?: number;
-            stocked_only?: boolean;
-            wholesale_only?: boolean;
-            stocked_days?: number;
-        };
-        SourcingBriefResource: {
-            id: string;
-            name: string;
-            criteria: components["schemas"]["SourcingBriefCriteria"] & Record<string, never>;
-            /** @enum {string} */
-            cadence: "manual";
-            isActive: boolean;
-            lastRunAt: string | null;
-            createdAt: string;
-            updatedAt: string;
-        };
-        SourcingBriefsListResponse: {
-            data: components["schemas"]["SourcingBriefResource"][];
-            meta: {
-                /** @enum {string} */
-                resource: "procurement-briefs";
-                /** @enum {string} */
-                namespace: "/v1/procurement/briefs";
-                /** @enum {string} */
-                version: "v1";
-                auth: {
-                    /** @enum {string} */
-                    kind: "session" | "api-key";
-                    /** @enum {string|null} */
-                    role: "admin" | "member" | "viewer" | null;
-                    /** @enum {string|null} */
-                    apiPlan: "viewer" | "member" | "enterprise" | null;
+        }, {
+            body: {
+                name: string;
+                scopes?: "catalog:read"[];
+            };
+        }, `${string}/${string}`>>;
+        /** Revoke an API key owned by the authenticated session user. */
+        revoke: (id: string) => Promise<openapi_fetch.FetchResponse<{
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    id: string;
                 };
+                cookie?: never;
             };
-        };
-        SourcingBriefResponse: {
-            data: components["schemas"]["SourcingBriefResource"];
-            meta: {
-                /** @enum {string} */
-                resource: "procurement-brief";
-                /** @enum {string} */
-                namespace: "/v1/procurement/briefs" | "/v1/procurement/briefs/:id";
-                /** @enum {string} */
-                version: "v1";
-                auth: {
-                    /** @enum {string} */
-                    kind: "session" | "api-key";
-                    /** @enum {string|null} */
-                    role: "admin" | "member" | "viewer" | null;
-                    /** @enum {string|null} */
-                    apiPlan: "viewer" | "member" | "enterprise" | null;
+            requestBody?: never;
+            responses: {
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ApiKeyMutationResponse"];
+                    };
+                };
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
             };
-        };
-        SourcingBriefCreateRequest: {
-            /** @description Human label, 1-120 chars. */
-            name: string;
-            criteria: components["schemas"]["SourcingBriefCriteria"] & unknown;
-            /** @enum {string} */
-            cadence?: "manual";
-        };
-        SourcingBriefMatch: {
-            id: number;
-            name?: string | null;
-            source?: string | null;
-            continent?: string | null;
-            country?: string | null;
-            region?: string | null;
-            processing?: string | null;
-            processing_base_method?: string | null;
-            fermentation_type?: string | null;
-            drying_method?: string | null;
-            cultivar_detail?: string | null;
-            type?: string | null;
-            grade?: string | null;
-            appearance?: string | null;
-            score_value?: number | null;
-            purveyor_score?: number | null;
-            cost_lb?: number | null;
-            price_per_lb?: number | null;
-            price_tiers?: unknown;
-            arrival_date?: string | null;
-            stocked_date?: string | null;
-            stocked?: boolean | null;
-            wholesale?: boolean | null;
-            public_coffee?: boolean | null;
-            matchReasons: string[];
-        };
-        SourcingBriefMatchesResponse: {
-            data: components["schemas"]["SourcingBriefMatch"][];
-            pagination: {
-                page: number;
-                limit: number;
-                total: number;
-                totalPages: number;
-                hasNext: boolean;
-                hasPrev: boolean;
+        }, {
+            params: {
+                path: {
+                    id: string;
+                };
             };
-            meta: {
-                /** @enum {string} */
-                resource: "procurement-brief-matches";
-                /** @enum {string} */
-                namespace: "/v1/procurement/briefs/:id/matches";
-                /** @enum {string} */
-                version: "v1";
-                generatedAt: string;
-                auth: {
-                    /** @enum {string} */
-                    kind: "session" | "api-key";
-                    /** @enum {string|null} */
-                    role: "admin" | "member" | "viewer" | null;
-                    /** @enum {string|null} */
-                    apiPlan: "viewer" | "member" | "enterprise" | null;
+        }, `${string}/${string}`>>;
+        /** Rotate an API key and return the replacement secret once. */
+        rotate: (id: string) => Promise<openapi_fetch.FetchResponse<{
+            parameters: {
+                query?: never;
+                header?: never;
+                path: {
+                    id: string;
                 };
-                brief: components["schemas"]["SourcingBriefResource"];
-                criteria: components["schemas"]["SourcingBriefCriteria"] & Record<string, never>;
-                limitations: string[];
+                cookie?: never;
             };
-        };
-    };
-    responses: never;
-    parameters: never;
-    requestBodies: never;
-    headers: never;
-    pathItems: never;
-}
-
-interface ParchmentClientOptions {
-    /** Base URL of the Parchment API, e.g. https://api.purveyors.io */
-    baseUrl: string;
-    /**
-     * Optional bearer token (a Supabase JWT or, later, an API key). Sent as
-     * `Authorization: Bearer <token>`. Auth is resolved server-side against the
-     * unified principal model; the SDK only forwards the credential.
-     */
-    token?: string;
-    /** Override the fetch implementation (useful for tests or custom runtimes). */
-    fetch?: ClientOptions["fetch"];
-}
-/** Query parameters for {@link ParchmentClient.catalog.list}. */
-type CatalogListQuery = NonNullable<paths["/v1/catalog"]["get"]["parameters"]["query"]>;
-/** Query parameters for {@link ParchmentClient.catalog.facets}. */
-type CatalogFacetsQuery = NonNullable<paths["/v1/catalog/facets"]["get"]["parameters"]["query"]>;
-/**
- * Optional headers for {@link ParchmentClient.catalog.list}, notably the
- * RFC 7240 `Prefer: handling=lenient|strict` override (PADR-0013 §7). Sending
- * `handling=lenient` opts a strict caller (API key or bearer-session JWT) back
- * into strip-with-notice degradation instead of a 401/403 hard-deny.
- */
-type CatalogListHeaders = NonNullable<paths["/v1/catalog"]["get"]["parameters"]["header"]>;
-/** Optional headers for {@link ParchmentClient.catalog.facets}; see {@link CatalogListHeaders}. */
-type CatalogFacetsHeaders = NonNullable<paths["/v1/catalog/facets"]["get"]["parameters"]["header"]>;
-/** Query parameters for {@link ParchmentClient.catalog.originPriceStats}. */
-type CatalogOriginPriceStatsQuery = NonNullable<paths["/v1/catalog/origin-price-stats"]["get"]["parameters"]["query"]>;
-/** Query parameters for {@link ParchmentClient.catalog.similar}. */
-type CatalogSimilarQuery = NonNullable<paths["/v1/catalog/{id}/similar"]["get"]["parameters"]["query"]>;
-/** Query parameters for {@link ParchmentClient.priceIndex.list}. */
-type PriceIndexQuery = NonNullable<paths["/v1/price-index"]["get"]["parameters"]["query"]>;
-/** Query parameters for {@link ParchmentClient.procurement.briefs.matches}. */
-type BriefMatchesQuery = NonNullable<paths["/v1/procurement/briefs/{id}/matches"]["get"]["parameters"]["query"]>;
-/** Request body for {@link ParchmentClient.procurement.briefs.create}. */
-type SourcingBriefCreateRequest = components["schemas"]["SourcingBriefCreateRequest"];
-/**
- * Create a typed Parchment API client.
- *
- * The generated core (openapi-fetch over the generated `paths` types) is the
- * contract truth; the named helpers below are the hand-maintained ergonomic
- * layer and grow as endpoints land. `raw` always exposes the underlying typed
- * client for direct path access to anything not yet wrapped.
- */
-declare function createParchmentClient(options: ParchmentClientOptions): {
-    /** The underlying typed openapi-fetch client for direct path access. */
-    raw: openapi_fetch.Client<paths, `${string}/${string}`>;
-    /** Liveness and service identity. */
-    health: () => Promise<openapi_fetch.FetchResponse<{
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            200: {
-                headers: {
-                    [name: string]: unknown;
+            requestBody?: never;
+            responses: {
+                201: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ApiKeyCreateResponse"];
+                    };
                 };
-                content: {
-                    "application/json": components["schemas"]["HealthResponse"];
+                400: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
-            };
-        };
-    }, openapi_fetch.FetchOptions<{
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            200: {
-                headers: {
-                    [name: string]: unknown;
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
-                content: {
-                    "application/json": components["schemas"]["HealthResponse"];
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
-            };
-        };
-    }> | undefined, `${string}/${string}`>>;
-    /** Resolved principal and entitlements for the caller. */
-    me: () => Promise<openapi_fetch.FetchResponse<{
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            200: {
-                headers: {
-                    [name: string]: unknown;
+                404: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
-                content: {
-                    "application/json": components["schemas"]["MeResponse"];
+                503: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
                 };
             };
-        };
-    }, openapi_fetch.FetchOptions<{
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        requestBody?: never;
-        responses: {
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": components["schemas"]["MeResponse"];
+        }, {
+            params: {
+                path: {
+                    id: string;
                 };
             };
-        };
-    }> | undefined, `${string}/${string}`>>;
+        }, `${string}/${string}`>>;
+    };
     catalog: {
         /** Catalog capabilities and visibility for the caller. */
         access: () => Promise<openapi_fetch.FetchResponse<{
             parameters: {
                 query?: never;
-                header? /** Catalog capabilities and visibility for the caller. */: never;
+                header?: never;
                 path?: never;
                 cookie?: never;
             };
@@ -1808,7 +2479,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"] /** Live catalog price context by origin. */["ErrorResponse"];
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
                 403: {
@@ -1823,7 +2494,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
         }, openapi_fetch.FetchOptions<{
             parameters: {
                 query?: never;
-                header? /** Catalog capabilities and visibility for the caller. */: never;
+                header?: never;
                 path?: never;
                 cookie?: never;
             };
@@ -1842,7 +2513,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                         [name: string]: unknown;
                     };
                     content: {
-                        "application/json": components["schemas"] /** Live catalog price context by origin. */["ErrorResponse"];
+                        "application/json": components["schemas"]["ErrorResponse"];
                     };
                 };
                 403: {