@purveyors/sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -141,6 +141,24 @@ interface paths {
                         "application/json": components["schemas"]["CatalogAccessResponse"];
                     };
                 };
+                /** @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;
@@ -160,7 +178,7 @@ interface paths {
         };
         /**
          * 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.
+         * @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: {
@@ -170,8 +188,40 @@ interface paths {
                     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;
                 };
-                header?: never;
                 path?: never;
                 cookie?: never;
             };
@@ -186,6 +236,175 @@ interface paths {
                         "application/json": components["schemas"]["CatalogListResponse"];
                     };
                 };
+                /** @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;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/catalog/facets": {
+        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: {
+            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;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Access-aware catalog filter metadata */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CatalogFacetsResponse"];
+                    };
+                };
+                /** @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;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/catalog/origin-price-stats": {
+        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: {
+            parameters: {
+                query?: {
+                    showWholesale?: "true" | "false";
+                    wholesaleOnly?: "true" | "false";
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                /** @description Per-origin price context for caller-visible catalog rows */
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CatalogOriginPriceStatsResponse"];
+                    };
+                };
+                /** @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;
@@ -225,6 +444,24 @@ interface paths {
                         "application/json": components["schemas"]["CatalogProofCoverageResponse"];
                     };
                 };
+                /** @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;
@@ -697,6 +934,12 @@ interface components {
                 canExport: boolean;
             };
         };
+        ErrorResponse: {
+            error: {
+                code: string;
+                message: string;
+            };
+        };
         CatalogItem: {
             id: number;
             name?: string | null;
@@ -712,9 +955,41 @@ interface components {
             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"][];
@@ -743,10 +1018,174 @@ interface components {
                 };
                 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: {
@@ -866,12 +1305,6 @@ interface components {
                 };
             };
         };
-        ErrorResponse: {
-            error: {
-                code: string;
-                message: string;
-            };
-        };
         CatalogSimilarityTarget: {
             id: number;
             name: string;
@@ -1243,6 +1676,19 @@ interface ParchmentClientOptions {
 }
 /** 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}. */
@@ -1343,7 +1789,7 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
         access: () => Promise<openapi_fetch.FetchResponse<{
             parameters: {
                 query?: never;
-                header?: never;
+                header? /** Catalog capabilities and visibility for the caller. */: never;
                 path?: never;
                 cookie?: never;
             };
@@ -1357,11 +1803,27 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                         "application/json": components["schemas"]["CatalogAccessResponse"];
                     };
                 };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"] /** Live catalog price context by origin. */["ErrorResponse"];
+                    };
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
             };
         }, openapi_fetch.FetchOptions<{
             parameters: {
                 query?: never;
-                header?: never;
+                header? /** Catalog capabilities and visibility for the caller. */: never;
                 path?: never;
                 cookie?: never;
             };
@@ -1375,10 +1837,29 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                         "application/json": components["schemas"]["CatalogAccessResponse"];
                     };
                 };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"] /** Live catalog price context by origin. */["ErrorResponse"];
+                    };
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
             };
         }> | undefined, `${string}/${string}`>>;
