@cartbase/storefront 0.6.0 → 0.8.0

package/README.md

@@ -1,58 +1,74 @@
-# @cartbase/storefront
-
-The storefront kit for the [Cartbase](https://cartbase.net) commerce
-platform: a fully-typed API client for every store endpoint, checkout
-orchestration, a production-grade cart drawer, product and catalog
-components, and consent-gated tracking — everything a storefront needs
-between your pages and your store.
-
-```bash
-npm create cartbase my-store    # scaffold with everything prewired
-# or add to an existing Next.js app:
-npm install @cartbase/storefront
-```
-
-## Setup
-
-The package is **source-shipped TypeScript** — tell Next.js to compile it:
-
-```js
-// next.config.js
-module.exports = {
-  transpilePackages: ["@cartbase/storefront"],
-}
-```
-
-Three environment values wire it to your store (all in your Cartbase
-admin under **Settings**):
-
-```bash
-NEXT_PUBLIC_CARTBASE_URL=            # your store's API origin
-NEXT_PUBLIC_CARTBASE_CLIENT_ID=      # your store's client id
-NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY=  # optional, channel-scoped catalogs
-```
-
-## What's inside
-
-| Import | What you get |
-|---|---|
-| `@cartbase/storefront/api` | Typed client for the whole store API — products, carts, checkout, orders, customers, auth, content, search, reviews |
-| `@cartbase/storefront/checkout` | The complete checkout: orchestration hook, address forms, shipping/payment method lists, Stripe wrapper, carrier pickers |
-| `@cartbase/storefront/cart-drawer` | Slide-out cart with upsells, tiers, gift options, notes |
-| `@cartbase/storefront/products` | PDP building blocks: gallery, options, prices, actions |
-| `@cartbase/storefront/store` | Listing pages: pagination, sorting, collection/category/search templates |
-| `@cartbase/storefront/order` | Order confirmation surfaces |
-| `@cartbase/storefront/tracking` | Consent banner + consent-gated Meta Pixel / GA4 / analytics |
-| `@cartbase/storefront/theme` | The design system: token names plus a filled default set of values (Tailwind 4, CSS-first) |
-
-## Documentation
-
-The complete reference — every endpoint with request/response shapes and
-working examples, plus a step-by-step build runbook — is written to be
-followed by a developer **or handed to a coding agent as-is**. It ships
-inside every `npm create cartbase` scaffold under `docs/`, and online at
-your store's docs site. Start with *Build a storefront — the runbook*.
-
-## License
-
-MIT © Cartbase
+# @cartbase/storefront
+
+The storefront kit for the [Cartbase](https://cartbase.net) commerce
+platform: a fully-typed API client for every store endpoint, checkout
+orchestration, a production-grade cart drawer, product and catalog
+components, and consent-gated tracking — everything a storefront needs
+between your pages and your store.
+
+```bash
+npm create cartbase my-store    # scaffold with everything prewired
+# or add to an existing Next.js app:
+npm install @cartbase/storefront
+```
+
+## Setup
+
+The package is **source-shipped TypeScript** — tell Next.js to compile it:
+
+```js
+// next.config.js
+module.exports = {
+  transpilePackages: ["@cartbase/storefront"],
+}
+```
+
+One environment value wires it to your store: the publishable key your
+Cartbase admin hands out on the **Storefront** page.
+
+```bash
+NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY=  # your store's key: names the store, scopes the catalog
+NEXT_PUBLIC_CARTBASE_URL=              # optional: only to point at a local or staging platform
+```
+
+## What's inside
+
+| Import | What you get |
+|---|---|
+| `@cartbase/storefront/api` | Typed client for the whole store API — products, carts, checkout, orders, customers, auth, content, search, reviews |
+| `@cartbase/storefront/checkout` | The complete checkout: orchestration hook, address forms, shipping/payment method lists, Stripe wrapper, carrier pickers |
+| `@cartbase/storefront/cart-drawer` | Slide-out cart with upsells, tiers, gift options, notes |
+| `@cartbase/storefront/products` | PDP building blocks: gallery, options, prices, actions |
+| `@cartbase/storefront/store` | Listing pages: pagination, sorting, collection/category/search templates |
+| `@cartbase/storefront/order` | Order confirmation surfaces |
+| `@cartbase/storefront/tracking` | Consent banner and Consent Mode v2, every marketing tag the store configured mounted from its own config (Meta Pixel, TikTok, Google Analytics 4 and Google Ads on one tag, Google Tag Manager), and one call per commerce moment that fires all of them |
+| `@cartbase/storefront/theme` | The design system: token names plus a filled default set of values (Tailwind 4, CSS-first) |
+
+### Tracking, in three lines
+
+The merchant configures their pixels in the admin; the storefront mounts
+what they configured. Nothing per vendor:
+
+```tsx
+<ConsentInit />                 // first child of <body>, sets the consent defaults
+<StorefrontTags client={client} />  // every configured tag, gated by the above
+<TrackInit />                   // captures UTMs + ad-click ids on the landing page
+```
+
+Then one call per moment (`trackProductView`, `trackCartAdd`,
+`trackCheckoutStart`) and `<TrackOrderPurchase>` on the confirmation
+page. Purchase events dedupe against the platform's own server-side
+events automatically — the ids are derived from the order number on both
+sides, so the browser event and the server event count as one conversion.
+
+## Documentation
+
+The complete reference — every endpoint with request/response shapes and
+working examples, plus a step-by-step build runbook — is written to be
+followed by a developer **or handed to a coding agent as-is**. It ships
+inside every `npm create cartbase` scaffold under `docs/`, and online at
+your store's docs site. Start with *Build a storefront — the runbook*.
+
+## License
+
+MIT © Cartbase