@purveyors/cli 0.15.1 → 0.20.0

package/dist/lib/catalog.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { AuthError, PrvrsError } from './errors.js';
 // ─── Zod schemas ──────────────────────────────────────────────────────────────
 export const catalogSortFields = ['price', 'price-desc', 'name', 'origin', 'newest'];
 export const searchCatalogSchema = z.object({
@@ -17,11 +18,122 @@ export const searchCatalogSchema = z.object({
     variety: z.string().optional(),
     dryingMethod: z.string().optional(),
     stockedDays: z.number().int().positive().optional(),
+    processingBaseMethod: z.string().optional(),
+    fermentationType: z.string().optional(),
+    processAdditive: z.string().optional(),
+    processingDisclosureLevel: z.string().optional(),
+    processingConfidenceMin: z.number().min(0).max(1).optional(),
+    includeProof: z.boolean().optional(),
 });
 export const getCatalogSchema = z.object({
     id: z.number().int().positive(),
+    includeProof: z.boolean().optional(),
 });
 export const getCatalogStatsSchema = z.object({});
+const CATALOG_INTELLIGENCE_MAX_SAMPLE_SIZE = 5000;
+const CATALOG_PREMIUM_DEFAULT_SAMPLE_SIZE = 250;
+const SUPABASE_DATA_API_MAX_PAGE_SIZE = 1000;
+const SUPPLIER_AGGREGATE_DEFAULT_SAMPLE_SIZE = CATALOG_INTELLIGENCE_MAX_SAMPLE_SIZE;
+export const catalogRankPremiumSchema = z.object({
+    origin: z.string().optional(),
+    process: z.string().optional(),
+    supplier: z.string().optional(),
+    stocked: z.boolean().optional(),
+    priceMax: z.number().optional(),
+    minScore: z.number().optional(),
+    includeUnscored: z.boolean().default(false).optional(),
+    limit: z.number().int().min(1).max(50).default(10).optional(),
+    sampleSize: z
+        .number()
+        .int()
+        .min(1)
+        .max(CATALOG_INTELLIGENCE_MAX_SAMPLE_SIZE)
+        .default(CATALOG_PREMIUM_DEFAULT_SAMPLE_SIZE)
+        .optional(),
+});
+export const supplierAggregateSchema = z.object({
+    supplier: z.string().optional(),
+    stocked: z.boolean().optional(),
+    minCoffees: z.number().int().min(1).default(1).optional(),
+    topCoffees: z.number().int().min(1).max(25).default(5).optional(),
+    limit: z.number().int().min(1).max(100).default(25).optional(),
+    sampleSize: z
+        .number()
+        .int()
+        .min(1)
+        .max(CATALOG_INTELLIGENCE_MAX_SAMPLE_SIZE)
+        .default(SUPPLIER_AGGREGATE_DEFAULT_SAMPLE_SIZE)
+        .optional(),
+});
+export const catalogFacetFields = [
+    'supplier',
+    'country',
+    'processing_base_method',
+    'fermentation_type',
+    'drying_method',
+    'grade',
+    'wholesale',
+];
+export const catalogFacetsSchema = z.object({
+    field: z.enum(catalogFacetFields),
+    stockedOnly: z.boolean().default(true).optional(),
+    limit: z.number().int().min(1).max(100).default(60).optional(),
+    sampleSize: z
+        .number()
+        .int()
+        .min(1)
+        .max(CATALOG_INTELLIGENCE_MAX_SAMPLE_SIZE)
+        .default(SUPPLIER_AGGREGATE_DEFAULT_SAMPLE_SIZE)
+        .optional(),
+});
+export const catalogRankObjectives = ['premium', 'value', 'fresh_arrival', 'rare_origin'];
+export const catalogRankSchema = z.object({
+    objective: z.enum(catalogRankObjectives).default('premium').optional(),
+    stockedOnly: z.boolean().default(true).optional(),
+    supplier: z.string().optional(),
+    country: z.string().optional(),
+    process: z.string().optional(),
+    priceMax: z.number().optional(),
+    minScore: z.number().optional(),
+    nonWholesaleOnly: z.boolean().default(false).optional(),
+    limit: z.number().int().min(1).max(50).default(10).optional(),
+    sampleSize: z
+        .number()
+        .int()
+        .min(1)
+        .max(CATALOG_INTELLIGENCE_MAX_SAMPLE_SIZE)
+        .default(SUPPLIER_AGGREGATE_DEFAULT_SAMPLE_SIZE)
+        .optional(),
+});
+export const catalogSimilarityModes = ['all', 'likely_same', 'similar_profile'];
+export const getCatalogSimilaritySchema = z.object({
+    coffee_id: z
+        .number()
+        .int()
+        .positive()
+        .describe('The coffee_catalog ID to request canonical similarity for'),
+    threshold: z
+        .number()
+        .min(0.5)
+        .max(0.99)
+        .default(0.7)
+        .optional()
+        .describe('Minimum canonical similarity threshold (0.5-0.99)'),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(25)
+        .default(10)
+        .optional()
+        .describe('Maximum canonical similarity results to request'),
+    stockedOnly: z
+        .boolean()
+        .default(false)
+        .optional()
+        .describe('Restrict similarity results to currently stocked coffees'),
+    mode: z.enum(catalogSimilarityModes).default('all').optional().describe('Canonical group filter'),
+});
 export const findSimilarBeansSchema = z.object({
     coffee_id: z
         .number()
@@ -57,6 +169,377 @@ export function sanitizeFilterValue(value) {
 function getPerLbPrice(item) {
     return item.price_tiers?.[0]?.price ?? item.price_per_lb ?? item.cost_lb ?? null;
 }
+function round(value, places = 2) {
+    const multiplier = 10 ** places;
+    return Math.round(value * multiplier) / multiplier;
+}
+function average(values) {
+    if (values.length === 0)
+        return null;
+    return round(values.reduce((sum, value) => sum + value, 0) / values.length);
+}
+function uniqueSorted(values, limit = 10) {
+    return [
+        ...new Set(values.map((value) => value?.trim()).filter((value) => Boolean(value))),
+    ]
+        .sort((a, b) => a.localeCompare(b))
+        .slice(0, limit);
+}
+export function summarizePurveyorScore(scoreValueOrItem) {
+    const item = typeof scoreValueOrItem === 'object' && scoreValueOrItem !== null
+        ? scoreValueOrItem
+        : undefined;
+    const value = item
+        ? (item.purveyor_score ?? null)
+        : typeof scoreValueOrItem === 'number'
+            ? scoreValueOrItem
+            : null;
+    const base = {
+        source: 'purveyor_score',
+        confidence: item?.purveyor_score_confidence ?? null,
+        tier: item?.purveyor_score_tier ?? null,
+        factors: item?.purveyor_score_factors ?? null,
+        version: item?.purveyor_score_version ?? null,
+        updated_at: item?.purveyor_score_updated_at ?? null,
+    };
+    if (value === null) {
+        return {
+            value: null,
+            band: 'unscored',
+            ...base,
+            note: 'No Purveyor Score is available on this catalog row.',
+        };
+    }
+    if (value >= 90) {
+        return {
+            value,
+            band: 'premium',
+            ...base,
+            note: 'High Purveyor Score; inspect confidence and factor breakdown before treating it as a premium catalog candidate.',
+        };
+    }
+    if (value >= 85) {
+        return {
+            value,
+            band: 'strong',
+            ...base,
+            note: 'Strong Purveyor Score; compare confidence, factor breakdown, price, provenance, and fit before selecting.',
+        };
+    }
+    return {
+        value,
+        band: 'scored',
+        ...base,
+        note: 'Purveyor Score is available; ranking still depends on confidence, factor breakdown, and sourcing context.',
+    };
+}
+function getPurveyorScoreValue(item) {
+    return item.purveyor_score ?? null;
+}
+function buildRankSignals(item) {
+    const signals = [];
+    const score = summarizePurveyorScore(item);
+    if (score.value !== null)
+        signals.push(`purveyor_score=${score.value}`);
+    if (score.confidence !== null)
+        signals.push(`purveyor_score_confidence=${score.confidence}`);
+    if (score.tier)
+        signals.push(`purveyor_score_tier=${score.tier}`);
+    const price = getPerLbPrice(item);
+    if (price !== null)
+        signals.push(`price_per_lb=${price}`);
+    if (item.stocked === true)
+        signals.push('currently_stocked');
+    if (item.country)
+        signals.push(`origin=${item.country}`);
+    if (item.processing_base_method ?? item.processing) {
+        signals.push(`process=${item.processing_base_method ?? item.processing}`);
+    }
+    return signals;
+}
+function toPremiumRankedItem(item, rank) {
+    return {
+        rank,
+        id: item.id,
+        name: item.name,
+        supplier: item.source,
+        origin: {
+            continent: item.continent,
+            country: item.country,
+            region: item.region,
+        },
+        processing: {
+            label: item.processing,
+            base_method: item.processing_base_method,
+            fermentation_type: item.fermentation_type,
+            drying_method: item.drying_method,
+        },
+        purveyor_score: summarizePurveyorScore(item),
+        pricing: {
+            price_per_lb: item.price_per_lb,
+            cost_lb: item.cost_lb,
+            price_tiers: item.price_tiers,
+        },
+        stocked: item.stocked,
+        stocked_date: item.stocked_date,
+        signals: buildRankSignals(item),
+    };
+}
+export function computeCatalogPremiumRanking(items, opts = {}) {
+    const limit = opts.limit ?? 10;
+    const includeUnscored = opts.includeUnscored ?? false;
+    const minScore = opts.minScore;
+    return items
+        .filter((item) => includeUnscored || getPurveyorScoreValue(item) !== null)
+        .filter((item) => minScore === undefined || (getPurveyorScoreValue(item) ?? -Infinity) >= minScore)
+        .sort((a, b) => {
+        const scoreDelta = (getPurveyorScoreValue(b) ?? -Infinity) - (getPurveyorScoreValue(a) ?? -Infinity);
+        if (scoreDelta !== 0)
+            return scoreDelta;
+        const aPrice = getPerLbPrice(a) ?? Infinity;
+        const bPrice = getPerLbPrice(b) ?? Infinity;
+        if (aPrice !== bPrice)
+            return aPrice - bPrice;
+        return (a.name ?? '').localeCompare(b.name ?? '');
+    })
+        .slice(0, limit)
+        .map((item, index) => toPremiumRankedItem(item, index + 1));
+}
+export function computeSupplierAggregates(items, opts = {}) {
+    const bySupplier = new Map();
+    for (const item of items) {
+        const supplier = item.source?.trim() || 'Unknown supplier';
+        const group = bySupplier.get(supplier) ?? [];
+        group.push(item);
+        bySupplier.set(supplier, group);
+    }
+    const topCoffees = opts.topCoffees ?? 5;
+    const minCoffees = opts.minCoffees ?? 1;
+    return [...bySupplier.entries()]
+        .map(([supplier, supplierItems]) => {
+        const scores = supplierItems
+            .map((item) => getPurveyorScoreValue(item))
+            .filter((score) => score !== null);
+        const confidences = supplierItems
+            .map((item) => item.purveyor_score_confidence)
+            .filter((confidence) => confidence !== null);
+        const prices = supplierItems
+            .map((item) => getPerLbPrice(item))
+            .filter((p) => p !== null);
+        return {
+            supplier,
+            total: supplierItems.length,
+            stocked: supplierItems.filter((item) => item.stocked === true).length,
+            score: {
+                average: average(scores),
+                coverage: supplierItems.length === 0 ? 0 : round(scores.length / supplierItems.length, 3),
+                scored_count: scores.length,
+                top_score: scores.length > 0 ? Math.max(...scores) : null,
+                average_confidence: average(confidences),
+                confidence_coverage: supplierItems.length === 0 ? 0 : round(confidences.length / supplierItems.length, 3),
+            },
+            price: {
+                average_per_lb: average(prices),
+                min_per_lb: prices.length > 0 ? Math.min(...prices) : null,
+                max_per_lb: prices.length > 0 ? Math.max(...prices) : null,
+            },
+            origins: uniqueSorted(supplierItems.flatMap((item) => [item.country, item.continent])),
+            processing_methods: uniqueSorted(supplierItems.map((item) => item.processing_base_method ?? item.processing)),
+            top_coffees: computeCatalogPremiumRanking(supplierItems, {
+                limit: topCoffees,
+                includeUnscored: true,
+            }),
+        };
+    })
+        .filter((supplier) => supplier.total >= minCoffees)
+        .sort((a, b) => {
+        const scoreDelta = (b.score.average ?? -Infinity) - (a.score.average ?? -Infinity);
+        if (scoreDelta !== 0)
+            return scoreDelta;
+        const stockedDelta = b.stocked - a.stocked;
+        if (stockedDelta !== 0)
+            return stockedDelta;
+        return a.supplier.localeCompare(b.supplier);
+    });
+}
+const CATALOG_API_SORT_MAP = {
+    price: { field: 'price_per_lb', direction: 'asc' },
+    'price-desc': { field: 'price_per_lb', direction: 'desc' },
+    name: { field: 'name', direction: 'asc' },
+    origin: { field: 'country', direction: 'asc' },
+    newest: { field: 'stocked_date', direction: 'desc' },
+};
+function getCatalogApiBaseUrl() {
+    return (process.env.PURVEYORS_BASE_URL ?? 'https://www.purveyors.io').replace(/\/+$/, '');
+}
+async function getCatalogApiAuthHeader(supabase) {
+    const apiKey = process.env.PARCHMENT_API_KEY ?? process.env.PURVEYORS_API_KEY;
+    if (apiKey) {
+        return `Bearer ${apiKey}`;
+    }
+    const { data: { session }, } = await supabase.auth.getSession();
+    if (!session?.access_token) {
+        throw new AuthError('Catalog API reads require a Purveyors session or API key. Run `purvey auth login`, or set PARCHMENT_API_KEY/PURVEYORS_API_KEY for API-backed catalog reads.');
+    }
+    return `Bearer ${session.access_token}`;
+}
+function appendSearchParam(params, name, value) {
+    if (value === undefined)
+        return;
+    params.append(name, String(value));
+}
+function hasCatalogIdFilter(parsed) {
+    return parsed.ids !== undefined && parsed.ids.length > 0;
+}
+function assertCatalogApiCompatibleSearch(parsed) {
+    const unsupportedFilters = [];
+    if (parsed.flavor)
+        unsupportedFilters.push('--flavor');
+    if (parsed.supplier)
+        unsupportedFilters.push('--supplier');
+    if (parsed.dryingMethod)
+        unsupportedFilters.push('--drying-method');
+    if (parsed.sort === 'newest')
+        unsupportedFilters.push('--sort newest');
+    if (unsupportedFilters.length > 0) {
+        throw new PrvrsError('INVALID_ARGUMENT', `--include-proof uses /v1/catalog and cannot safely preserve ${unsupportedFilters.join(', ')} yet. Omit those filters or run the default catalog search without --include-proof.`);
+    }
+    if (hasCatalogIdFilter(parsed))
+        return;
+    const offset = parsed.offset ?? 0;
+    if (offset > 0 && offset % parsed.limit !== 0) {
+        throw new PrvrsError('INVALID_ARGUMENT', `--include-proof uses /v1/catalog page-based pagination; --offset must be a multiple of --limit. Received offset=${offset}, limit=${parsed.limit}.`);
+    }
+}
+function buildCatalogApiUrl(parsed) {
+    assertCatalogApiCompatibleSearch(parsed);
+    const url = new URL('/v1/catalog', getCatalogApiBaseUrl());
+    const params = url.searchParams;
+    params.set('include', 'proof');
+    params.set('stocked', parsed.stocked ? 'true' : 'all');
+    appendSearchParam(params, 'origin', parsed.origin);
+    appendSearchParam(params, 'processing', parsed.process);
+    appendSearchParam(params, 'processing_base_method', parsed.processingBaseMethod);
+    appendSearchParam(params, 'fermentation_type', parsed.fermentationType);
+    appendSearchParam(params, 'process_additive', parsed.processAdditive);
+    appendSearchParam(params, 'processing_disclosure_level', parsed.processingDisclosureLevel);
+    appendSearchParam(params, 'processing_confidence_min', parsed.processingConfidenceMin);
+    appendSearchParam(params, 'price_per_lb_min', parsed.priceMin);
+    appendSearchParam(params, 'price_per_lb_max', parsed.priceMax);
+    appendSearchParam(params, 'name', parsed.name);
+    appendSearchParam(params, 'cultivar_detail', parsed.variety);
+    appendSearchParam(params, 'stocked_days', parsed.stockedDays);
+    for (const id of parsed.ids ?? []) {
+        params.append('ids', String(id));
+    }
+    const sort = parsed.sort ? CATALOG_API_SORT_MAP[parsed.sort] : undefined;
+    if (sort) {
+        params.set('sortField', sort.field);
+        params.set('sortDirection', sort.direction);
+    }
+    if (!hasCatalogIdFilter(parsed)) {
+        const offset = parsed.offset ?? 0;
+        const limit = parsed.limit;
+        params.set('limit', String(limit));
+        if (offset > 0) {
+            params.set('page', String(Math.floor(offset / limit) + 1));
+        }
+    }
+    return url;
+}
+async function parseCatalogApiError(response, context = 'include=proof') {
+    let body;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        body = undefined;
+    }
+    const serverMessage = typeof body?.message === 'string'
+        ? body.message
+        : typeof body?.error === 'string'
+            ? body.error
+            : response.statusText;
+    const details = { status: response.status, body };
+    if (response.status === 401 || response.status === 403) {
+        return new AuthError(`Catalog API authentication failed: ${serverMessage}`, details);
+    }
+    if (response.status === 400) {
+        return new PrvrsError('INVALID_ARGUMENT', `Catalog API rejected ${context}: ${serverMessage}. Verify the configured Purveyors API endpoint supports this canonical catalog contract.`, details);
+    }
+    if (response.status === 404) {
+        if (context === '/v1/catalog/{id}/similar') {
+            if (/^Catalog coffee \d+ was not found$/i.test(serverMessage)) {
+                return new PrvrsError('NOT_FOUND', `Catalog similarity target not found: ${serverMessage}`, details);
+            }
+            return new PrvrsError('CONFIG_ERROR', `Catalog similarity API endpoint not found. Set PURVEYORS_BASE_URL to a Purveyors deployment that supports ${context}.`, details);
+        }
+        return new PrvrsError('CONFIG_ERROR', `Catalog API endpoint not found. Set PURVEYORS_BASE_URL to a Purveyors deployment that supports ${context}.`, details);
+    }
+    return new PrvrsError('GENERAL_ERROR', `Catalog API request failed (${response.status}): ${serverMessage}`, details);
+}
+function buildCatalogSimilarityApiUrl(parsed) {
+    const url = new URL(`/v1/catalog/${parsed.coffee_id}/similar`, getCatalogApiBaseUrl());
+    const params = url.searchParams;
+    params.set('threshold', String(parsed.threshold ?? 0.7));
+    params.set('limit', String(parsed.limit ?? 10));
+    params.set('stocked_only', String(parsed.stockedOnly ?? false));
+    if ((parsed.mode ?? 'all') !== 'all') {
+        params.set('mode', parsed.mode ?? 'all');
+    }
+    return url;
+}
+function isCatalogSimilarityResponse(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    const data = record.data;
+    const groups = data?.groups;
+    const meta = record.meta;
+    return Boolean(data &&
+        typeof data === 'object' &&
+        data.target &&
+        groups &&
+        Array.isArray(groups.canonical_candidates) &&
+        Array.isArray(groups.similar_recommendations) &&
+        meta &&
+        typeof meta.classification_version === 'string' &&
+        typeof meta.query_strategy === 'string');
+}
+async function fetchCatalogSimilarityApi(supabase, parsed) {
+    const url = buildCatalogSimilarityApiUrl(parsed);
+    const response = await fetch(url, {
+        headers: {
+            Accept: 'application/json',
+            Authorization: await getCatalogApiAuthHeader(supabase),
+        },
+    });
+    if (!response.ok) {
+        throw await parseCatalogApiError(response, '/v1/catalog/{id}/similar');
+    }
+    const envelope = (await response.json());
+    if (!isCatalogSimilarityResponse(envelope)) {
+        throw new PrvrsError('GENERAL_ERROR', 'Catalog similarity API returned an unexpected response shape; expected canonical { data: { target, groups: { canonical_candidates, similar_recommendations } }, meta }.', { body: envelope });
+    }
+    return envelope;
+}
+async function fetchCatalogApiItems(supabase, parsed) {
+    const url = buildCatalogApiUrl(parsed);
+    const response = await fetch(url, {
+        headers: {
+            Accept: 'application/json',
+            Authorization: await getCatalogApiAuthHeader(supabase),
+        },
+    });
+    if (!response.ok) {
+        throw await parseCatalogApiError(response);
+    }
+    const envelope = (await response.json());
+    if (!Array.isArray(envelope.data)) {
+        throw new PrvrsError('GENERAL_ERROR', 'Catalog API returned an unexpected response shape for include=proof; expected { data: [...] }.', { body: envelope });
+    }
+    return envelope.data;
+}
 /**
  * Aggregate stats from an array of catalog items.
  * Pure function — no I/O, safe to unit test.
@@ -84,6 +567,9 @@ export function computeCatalogStats(items) {
  */
 export async function searchCatalog(supabase, opts) {
     const parsed = searchCatalogSchema.parse(opts);
+    if (parsed.includeProof) {
+        return fetchCatalogApiItems(supabase, parsed);
+    }
     let query = supabase.from('coffee_catalog').select('*');
     if (parsed.origin) {
         const o = sanitizeFilterValue(parsed.origin);
@@ -93,6 +579,21 @@ export async function searchCatalog(supabase, opts) {
         const p = sanitizeFilterValue(parsed.process);
         query = query.ilike('processing', `%${p}%`);
     }
+    if (parsed.processingBaseMethod) {
+        query = query.eq('processing_base_method', sanitizeFilterValue(parsed.processingBaseMethod));
+    }
+    if (parsed.fermentationType) {
+        query = query.eq('fermentation_type', sanitizeFilterValue(parsed.fermentationType));
+    }
+    if (parsed.processAdditive) {
+        query = query.contains('process_additives', [sanitizeFilterValue(parsed.processAdditive)]);
+    }
+    if (parsed.processingDisclosureLevel) {
+        query = query.eq('processing_disclosure_level', sanitizeFilterValue(parsed.processingDisclosureLevel));
+    }
+    if (parsed.processingConfidenceMin !== undefined) {
+        query = query.gte('processing_confidence', parsed.processingConfidenceMin);
+    }
     if (parsed.priceMin !== undefined) {
         query = query.gte('price_per_lb', parsed.priceMin);
     }
@@ -175,8 +676,20 @@ export async function searchCatalog(supabase, opts) {
 /**
  * Fetch a single catalog item by ID.
  */
-export async function getCatalog(supabase, id) {
-    getCatalogSchema.parse({ id });
+export async function getCatalog(supabase, id, opts = {}) {
+    const parsed = getCatalogSchema.parse({ id, includeProof: opts.includeProof });
+    if (parsed.includeProof) {
+        const rows = await fetchCatalogApiItems(supabase, {
+            ids: [parsed.id],
+            limit: 1,
+            includeProof: true,
+        });
+        const item = rows[0];
+        if (!item) {
+            throw new PrvrsError('NOT_FOUND', `Coffee ID ${parsed.id} not found in catalog.`);
+        }
+        return item;
+    }
     const { data, error } = await supabase.from('coffee_catalog').select('*').eq('id', id).single();
     if (error)
         throw error;
@@ -193,6 +706,409 @@ export async function getCatalogStats(supabase) {
         throw error;
     return computeCatalogStats((data ?? []));
 }
+function buildCatalogIntelligenceQuery(supabase, parsed, options = {}) {
+    let query = supabase.from('coffee_catalog').select('*');
+    if (parsed.origin) {
+        const origin = sanitizeFilterValue(parsed.origin);
+        query = query.or(`country.ilike.%${origin}%,continent.ilike.%${origin}%,region.ilike.%${origin}%`);
+    }
+    if (parsed.process) {
+        const process = sanitizeFilterValue(parsed.process);
+        query = query.or(`processing.ilike.%${process}%,processing_base_method.ilike.%${process}%`);
+    }
+    if (parsed.supplier) {
+        query = query.ilike('source', `%${sanitizeFilterValue(parsed.supplier)}%`);
+    }
+    if (parsed.stocked !== undefined) {
+        query = query.eq('stocked', parsed.stocked);
+    }
+    if (parsed.priceMax !== undefined) {
+        query = query.lte('price_per_lb', parsed.priceMax);
+    }
+    if (parsed.minScore !== undefined) {
+        query = query.gte('purveyor_score', parsed.minScore);
+    }
+    if (parsed.orderByScore) {
+        query = query.order('purveyor_score', { ascending: false, nullsFirst: false });
+    }
+    else {
+        query = query.order('source', { ascending: true, nullsFirst: false });
+    }
+    if (options.applyRange ?? true) {
+        const sampleSize = parsed.sampleSize ?? CATALOG_PREMIUM_DEFAULT_SAMPLE_SIZE;
+        query = query.range(0, sampleSize - 1);
+    }
+    return query;
+}
+async function fetchSupplierAggregateRows(supabase, parsed) {
+    const sampleSize = parsed.sampleSize ?? SUPPLIER_AGGREGATE_DEFAULT_SAMPLE_SIZE;
+    const pageSize = Math.min(sampleSize, SUPABASE_DATA_API_MAX_PAGE_SIZE);
+    const rows = [];
+    for (let offset = 0;; offset += pageSize) {
+        const { data, error } = await buildCatalogIntelligenceQuery(supabase, {
+            supplier: parsed.supplier,
+            stocked: parsed.stocked,
+        }, { applyRange: false })
+            .order('id', { ascending: true })
+            .range(offset, offset + pageSize - 1);
+        if (error)
+            throw error;
+        const page = (data ?? []);
+        rows.push(...page);
+        if (page.length < pageSize)
+            break;
+    }
+    return rows;
+}
+async function fetchCatalogPremiumSampleRows(supabase, parsed, sampleSize) {
+    const targetRows = sampleSize + 1;
+    const pageSize = Math.min(targetRows, SUPABASE_DATA_API_MAX_PAGE_SIZE);
+    const rows = [];
+    for (let offset = 0; rows.length < targetRows; offset += pageSize) {
+        const pageEnd = Math.min(offset + pageSize - 1, targetRows - 1);
+        const { data, error } = await buildCatalogIntelligenceQuery(supabase, {
+            ...parsed,
+            orderByScore: true,
+        }, { applyRange: false })
+            .order('id', { ascending: true })
+            .range(offset, pageEnd);
+        if (error)
+            throw error;
+        const page = (data ?? []);
+        rows.push(...page);
+        if (page.length < pageEnd - offset + 1)
+            break;
+    }
+    return {
+        sampledRows: rows.slice(0, sampleSize),
+        truncated: rows.length > sampleSize,
+    };
+}
+const catalogIntelligenceCaveats = [
+    'Purveyor Score is read from coffee_catalog.purveyor_score with confidence, tier, factor breakdown, version, and update metadata; the CLI does not recompute the upstream score model.',
+    'Ranking is catalog-only and does not account for a roaster’s owned inventory, roast history, or target menu fit.',
+];
+const catalogPremiumRankingCaveats = [
+    ...catalogIntelligenceCaveats,
+    'Premium ranking samples catalog rows ordered by purveyor_score descending, then id ascending, before applying agent-facing ranking logic; meta.truncated indicates more rows matched than the requested sample_size.',
+];
+const supplierAggregateCaveats = [
+    ...catalogIntelligenceCaveats,
+    'Supplier aggregates paginate catalog rows ordered by source ascending, then id ascending; meta.sample_size is the requested fetch page size and meta.rows_examined reports the rows included in aggregation.',
+];
+const catalogFacetColumns = {
+    supplier: 'source',
+    country: 'country',
+    processing_base_method: 'processing_base_method',
+    fermentation_type: 'fermentation_type',
+    drying_method: 'drying_method',
+    grade: 'grade',
+    wholesale: 'wholesale',
+};
+const catalogFacetCaveats = [
+    'Facet counts are computed from catalog rows visible to the current client and are intended for value discovery, not inventory guarantees.',
+];
+const catalogRankingCaveats = [
+    ...catalogIntelligenceCaveats,
+    'Generic catalog ranking samples catalog rows ordered by id ascending before applying deterministic objective-specific ranking; meta.truncated indicates more rows matched than the requested sample_size.',
+];
+function asPositiveNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : null;
+}
+function scoreBasis(item) {
+    const score = summarizePurveyorScore(item);
+    if (score.value === null)
+        return 'no Purveyor Score yet';
+    const tier = score.tier ? `, ${score.tier}` : '';
+    return `Purveyor Score ${score.value}${tier}`;
+}
+async function fetchCatalogFacetRows(supabase, parsed) {
+    const sampleSize = parsed.sampleSize ?? SUPPLIER_AGGREGATE_DEFAULT_SAMPLE_SIZE;
+    const targetRows = sampleSize + 1;
+    const pageSize = Math.min(targetRows, SUPABASE_DATA_API_MAX_PAGE_SIZE);
+    const rows = [];
+    const column = catalogFacetColumns[parsed.field];
+    for (let offset = 0; rows.length < targetRows; offset += pageSize) {
+        const pageEnd = Math.min(offset + pageSize - 1, targetRows - 1);
+        let query = supabase.from('coffee_catalog').select(`id, ${String(column)}`);
+        if (parsed.stockedOnly ?? true)
+            query = query.eq('stocked', true);
+        const { data, error } = await query.order('id', { ascending: true }).range(offset, pageEnd);
+        if (error)
+            throw error;
+        const page = (data ?? []);
+        rows.push(...page);
+        if (page.length < pageEnd - offset + 1)
+            break;
+    }
+    return { rows: rows.slice(0, sampleSize), truncated: rows.length > sampleSize };
+}
+async function fetchCatalogRankRows(supabase, parsed) {
+    const sampleSize = parsed.sampleSize ?? SUPPLIER_AGGREGATE_DEFAULT_SAMPLE_SIZE;
+    const targetRows = sampleSize + 1;
+    const pageSize = Math.min(targetRows, SUPABASE_DATA_API_MAX_PAGE_SIZE);
+    const rows = [];
+    for (let offset = 0; rows.length < targetRows; offset += pageSize) {
+        const pageEnd = Math.min(offset + pageSize - 1, targetRows - 1);
+        let query = supabase.from('coffee_catalog').select('*');
+        if (parsed.stockedOnly ?? true)
+            query = query.eq('stocked', true);
+        if (parsed.supplier)
+            query = query.ilike('source', `%${sanitizeFilterValue(parsed.supplier)}%`);
+        if (parsed.country)
+            query = query.ilike('country', `%${sanitizeFilterValue(parsed.country)}%`);
+        if (parsed.process) {
+            const process = sanitizeFilterValue(parsed.process);
+            query = query.or(`processing.ilike.%${process}%,processing_base_method.ilike.%${process}%`);
+        }
+        if (parsed.priceMax !== undefined)
+            query = query.lte('price_per_lb', parsed.priceMax);
+        if (parsed.minScore !== undefined)
+            query = query.gte('purveyor_score', parsed.minScore);
+        if (parsed.nonWholesaleOnly)
+            query = query.or('wholesale.is.null,wholesale.eq.false');
+        const { data, error } = await query.order('id', { ascending: true }).range(offset, pageEnd);
+        if (error)
+            throw error;
+        const page = (data ?? []);
+        rows.push(...page);
+        if (page.length < pageEnd - offset + 1)
+            break;
+    }
+    return { rows: rows.slice(0, sampleSize), truncated: rows.length > sampleSize };
+}
+function rankCatalogRows(rows, objective, limit) {
+    const byScoreDesc = (a, b) => (getPurveyorScoreValue(b) ?? -Infinity) - (getPurveyorScoreValue(a) ?? -Infinity) ||
+        String(b.stocked_date ?? '').localeCompare(String(a.stocked_date ?? '')) ||
+        a.id - b.id;
+    let ranked;
+    switch (objective) {
+        case 'premium':
+            ranked = [...rows].sort(byScoreDesc).map((row) => ({ row, basis: scoreBasis(row) }));
+            break;
+        case 'value': {
+            ranked = rows
+                .map((row) => {
+                const score = getPurveyorScoreValue(row);
+                const price = asPositiveNumber(getPerLbPrice(row));
+                if (score === null || price === null)
+                    return null;
+                return { row, ratio: score / price };
+            })
+                .filter((entry) => entry !== null)
+                .sort((a, b) => b.ratio - a.ratio || byScoreDesc(a.row, b.row))
+                .map(({ row, ratio }) => ({
+                row,
+                basis: `${scoreBasis(row)} at $${getPerLbPrice(row)}/lb (${round(ratio, 1)} score points per dollar)`,
+            }));
+            break;
+        }
+        case 'fresh_arrival':
+            ranked = [...rows]
+                .sort((a, b) => String(b.stocked_date ?? '').localeCompare(String(a.stocked_date ?? '')) ||
+                String(b.arrival_date ?? '').localeCompare(String(a.arrival_date ?? '')) ||
+                byScoreDesc(a, b))
+                .map((row) => ({
+                row,
+                basis: `stocked ${row.stocked_date ?? 'date unknown'}; ${scoreBasis(row)}`,
+            }));
+            break;
+        case 'rare_origin': {
+            const originCounts = new Map();
+            for (const row of rows) {
+                const country = row.country?.trim();
+                if (country)
+                    originCounts.set(country, (originCounts.get(country) ?? 0) + 1);
+            }
+            const rarity = (row) => {
+                const country = row.country?.trim();
+                return country
+                    ? (originCounts.get(country) ?? Number.MAX_SAFE_INTEGER)
+                    : Number.MAX_SAFE_INTEGER;
+            };
+            ranked = [...rows]
+                .filter((row) => Boolean(row.country?.trim()))
+                .sort((a, b) => rarity(a) - rarity(b) || byScoreDesc(a, b))
+                .map((row) => ({
+                row,
+                basis: `${row.country} has ${rarity(row)} matching listing(s); ${scoreBasis(row)}`,
+            }));
+            break;
+        }
+    }
+    return ranked.slice(0, limit).map(({ row, basis }, index) => ({
+        ...row,
+        rank: index + 1,
+        rank_basis: basis,
+    }));
+}
+/** List distinct catalog facet values with counts for agent/client filter discovery. */
+export async function listCatalogFacets(supabase, input) {
+    const parsed = catalogFacetsSchema.parse(input);
+    const limit = parsed.limit ?? 60;
+    const sampleSize = parsed.sampleSize ?? SUPPLIER_AGGREGATE_DEFAULT_SAMPLE_SIZE;
+    const { rows, truncated } = await fetchCatalogFacetRows(supabase, parsed);
+    const column = catalogFacetColumns[parsed.field];
+    const counts = new Map();
+    for (const row of rows) {
+        const raw = row[column];
+        const value = typeof raw === 'boolean' ? String(raw) : typeof raw === 'string' ? raw.trim() : '';
+        if (!value)
+            continue;
+        counts.set(value, (counts.get(value) ?? 0) + 1);
+    }
+    const values = [...counts.entries()]
+        .map(([value, count]) => ({ value, count }))
+        .sort((a, b) => b.count - a.count || a.value.localeCompare(b.value));
+    return {
+        data: values.slice(0, limit),
+        meta: {
+            resource: 'catalog-facets',
+            field: parsed.field,
+            source_column: String(column),
+            stocked_only: parsed.stockedOnly ?? true,
+            scope: (parsed.stockedOnly ?? true) ? 'stocked_only' : 'all_visible',
+            sample_size: sampleSize,
+            sample_limited: true,
+            sample_order: 'id_asc',
+            truncated: truncated || values.length > limit,
+            rows_examined: rows.length,
+            distinct_values: values.length,
+            returned: Math.min(values.length, limit),
+            caveats: catalogFacetCaveats,
+        },
+    };
+}
+/** Rank catalog candidates by deterministic product-intelligence objectives. */
+export async function rankCatalog(supabase, input = {}) {
+    const parsed = catalogRankSchema.parse(input);
+    const sampleSize = parsed.sampleSize ?? SUPPLIER_AGGREGATE_DEFAULT_SAMPLE_SIZE;
+    const objective = parsed.objective ?? 'premium';
+    const limit = parsed.limit ?? 10;
+    const { rows, truncated } = await fetchCatalogRankRows(supabase, parsed);
+    const data = rankCatalogRows(rows, objective, limit);
+    const caveats = [...catalogRankingCaveats];
+    if (objective === 'value') {
+        caveats.push('Value objective ranks by Purveyor Score per dollar; rows without score or price are excluded.');
+    }
+    if (objective === 'rare_origin' && parsed.country) {
+        caveats.push('rare_origin combined with a country filter measures rarity only within that country filter.');
+    }
+    return {
+        data,
+        meta: {
+            resource: 'catalog-ranking',
+            objective,
+            scoring_source: 'coffee_catalog.purveyor_score',
+            sample_size: sampleSize,
+            sample_limited: true,
+            sample_order: 'id_asc',
+            truncated,
+            candidates_considered: rows.length,
+            returned: data.length,
+            filters: {
+                supplier: parsed.supplier,
+                country: parsed.country,
+                process: parsed.process,
+                stocked_only: parsed.stockedOnly ?? true,
+                scope: (parsed.stockedOnly ?? true) ? 'stocked_only' : 'all_visible',
+                priceMax: parsed.priceMax,
+                minScore: parsed.minScore,
+                nonWholesaleOnly: parsed.nonWholesaleOnly ?? false,
+            },
+            caveats,
+        },
+    };
+}
+/**
+ * Rank premium catalog candidates by Purveyor Score, with pricing and sourcing signals.
+ */
+export async function catalogRankPremium(supabase, input = {}) {
+    const parsed = catalogRankPremiumSchema.parse(input);
+    const sampleSize = parsed.sampleSize ?? CATALOG_PREMIUM_DEFAULT_SAMPLE_SIZE;
+    const { sampledRows, truncated } = await fetchCatalogPremiumSampleRows(supabase, parsed, sampleSize);
+    const ranking = computeCatalogPremiumRanking(sampledRows, {
+        limit: parsed.limit ?? 10,
+        includeUnscored: parsed.includeUnscored ?? false,
+        minScore: parsed.minScore,
+    });
+    return {
+        data: ranking,
+        meta: {
+            resource: 'catalog-premium-ranking',
+            scoring_source: 'coffee_catalog.purveyor_score',
+            sample_size: sampleSize,
+            sample_limited: true,
+            sample_order: 'purveyor_score_desc_nulls_last',
+            truncated,
+            returned: ranking.length,
+            filters: {
+                origin: parsed.origin,
+                process: parsed.process,
+                supplier: parsed.supplier,
+                stocked: parsed.stocked,
+                priceMax: parsed.priceMax,
+                minScore: parsed.minScore,
+                includeUnscored: parsed.includeUnscored ?? false,
+            },
+            caveats: catalogPremiumRankingCaveats,
+        },
+    };
+}
+async function getSupplierAggregates(supabase, input, resource) {
+    const parsed = supplierAggregateSchema.parse(input);
+    const sampleSize = parsed.sampleSize ?? SUPPLIER_AGGREGATE_DEFAULT_SAMPLE_SIZE;
+    const rows = await fetchSupplierAggregateRows(supabase, {
+        supplier: parsed.supplier,
+        stocked: parsed.stocked,
+        sampleSize,
+    });
+    const aggregates = computeSupplierAggregates(rows, {
+        topCoffees: parsed.topCoffees ?? 5,
+        minCoffees: parsed.minCoffees ?? 1,
+    }).slice(0, parsed.limit ?? 25);
+    return {
+        data: aggregates,
+        meta: {
+            resource,
+            sample_size: sampleSize,
+            sample_limited: false,
+            sample_order: 'source_asc_nulls_last',
+            truncated: false,
+            rows_examined: rows.length,
+            returned: aggregates.length,
+            filters: {
+                supplier: parsed.supplier,
+                stocked: parsed.stocked,
+                minCoffees: parsed.minCoffees ?? 1,
+            },
+            caveats: supplierAggregateCaveats,
+        },
+    };
+}
+/** List supplier aggregates from catalog rows. */
+export async function supplierList(supabase, input = {}) {
+    return getSupplierAggregates(supabase, input, 'supplier-list');
+}
+/** Return aggregate detail for a supplier query. */
+export async function supplierDetail(supabase, input) {
+    const parsed = supplierAggregateSchema.parse(input);
+    if (!parsed.supplier?.trim()) {
+        throw new PrvrsError('INVALID_ARGUMENT', 'supplierDetail requires a non-empty supplier name.');
+    }
+    return getSupplierAggregates(supabase, { ...parsed, limit: parsed.limit ?? 10 }, 'supplier-detail');
+}
+/** Rank suppliers by average Purveyor Score, then currently stocked coverage. */
+export async function supplierRank(supabase, input = {}) {
+    return getSupplierAggregates(supabase, input, 'supplier-rank');
+}
+/**
+ * Fetch canonical catalog similarity groups from the beta /v1/catalog/{id}/similar API.
+ */
+export async function getCatalogSimilarity(supabase, input) {
+    const parsed = getCatalogSimilaritySchema.parse(input);
+    return fetchCatalogSimilarityApi(supabase, parsed);
+}
 /**
  * Find beans similar to a target coffee using pgvector embedding similarity.
  * Calls the `find_similar_beans_aggregated` RPC and returns ranked matches.