-        /** List public catalog coffees (paginated). */
-        list: (query?: CatalogListQuery) => Promise<openapi_fetch.FetchResponse<{
+        /**
+         * List public catalog coffees (paginated). Pass `headers` to send the
+         * `Prefer: handling=lenient|strict` override (see {@link CatalogListHeaders}).
+         */
+        list: (query?: CatalogListQuery, headers?: CatalogListHeaders) => Promise<openapi_fetch.FetchResponse<{
             parameters: {
                 query?: {
                     page?: number;
@@ -1386,8 +1867,40 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                     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;
                 };
-                header?: never;
                 path?: never;
                 cookie?: never;
             };
@@ -1401,6 +1914,22 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                         "application/json": components["schemas"]["CatalogListResponse"];
                     };
                 };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
             };
         }, {
             params: {
@@ -1410,6 +1939,197 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                     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;
+                } | undefined;
+                header: {
+                    Prefer?: string;
+                } | undefined;
+            };
+        }, `${string}/${string}`>>;
+        /**
+         * Catalog filter metadata and counted facets. Pass `headers` to send the
+         * `Prefer: handling=lenient|strict` override (see {@link CatalogFacetsHeaders}).
+         */
+        facets: (query?: CatalogFacetsQuery, headers?: CatalogFacetsHeaders) => Promise<openapi_fetch.FetchResponse<{
+            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;
+                };
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CatalogFacetsResponse"];
+                    };
+                };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        }, {
+            params: {
+                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;
+                } | undefined;
+                header: {
+                    Prefer?: string;
+                } | undefined;
+            };
+        }, `${string}/${string}`>>;
+        /** Live catalog price context by origin. */
+        originPriceStats: (query?: CatalogOriginPriceStatsQuery) => Promise<openapi_fetch.FetchResponse<{
+            parameters: {
+                query?: {
+                    showWholesale?: "true" | "false";
+                    wholesaleOnly?: "true" | "false";
+                };
+                header?: never;
+                path?: never;
+                cookie?: never;
+            };
+            requestBody?: never;
+            responses: {
+                200: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["CatalogOriginPriceStatsResponse"];
+                    };
+                };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+            };
+        }, {
+            params: {
+                query: {
+                    showWholesale?: "true" | "false";
+                    wholesaleOnly?: "true" | "false";
                 } | undefined;
             };
         }, `${string}/${string}`>>;
@@ -1431,6 +2151,22 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                         "application/json": components["schemas"]["CatalogProofCoverageResponse"];
                     };
                 };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
             };
         }, openapi_fetch.FetchOptions<{
             parameters: {
@@ -1449,6 +2185,22 @@ declare function createParchmentClient(options: ParchmentClientOptions): {
                         "application/json": components["schemas"]["CatalogProofCoverageResponse"];
                     };
                 };
+                401: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
+                403: {
+                    headers: {
+                        [name: string]: unknown;
+                    };
+                    content: {
+                        "application/json": components["schemas"]["ErrorResponse"];
+                    };
+                };
             };
         }> | undefined, `${string}/${string}`>>;
         /** Find catalog coffees similar to a target coffee. */

package/dist/index.js

