@fayz-ai/shop

The commerce layer behind every Fayz storefront — products, orders, customers, discounts, shipping.

Status: beta — published to npm and used across Fayz dogfood apps. Pre-1.0: minor APIs may change before 1.0.

@fayz-ai/shop is the headless ecommerce engine: a ShopProvider contract plus the domain types for products, carts, orders, customers, discounts, and shipping. It owns what commerce means so the storefront (@fayz-ai/storefront) and admin surfaces only have to render it.

It's provider-first by design. Ship a demo on createMockShopProvider, then drop in createSupabaseShopProvider (or your own ShopProvider) for real data — the UI doesn't change. Tenancy is resolved through a pluggable resolver, so the same engine serves one store or a marketplace of thousands.

What's inside

• ShopProvider contract — the one interface every backend implements
• Providers — createMockShopProvider (demo/offline) and createSupabaseShopProvider (real)
• Runtime — getShopProvider / setShopProvider singleton wiring
• Tenancy — setShopTenantResolver / getShopTenantId for multi-store isolation
• Public domain types — products, orders, customers, discounts, shipping
• StockStore contract (@fayz-ai/shop/inventory) — stock as an append-only ledger rather than a scalar, with a Supabase and an in-memory implementation held to one shared contract suite

Install

npm install @fayz-ai/shop

Peer deps: @fayz-ai/core, @fayz-ai/ui, @fayz-ai/auth (+ react, react-dom).

Usage

import { setShopProvider, createSupabaseShopProvider } from '@fayz-ai/shop'

setShopProvider(createSupabaseShopProvider({ /* supabase + storeId */ }))

Stock is a ledger: movements are appended, balances are derived from them, and available = on_hand − reserved. The same code runs against either implementation.

import { createSupabaseStockStore } from '@fayz-ai/shop/inventory'

const stock = createSupabaseStockStore()
await stock.recordMovement({
  variantId,
  kind: 'receipt',            // vocabulary rows, not a hardcoded enum
  reasonCode: 'purchase',
  quantity: 12,               // signed; the kind's direction decides the sign
  idempotencyKey: `po-1180:${variantId}`, // a retry returns the same movement
})
await stock.getAvailable(variantId)

Part of the Fayz SDK

The commerce engine @fayz-ai/storefront renders and @fayz-ai/plugin-shop administers. Pair with @fayz-ai/sdk's shop client for generated storefronts.

Roadmap & contributing

Built and evolving in the open. See the Fayz SDK roadmap.