How product search works

Published discovery

searchPublishedProducts() searches published products from active stores with active, in-stock variants. Buyer price constraints are enforced in integer minor units. Meaningful product terms must match, one variant per product is returned, and ordering is deterministic.

Recommendations reuse the executed search result. They cannot invent price, stock, delivery speed, or seller verification.

Relevance and title repair

Search normalization handles safe spelling correction and prevents partial-word false positives such as treating a requested named wearable as an air fryer. The title-repair command selects price-matched catalogue records and writes an audit record; it is an explicit operational command, not automatic mutation during buyer search.

Meta Commerce projection

flowchart LR
  Products[(Published products and variants)] --> Project[Deterministic projection]
  Project --> Fingerprint[Catalogue fingerprint]
  Fingerprint --> Lock[Per-catalogue advisory lock]
  Lock --> Pending[(Pending mappings)]
  Pending --> Meta[Meta Commerce API]
  Meta --> Final[(Synced or failed mappings)]
  Cart[Native product/cart payload] --> Resolve[Retailer ID resolution]
  Resolve --> Final

Stable SKU retailer IDs map Meta catalogue items back to Neo variants. Synchronization is serialized per catalogue, writes pending/final batches atomically around provider delivery, and treats an unchanged fingerprint as a no-op. HTTPS image requirements and catalogue scope are enforced.

Failure and certification boundary

A provider failure records failed mapping state for safe retry. Native list ordering follows the requested input order. Meta synchronization may be implemented and tested without being certified for a particular production account or credential rotation.

• src/catalog.ts
• src/meta-commerce.ts
• scripts/meta-commerce-setup.ts
• test/catalog.test.ts
• test/meta-commerce.test.ts