@@ -17,8 +17,20 @@ function createParchmentClient(options) {
     catalog: {
       /** Catalog capabilities and visibility for the caller. */
       access: () => client.GET("/v1/catalog/access"),
-      /** List public catalog coffees (paginated). */
-      list: (query) => client.GET("/v1/catalog", { params: { query } }),
+      /**
+       * List public catalog coffees (paginated). Pass `headers` to send the
+       * `Prefer: handling=lenient|strict` override (see {@link CatalogListHeaders}).
+       */
+      list: (query, headers) => client.GET("/v1/catalog", { params: { query, header: headers } }),
+      /**
+       * Catalog filter metadata and counted facets. Pass `headers` to send the
+       * `Prefer: handling=lenient|strict` override (see {@link CatalogFacetsHeaders}).
+       */
+      facets: (query, headers) => client.GET("/v1/catalog/facets", {
+        params: { query, header: headers }
+      }),
+      /** Live catalog price context by origin. */
+      originPriceStats: (query) => client.GET("/v1/catalog/origin-price-stats", { params: { query } }),
       /** Aggregate proof-coverage over the public catalog. */
       proofCoverage: () => client.GET("/v1/catalog/proof-coverage"),
       /** Find catalog coffees similar to a target coffee. */

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import createClient, { type ClientOptions } from \"openapi-fetch\";\nimport type { components, paths } from \"./schema\";\n\nexport interface ParchmentClientOptions {\n  /** Base URL of the Parchment API, e.g. https://api.purveyors.io */\n  baseUrl: string;\n  /**\n   * Optional bearer token (a Supabase JWT or, later, an API key). Sent as\n   * `Authorization: Bearer <token>`. Auth is resolved server-side against the\n   * unified principal model; the SDK only forwards the credential.\n   */\n  token?: string;\n  /** Override the fetch implementation (useful for tests or custom runtimes). */\n  fetch?: ClientOptions[\"fetch\"];\n}\n\n/** Query parameters for {@link ParchmentClient.catalog.list}. */\nexport type CatalogListQuery = NonNullable<\n  paths[\"/v1/catalog\"][\"get\"][\"parameters\"][\"query\"]\n>;\n/** Query parameters for {@link ParchmentClient.catalog.similar}. */\nexport type CatalogSimilarQuery = NonNullable<\n  paths[\"/v1/catalog/{id}/similar\"][\"get\"][\"parameters\"][\"query\"]\n>;\n/** Query parameters for {@link ParchmentClient.priceIndex.list}. */\nexport type PriceIndexQuery = NonNullable<\n  paths[\"/v1/price-index\"][\"get\"][\"parameters\"][\"query\"]\n>;\n/** Query parameters for {@link ParchmentClient.procurement.briefs.matches}. */\nexport type BriefMatchesQuery = NonNullable<\n  paths[\"/v1/procurement/briefs/{id}/matches\"][\"get\"][\"parameters\"][\"query\"]\n>;\n/** Request body for {@link ParchmentClient.procurement.briefs.create}. */\nexport type SourcingBriefCreateRequest =\n  components[\"schemas\"][\"SourcingBriefCreateRequest\"];\n\n/**\n * Create a typed Parchment API client.\n *\n * The generated core (openapi-fetch over the generated `paths` types) is the\n * contract truth; the named helpers below are the hand-maintained ergonomic\n * layer and grow as endpoints land. `raw` always exposes the underlying typed\n * client for direct path access to anything not yet wrapped.\n */\nexport function createParchmentClient(options: ParchmentClientOptions) {\n  const { baseUrl, token, fetch: fetchImpl } = options;\n\n  const client = createClient<paths>({\n    baseUrl,\n    fetch: fetchImpl,\n    headers: token ? { Authorization: `Bearer ${token}` } : undefined,\n  });\n\n  return {\n    /** The underlying typed openapi-fetch client for direct path access. */\n    raw: client,\n    /** Liveness and service identity. */\n    health: () => client.GET(\"/health\"),\n    /** Resolved principal and entitlements for the caller. */\n    me: () => client.GET(\"/v1/me\"),\n    catalog: {\n      /** Catalog capabilities and visibility for the caller. */\n      access: () => client.GET(\"/v1/catalog/access\"),\n      /** List public catalog coffees (paginated). */\n      list: (query?: CatalogListQuery) =>\n        client.GET(\"/v1/catalog\", { params: { query } }),\n      /** Aggregate proof-coverage over the public catalog. */\n      proofCoverage: () => client.GET(\"/v1/catalog/proof-coverage\"),\n      /** Find catalog coffees similar to a target coffee. */\n      similar: (id: string, query?: CatalogSimilarQuery) =>\n        client.GET(\"/v1/catalog/{id}/similar\", {\n          params: { path: { id }, query },\n        }),\n    },\n    priceIndex: {\n      /** Parchment Price Index (aggregate snapshots). */\n      list: (query?: PriceIndexQuery) =>\n        client.GET(\"/v1/price-index\", { params: { query } }),\n    },\n    procurement: {\n      briefs: {\n        /** List the caller's saved sourcing briefs. */\n        list: () => client.GET(\"/v1/procurement/briefs\"),\n        /** Create a saved sourcing brief. */\n        create: (body: SourcingBriefCreateRequest) =>\n          client.POST(\"/v1/procurement/briefs\", { body }),\n        /** Fetch one of the caller's sourcing briefs by id. */\n        get: (id: string) =>\n          client.GET(\"/v1/procurement/briefs/{id}\", {\n            params: { path: { id } },\n          }),\n        /** Run a saved brief against the catalog (paginated matches). */\n        matches: (id: string, query?: BriefMatchesQuery) =>\n          client.GET(\"/v1/procurement/briefs/{id}/matches\", {\n            params: { path: { id }, query },\n          }),\n      },\n    },\n  };\n}\n\nexport type ParchmentClient = ReturnType<typeof createParchmentClient>;\n"],"mappings":";AAAA,OAAO,kBAA0C;AA4C1C,SAAS,sBAAsB,SAAiC;AACrE,QAAM,EAAE,SAAS,OAAO,OAAO,UAAU,IAAI;AAE7C,QAAM,SAAS,aAAoB;AAAA,IACjC;AAAA,IACA,OAAO;AAAA,IACP,SAAS,QAAQ,EAAE,eAAe,UAAU,KAAK,GAAG,IAAI;AAAA,EAC1D,CAAC;AAED,SAAO;AAAA;AAAA,IAEL,KAAK;AAAA;AAAA,IAEL,QAAQ,MAAM,OAAO,IAAI,SAAS;AAAA;AAAA,IAElC,IAAI,MAAM,OAAO,IAAI,QAAQ;AAAA,IAC7B,SAAS;AAAA;AAAA,MAEP,QAAQ,MAAM,OAAO,IAAI,oBAAoB;AAAA;AAAA,MAE7C,MAAM,CAAC,UACL,OAAO,IAAI,eAAe,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAAA;AAAA,MAEjD,eAAe,MAAM,OAAO,IAAI,4BAA4B;AAAA;AAAA,MAE5D,SAAS,CAAC,IAAY,UACpB,OAAO,IAAI,4BAA4B;AAAA,QACrC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAG,MAAM;AAAA,MAChC,CAAC;AAAA,IACL;AAAA,IACA,YAAY;AAAA;AAAA,MAEV,MAAM,CAAC,UACL,OAAO,IAAI,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAAA,IACvD;AAAA,IACA,aAAa;AAAA,MACX,QAAQ;AAAA;AAAA,QAEN,MAAM,MAAM,OAAO,IAAI,wBAAwB;AAAA;AAAA,QAE/C,QAAQ,CAAC,SACP,OAAO,KAAK,0BAA0B,EAAE,KAAK,CAAC;AAAA;AAAA,QAEhD,KAAK,CAAC,OACJ,OAAO,IAAI,+BAA+B;AAAA,UACxC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE;AAAA,QACzB,CAAC;AAAA;AAAA,QAEH,SAAS,CAAC,IAAY,UACpB,OAAO,IAAI,uCAAuC;AAAA,UAChD,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAG,MAAM;AAAA,QAChC,CAAC;AAAA,MACL;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/client.ts"],"sourcesContent":["import createClient, { type ClientOptions } from \"openapi-fetch\";\nimport type { components, paths } from \"./schema\";\n\nexport interface ParchmentClientOptions {\n  /** Base URL of the Parchment API, e.g. https://api.purveyors.io */\n  baseUrl: string;\n  /**\n   * Optional bearer token (a Supabase JWT or, later, an API key). Sent as\n   * `Authorization: Bearer <token>`. Auth is resolved server-side against the\n   * unified principal model; the SDK only forwards the credential.\n   */\n  token?: string;\n  /** Override the fetch implementation (useful for tests or custom runtimes). */\n  fetch?: ClientOptions[\"fetch\"];\n}\n\n/** Query parameters for {@link ParchmentClient.catalog.list}. */\nexport type CatalogListQuery = NonNullable<\n  paths[\"/v1/catalog\"][\"get\"][\"parameters\"][\"query\"]\n>;\n/** Query parameters for {@link ParchmentClient.catalog.facets}. */\nexport type CatalogFacetsQuery = NonNullable<\n  paths[\"/v1/catalog/facets\"][\"get\"][\"parameters\"][\"query\"]\n>;\n/**\n * Optional headers for {@link ParchmentClient.catalog.list}, notably the\n * RFC 7240 `Prefer: handling=lenient|strict` override (PADR-0013 §7). Sending\n * `handling=lenient` opts a strict caller (API key or bearer-session JWT) back\n * into strip-with-notice degradation instead of a 401/403 hard-deny.\n */\nexport type CatalogListHeaders = NonNullable<\n  paths[\"/v1/catalog\"][\"get\"][\"parameters\"][\"header\"]\n>;\n/** Optional headers for {@link ParchmentClient.catalog.facets}; see {@link CatalogListHeaders}. */\nexport type CatalogFacetsHeaders = NonNullable<\n  paths[\"/v1/catalog/facets\"][\"get\"][\"parameters\"][\"header\"]\n>;\n/** Query parameters for {@link ParchmentClient.catalog.originPriceStats}. */\nexport type CatalogOriginPriceStatsQuery = NonNullable<\n  paths[\"/v1/catalog/origin-price-stats\"][\"get\"][\"parameters\"][\"query\"]\n>;\n/** Query parameters for {@link ParchmentClient.catalog.similar}. */\nexport type CatalogSimilarQuery = NonNullable<\n  paths[\"/v1/catalog/{id}/similar\"][\"get\"][\"parameters\"][\"query\"]\n>;\n/** Query parameters for {@link ParchmentClient.priceIndex.list}. */\nexport type PriceIndexQuery = NonNullable<\n  paths[\"/v1/price-index\"][\"get\"][\"parameters\"][\"query\"]\n>;\n/** Query parameters for {@link ParchmentClient.procurement.briefs.matches}. */\nexport type BriefMatchesQuery = NonNullable<\n  paths[\"/v1/procurement/briefs/{id}/matches\"][\"get\"][\"parameters\"][\"query\"]\n>;\n/** Request body for {@link ParchmentClient.procurement.briefs.create}. */\nexport type SourcingBriefCreateRequest =\n  components[\"schemas\"][\"SourcingBriefCreateRequest\"];\n\n/**\n * Create a typed Parchment API client.\n *\n * The generated core (openapi-fetch over the generated `paths` types) is the\n * contract truth; the named helpers below are the hand-maintained ergonomic\n * layer and grow as endpoints land. `raw` always exposes the underlying typed\n * client for direct path access to anything not yet wrapped.\n */\nexport function createParchmentClient(options: ParchmentClientOptions) {\n  const { baseUrl, token, fetch: fetchImpl } = options;\n\n  const client = createClient<paths>({\n    baseUrl,\n    fetch: fetchImpl,\n    headers: token ? { Authorization: `Bearer ${token}` } : undefined,\n  });\n\n  return {\n    /** The underlying typed openapi-fetch client for direct path access. */\n    raw: client,\n    /** Liveness and service identity. */\n    health: () => client.GET(\"/health\"),\n    /** Resolved principal and entitlements for the caller. */\n    me: () => client.GET(\"/v1/me\"),\n    catalog: {\n      /** Catalog capabilities and visibility for the caller. */\n      access: () => client.GET(\"/v1/catalog/access\"),\n      /**\n       * List public catalog coffees (paginated). Pass `headers` to send the\n       * `Prefer: handling=lenient|strict` override (see {@link CatalogListHeaders}).\n       */\n      list: (query?: CatalogListQuery, headers?: CatalogListHeaders) =>\n        client.GET(\"/v1/catalog\", { params: { query, header: headers } }),\n      /**\n       * Catalog filter metadata and counted facets. Pass `headers` to send the\n       * `Prefer: handling=lenient|strict` override (see {@link CatalogFacetsHeaders}).\n       */\n      facets: (query?: CatalogFacetsQuery, headers?: CatalogFacetsHeaders) =>\n        client.GET(\"/v1/catalog/facets\", {\n          params: { query, header: headers },\n        }),\n      /** Live catalog price context by origin. */\n      originPriceStats: (query?: CatalogOriginPriceStatsQuery) =>\n        client.GET(\"/v1/catalog/origin-price-stats\", { params: { query } }),\n      /** Aggregate proof-coverage over the public catalog. */\n      proofCoverage: () => client.GET(\"/v1/catalog/proof-coverage\"),\n      /** Find catalog coffees similar to a target coffee. */\n      similar: (id: string, query?: CatalogSimilarQuery) =>\n        client.GET(\"/v1/catalog/{id}/similar\", {\n          params: { path: { id }, query },\n        }),\n    },\n    priceIndex: {\n      /** Parchment Price Index (aggregate snapshots). */\n      list: (query?: PriceIndexQuery) =>\n        client.GET(\"/v1/price-index\", { params: { query } }),\n    },\n    procurement: {\n      briefs: {\n        /** List the caller's saved sourcing briefs. */\n        list: () => client.GET(\"/v1/procurement/briefs\"),\n        /** Create a saved sourcing brief. */\n        create: (body: SourcingBriefCreateRequest) =>\n          client.POST(\"/v1/procurement/briefs\", { body }),\n        /** Fetch one of the caller's sourcing briefs by id. */\n        get: (id: string) =>\n          client.GET(\"/v1/procurement/briefs/{id}\", {\n            params: { path: { id } },\n          }),\n        /** Run a saved brief against the catalog (paginated matches). */\n        matches: (id: string, query?: BriefMatchesQuery) =>\n          client.GET(\"/v1/procurement/briefs/{id}/matches\", {\n            params: { path: { id }, query },\n          }),\n      },\n    },\n  };\n}\n\nexport type ParchmentClient = ReturnType<typeof createParchmentClient>;\n"],"mappings":";AAAA,OAAO,kBAA0C;AAiE1C,SAAS,sBAAsB,SAAiC;AACrE,QAAM,EAAE,SAAS,OAAO,OAAO,UAAU,IAAI;AAE7C,QAAM,SAAS,aAAoB;AAAA,IACjC;AAAA,IACA,OAAO;AAAA,IACP,SAAS,QAAQ,EAAE,eAAe,UAAU,KAAK,GAAG,IAAI;AAAA,EAC1D,CAAC;AAED,SAAO;AAAA;AAAA,IAEL,KAAK;AAAA;AAAA,IAEL,QAAQ,MAAM,OAAO,IAAI,SAAS;AAAA;AAAA,IAElC,IAAI,MAAM,OAAO,IAAI,QAAQ;AAAA,IAC7B,SAAS;AAAA;AAAA,MAEP,QAAQ,MAAM,OAAO,IAAI,oBAAoB;AAAA;AAAA;AAAA;AAAA;AAAA,MAK7C,MAAM,CAAC,OAA0B,YAC/B,OAAO,IAAI,eAAe,EAAE,QAAQ,EAAE,OAAO,QAAQ,QAAQ,EAAE,CAAC;AAAA;AAAA;AAAA;AAAA;AAAA,MAKlE,QAAQ,CAAC,OAA4B,YACnC,OAAO,IAAI,sBAAsB;AAAA,QAC/B,QAAQ,EAAE,OAAO,QAAQ,QAAQ;AAAA,MACnC,CAAC;AAAA;AAAA,MAEH,kBAAkB,CAAC,UACjB,OAAO,IAAI,kCAAkC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAAA;AAAA,MAEpE,eAAe,MAAM,OAAO,IAAI,4BAA4B;AAAA;AAAA,MAE5D,SAAS,CAAC,IAAY,UACpB,OAAO,IAAI,4BAA4B;AAAA,QACrC,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAG,MAAM;AAAA,MAChC,CAAC;AAAA,IACL;AAAA,IACA,YAAY;AAAA;AAAA,MAEV,MAAM,CAAC,UACL,OAAO,IAAI,mBAAmB,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;AAAA,IACvD;AAAA,IACA,aAAa;AAAA,MACX,QAAQ;AAAA;AAAA,QAEN,MAAM,MAAM,OAAO,IAAI,wBAAwB;AAAA;AAAA,QAE/C,QAAQ,CAAC,SACP,OAAO,KAAK,0BAA0B,EAAE,KAAK,CAAC;AAAA;AAAA,QAEhD,KAAK,CAAC,OACJ,OAAO,IAAI,+BAA+B;AAAA,UACxC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE;AAAA,QACzB,CAAC;AAAA;AAAA,QAEH,SAAS,CAAC,IAAY,UACpB,OAAO,IAAI,uCAAuC;AAAA,UAChD,QAAQ,EAAE,MAAM,EAAE,GAAG,GAAG,MAAM;AAAA,QAChC,CAAC;AAAA,MACL;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purveyors/sdk",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Typed client for the Purveyors Parchment API, generated from its OpenAPI spec.",
   "license": "MIT",
   "type": "module",