# litecommerce Storefront Skill

Version: M3 customer-surface refresh (`0.2.0`).

Use this skill when building a tenant-owned storefront on litecommerce. The
storefront can be Next.js, Astro, Remix, plain React, or another web stack, but
litecommerce remains the backend of record for catalog, content, inventory,
checkout sessions, payments, orders, returns, shipping rates, and future hosted
litecheckout / shared-commerce surfaces.

This is a tenant-facing implementation skill, not an internal litecommerce repo
agent. Prefer small, production-shaped storefront code over demo-only scaffolds.

## Start Here

1. Ask for the tenant slug and API base URL. Production API calls normally use
   `https://api.litecommerce.io/api/v1`.
2. Send `x-organization-slug: <tenant-slug>` on tenant-resolving public
   requests. Token-only checkout handoff routes document their own exception.
3. Build against `/api/v1/public/*` first. Do not use merchant, platform, or
   internal APIs for customer storefront work unless the human explicitly asks
   for an authenticated admin surface.
4. Read `references/capabilities.md` before claiming a capability is live. That
   file is generated from litecommerce's feature-status source of truth.
5. Use the OpenAPI reference for endpoint details. Do not copy request or
   response schemas into generated code unless the user explicitly asks.

## Non-Negotiables

- Never put server secrets in browser code or public environment variables:
  `SUPABASE_SERVICE_ROLE_KEY`, `SUPABASE_SECRET_KEY`, `SUPABASE_JWT_SECRET`,
  `POSTGRES_*`, tenant secret keys, Stripe secrets, or private API tokens.
- Browser code may use only browser-safe public values. Prefer server-side API
  calls for framework code, especially when composing cart/order flows.
- Treat litecommerce error responses as a standard error envelope and render
  useful customer states instead of crashing.
- Handle empty catalogs, empty collections, missing images, unavailable
  variants, and temporarily absent optional features gracefully.
- Storefronts are CUSTOM by default. Do not assume every tenant has a
  litecommerce-hosted subdomain.

## Recommended Build Flow

1. Catalog shell: listing page, product cards, search/filter controls that map
   to public catalog reads, and empty states.
2. Product detail: render `item.shortDescription` as compact blurb copy and
   `item.description` as the primary PDP body; then add variant selection, media
   gallery, availability check, bundle/discount preview callouts, and
   add-to-cart action. Use metafields for structured extras or explicit
   variant-specific overrides, not as the default product description source.
   When a tenant explicitly needs variant-specific body copy, use the
   conventional override key `metafields.description` on the selected variant
   and fall back to `item.description`.
3. Collections and pages: merchandising collections, CMS pages, and navigation
   derived from public content.
4. Cart: local cart state is editable; line-item and preview calls are still
   estimates until the server-side checkout session is repriced and bound.
   Render the standard cart summary — subtotal, itemized discounts/coupon
   names, shipping, tax disclosure, and an estimated-vs-bound total — the same
   way across drawer, full cart, and checkout handoff, per
   `references/cart-summary-contract.md`.
5. BYO checkout: create/reprice/bind a checkout session with
   `x-organization-slug`, then request the token-only payment handoff without
   that header. Render Stripe Payment Element with the returned `clientSecret`;
   never create Stripe PaymentIntents directly.
6. Legacy order placement: `POST /api/v1/public/orders` still creates an order
   from line items only. Prefer checkout sessions for new payment-capable
   storefronts.
7. Post-purchase: confirmation/status pages use public order reads. The
   order-confirmation email also carries a read-only `o`-token status link
   (`GET /api/v1/public/orders/token/:token` — no customer session, but it
   still requires `x-organization-slug`; unlike the checkout payment-session
   call it is NOT fully token-only) a storefront can render its own page
   against — pass the token through verbatim. Returns use the email-match
   customer-lite flow or the customer account APIs.
8. Customer accounts (optional tier): passwordless sign-in
   (`request-link`/`request-otp`/`verify` under `/api/v1/public/customer/auth`)
   plus the authenticated `/api/v1/customer/account/*` surface — profile,
   addresses, order history, returns. See "Customer Accounts And Sign-In" in
   `references/api-patterns.md`; keep the session token server-side, and never
   branch UI on the always-neutral challenge responses.
9. Hosted litecheckout — **matrix-gated**: the hand-off path (a tenant hands
   checkout/status/account surfaces to the litecommerce-hosted app instead of
   building them) only applies once `references/capabilities.md` marks the
   hosted surface shipped; while it lists `litecheckout` /
   `storefront-redirect` as planned/in-progress, do NOT generate hosted
   redirects or `*.litecheckout.io` URLs in tenant storefront code. When the
   matrix allows it, `https://docs.litecommerce.io/guides/hosted-litecheckout`
   documents the route map and per-area hand-off seam. Never expose database
   ids in customer URLs.

## Storefront Origin Posture

Build for CUSTOM tenant storefronts by default. litecommerce-hosted subdomain
flows and platform-sent canonical redirects are M3-era behavior tied to the
`storefront-redirect` capability. Until that capability is marked shipped and
the redirect contract is documented, do not assume a tenant has a hosted
litecommerce storefront URL or invent hosted checkout/status redirect URLs.

## Versioning

This skill is refreshed by milestone. Future milestone refreshes update the
capability matrix and references as shared-commerce quote/invoice/contract
actions, bookings, subscriptions, API keys, outbound webhooks, integrations, and
SaaS packaging become real public contracts. Do not patch a tenant storefront
against an imagined future endpoint; update the skill or point to the current
OpenAPI/docs contract first.

## References

- `references/capabilities.md` - generated live/in-progress/planned matrix.
- `references/api-patterns.md` - endpoint map and wire-level API gotchas.
- `references/cart-summary-contract.md` - the standard cart summary rows + estimate-vs-binding disclosure.
- `references/storefront-checklist.md` - implementation checklist.
- `references/validation-checklist.md` - review checklist for generated code.
- `examples/` - forward-test prompts with expected output shapes and
  validation steps (product grid, product detail, litecheckout handoff,
  storefront brief template).
- API reference: `https://docs.litecommerce.io/api-reference`
- Guides: `https://docs.litecommerce.io/guides/byo-checkout`,
  `https://docs.litecommerce.io/guides/customer-accounts`,
  `https://docs.litecommerce.io/guides/order-status`,
  `https://docs.litecommerce.io/guides/hosted-litecheckout`