Commerce

CatalogListing exposes that product in a particular corporate store with

store-specific copy, pricing, approved artwork, and customization rules.

CatalogCollection organizes large assortments without duplicating products.

CatalogSourceProvider is the adapter contract for supplier feeds and live

inventory.

Optional provider taxonomy discovery feeds durable categories and

subcategories without hardcoded provider lists.

Supplier sync checkpoints and batch variant upserts make large feed imports

resumable and efficient; listing queries filter by search, brand, category, and product type.

That model supports one supplier product being reused across hundreds of tenant catalogs while every store remains independently merchandised.

DecorationItemInput.identity carries brand, style, SKU, supplier SKU, catalog/listing, and variant identity into OrderProductionSpec, spec.json, and the printable work order. Operators can therefore pull the exact blank without relying on a separate admin screen.

createStorefrontAftercareService() replaces one-off return tables with a single durable order-linked case substrate for returns, exchanges, payment disputes, and customer support. Guest access reuses the secret checkout token; owner and fleet views retain assignment, internal notes, public conversation, structured resolutions, optimistic transition fencing, and stable lifecycle events. Customer requests and notification delivery are separately gated. Signed payment dispute events correlate through the provider payment identity and upsert one case without exposing raw provider payloads. Approved full returns can enqueue a distinct post-delivery refund action, so shipped-order refunds never run through fulfillment cancellation.

createStorefrontAftercareEvidenceService() owns the private attachment and payment-dispute evidence lifecycle. Uploads begin in pending_scan, use leased inspection, and remain hidden from customers unless clean. Infected bytes stay quarantined, scanner failures fail closed, and terminal-case retention cleanup deletes through a host-supplied blob boundary. Dispute evidence jobs accept only clean case-owned attachments, preserve stable provider idempotency, and quarantine ambiguous submission outcomes. A retry is prohibited until a leased provider reconciliation confirms the intended effect was not applied; applied effects converge on the retained staged/submitted record. Reconciliation also retains non-secret field/purpose mismatch diagnostics without copying customer evidence values into operational metadata. Tenant-owned deadline policies control whether alerts run, whether overdue alerts are emitted, and up to six unique warning thresholds from 1 to 720 hours. The service emits idempotent deadline events through the case event substrate and records durable, audience-routed escalations with bounded acknowledgement deadlines. createStorefrontAftercareEscalationService() adds optimistic acknowledgement and assignment, leased and retryable host-supplied incident promotion, terminal resolution, and privacy-safe SLA/outcome analytics. Evidence effectiveness counts whether a staged/submitted bundle existed; it never returns evidence values, file identifiers, or customer content. Provider adapters implement reconcileDisputeEvidence and submitDisputeEvidence; the host independently gates reconciliation, staging, final payment-network submission, notification delivery, and incident promotion.

Cross-origin provider journey evidence

Hosted checkout and invoice pages run outside the application's origin, so no browser SDK can directly capture errors rendered there. Use withProviderJourneyCorrelation() to stamp a host-owned identity into provider metadata. Providers with fixed metadata slots can pass that slot as the third argument. Retain privacy-safe ProviderJourneyEvidence from host requests, provider APIs, webhooks, reconciliation, and customer reports, then call summarizeProviderJourney().

These Commerce names are compatibility adapters over @absolutejs/handoff. New cross-domain integrations should import the neutral handoff vocabulary directly; Commerce retains payment-specific naming for existing consumers.

The summary keeps customer-reported hosted-page outcomes separate from authoritative provider evidence and flags contradictions such as a hosted page reporting failure after a webhook confirmed success. Evidence intentionally excludes raw webhook payloads, credentials, card data, and customer data; hosts keep those in their own protected stores.

The ./react export includes a reusable StorefrontRenderer and listing/card controls, while ./client includes a storefront-scoped persistent cart store. Both remain provider-neutral and can be styled by the host without replacing the cart or checkout contracts.

FulfillmentCostQuoteProvider is the read-only preflight seam for providers that can price an exact set of fulfillment lines and destination. Quotes expose normalized item, shipping, and adjustment costs, but deliberately do not claim to reserve provider inventory or pricing. Spending applications refresh the quote immediately before authorization and bind final settlement to the provider's accepted cost.

Follows the same shape as @absolutejs/voice: a host package holds the agnostic logic + adapter contracts, and provider implementations live in the commerce-adapters monorepo (Apache-2.0).