create-cartbase 0.1.0 → 0.1.2

package/dist/index.js

@@ -68,9 +68,9 @@ as flags they are written into .env.local, otherwise placeholders are.`);
     const key = typeof flags.get("key") === "string" ? flags.get("key") : "";
     fs.writeFileSync(path.join(target, ".env.local"), [
         "# Your store's inputs — Cartbase admin, Settings.",
-        `NEXT_PUBLIC_BARTER_URL=${url}`,
-        `NEXT_PUBLIC_BARTER_CLIENT_ID=${clientId}`,
-        `NEXT_PUBLIC_BARTER_PUBLISHABLE_KEY=${key}`,
+        `NEXT_PUBLIC_CARTBASE_URL=${url}`,
+        `NEXT_PUBLIC_CARTBASE_CLIENT_ID=${clientId}`,
+        `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY=${key}`,
         "",
     ].join("\n"));
     const filled = url && clientId;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cartbase",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Scaffold a Cartbase storefront: npm create cartbase my-store",
   "license": "MIT",
   "type": "module",

package/template/app/docs/BUILD-A-STOREFRONT.md

@@ -1,4 +1,4 @@
-# Build a storefront — the runbook
+# Build a storefront
 
 **This runbook takes you from a blank Next.js app to a completed checkout
 against your Cartbase store.** It is written to be followed by a developer
@@ -12,9 +12,9 @@ What you need before starting (all three are in your Cartbase admin under
 
 | Input | Example | Where it goes |
 |---|---|---|
-| API origin | `https://admin.bitfar.co` | `NEXT_PUBLIC_BARTER_URL` |
-| Store client id | `1e7a4c02-9b31-4f7e-8d2a-5c6f90ab12cd` (uuid) | `NEXT_PUBLIC_BARTER_CLIENT_ID` |
-| Publishable API key | `pk_…` (optional, channel scope) | `NEXT_PUBLIC_BARTER_PUBLISHABLE_KEY` |
+| API origin | `https://admin.bitfar.co` | `NEXT_PUBLIC_CARTBASE_URL` |
+| Store client id | `1e7a4c02-9b31-4f7e-8d2a-5c6f90ab12cd` (uuid) | `NEXT_PUBLIC_CARTBASE_CLIENT_ID` |
+| Publishable API key | `pk_…` (optional, channel scope) | `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY` |
 
 Sanity-check the store before writing any code:
 
@@ -73,7 +73,7 @@ whole checkout orchestration) only work same-origin. Unless your
 storefront is served from the Cartbase deployment origin itself, proxy the
 store surface through your own origin — in Next.js one rewrite does it —
 and give the BROWSER client `window.location.origin` as `baseUrl`
-(server-side calls hit `NEXT_PUBLIC_BARTER_URL` directly and are
+(server-side calls hit `NEXT_PUBLIC_CARTBASE_URL` directly and are
 unaffected; see `examples/storefront/next.config.ts` for the working
 rewrite):
 
@@ -81,7 +81,7 @@ rewrite):
 // next.config.ts — proxy browser SDK traffic to the API origin
 async rewrites() {
   return [{ source: "/api/store/:path*",
-            destination: `${process.env.NEXT_PUBLIC_BARTER_URL}/api/store/:path*` }]
+            destination: `${process.env.NEXT_PUBLIC_CARTBASE_URL}/api/store/:path*` }]
 }
 ```
 

package/template/app/docs/README.md

@@ -1,76 +1,77 @@
-# docs/storefront/ — the bulletproof storefront docs
-
-**Audience: an AGENT building a storefront from a blank Next.js app.** These
-docs are the entire knowledge transfer — every call shape, every curl, every
-setting, every component contract. If a storefront can't be built from these
-files alone, the fix is a doc fix, never tribal knowledge.
-
-Start at **[BUILD-A-STOREFRONT.md](BUILD-A-STOREFRONT.md)** — the runbook.
-Domain files below are its reference chapters.
-
-## Executable-docs contract (docs-truth CI)
-
-Docs that can lie aren't bulletproof, so every ```bash block in every file
-here is **extracted and executed** against the real test server by
-`tests/docs/storefront-curls.test.ts`. A drifted doc FAILS the build.
-
-Rules for doc authors (agents included):
-
-1. All ```bash blocks in one file form ONE script, executed top-to-bottom
-   with `bash -euo pipefail`. Later blocks may use variables exported by
-   earlier blocks (`CART_ID=$(curl … | grep -o …)`).
-2. The harness pre-exports: `BASE` (test-server origin), `CLIENT_ID` (dev
-   tenant id), `PUBLISHABLE_KEY` (the B2B-channel dev key — channel-scoped,
-   use only where the doc discusses key scoping).
-3. Every curl uses `-sf` (silent + fail-on-HTTP-error) unless the block
-   demonstrates an error case — then capture the status explicitly
-   (`-o /dev/null -w '%{http_code}'`) and assert it (`test "$STATUS" = 404`).
-4. Assert shape, not just liveness: pipe to `grep -q '"key"'` (or `node -e`
-   for anything structural). A block that checks nothing proves nothing.
-5. A block that must NOT run (illustrative only, external side effects)
-   starts with `# doc-noexec` on its first line. Use sparingly — every
-   noexec block is a hole in the truth gate.
-6. Blocks must be idempotent-safe on the shared dev tenant: create what you
-   read, suffix names with `$RUN` (pre-exported unique stamp), and clean up
-   in a final block when you created durable rows.
-
-## Per-domain file format
-
-One file per domain. For each endpoint, in order:
-
-- **Purpose** — one sentence, when a storefront calls it.
-- **Auth** — which headers (anon `x-client-id` / publishable key / Bearer).
-- **Request** — method, path, query/body shape (jsonc block).
-- **Response** — shape (jsonc block), with field notes.
-- **Working curl** — executable per the contract above.
-- **Errors** — status + `code` for every contract-listed failure.
-- **SDK** — the `@cartbase/storefront/api` function that wraps it.
-- **Components** — which `@cartbase/storefront` UI components consume it.
-- **Settings** — admin settings that change its behavior (checkout rules,
-  locales, consent, accounts mode…).
-
-## Files
-
-| File | Domain |
-|---|---|
-| [BUILD-A-STOREFRONT.md](BUILD-A-STOREFRONT.md) | The agent runbook — blank app → completed checkout |
-| [products.md](products.md) | Products, variants, pricing context |
-| [search.md](search.md) | Search, facets, related products |
-| [collections.md](collections.md) | Collections + membership listings |
-| [categories.md](categories.md) | Categories, tags, types |
-| [regions.md](regions.md) | Regions, currencies, locales |
-| [carts.md](carts.md) | Cart lifecycle + line items |
-| [gift-cards.md](gift-cards.md) | Gift-card tender on carts |
-| [checkout.md](checkout.md) | Shipping options, payment providers/collections, prepare-checkout orchestration, complete |
-| [orders.md](orders.md) | Order reads, display-id lookup, transfers |
-| [customers.md](customers.md) | Customer profile, addresses, documents |
-| [subscriptions.md](subscriptions.md) | Subscription portal: schedule control, contract edits, payment-method recovery |
-| [auth.md](auth.md) | Passwordless code login + session discipline |
-| [content.md](content.md) | Pages + blogs |
-| [menus.md](menus.md) | Navigation menus |
-| [metaobjects.md](metaobjects.md) | Merchant-defined content types |
-| [reviews.md](reviews.md) | Review widget, token wizard, photo rewards |
-| [integrations.md](integrations.md) | Store config: carriers, COD, tracking block, lockers |
-| [consent.md](consent.md) | Consent Mode v2 banner config |
-| [redirects.md](redirects.md) | 404-path URL redirects |
-| [components.md](components.md) | UI component families: contracts + required SDK calls |
+# Storefront docs
+
+**Audience: an AGENT building a storefront from a blank Next.js app.** These
+docs are the entire knowledge transfer — every call shape, every curl, every
+setting, every component contract. If a storefront can't be built from these
+files alone, the fix is a doc fix, never tribal knowledge.
+
+Start at **[BUILD-A-STOREFRONT.md](BUILD-A-STOREFRONT.md)** — the runbook.
+Domain files below are its reference chapters.
+
+## Executable-docs contract (docs-truth CI)
+
+Docs that can lie aren't bulletproof, so every ```bash block in every file
+here is **extracted and executed** against the real test server by
+`tests/docs/storefront-curls.test.ts`. A drifted doc FAILS the build.
+
+Rules for doc authors (agents included):
+
+1. All ```bash blocks in one file form ONE script, executed top-to-bottom
+   with `bash -euo pipefail`. Later blocks may use variables exported by
+   earlier blocks (`CART_ID=$(curl … | grep -o …)`).
+2. The harness pre-exports: `BASE` (test-server origin), `CLIENT_ID` (dev
+   tenant id), `PUBLISHABLE_KEY` (the B2B-channel dev key — channel-scoped,
+   use only where the doc discusses key scoping).
+3. Every curl uses `-sf` (silent + fail-on-HTTP-error) unless the block
+   demonstrates an error case — then capture the status explicitly
+   (`-o /dev/null -w '%{http_code}'`) and assert it (`test "$STATUS" = 404`).
+4. Assert shape, not just liveness: pipe to `grep -q '"key"'` (or `node -e`
+   for anything structural). A block that checks nothing proves nothing.
+5. A block that must NOT run (illustrative only, external side effects)
+   starts with `# doc-noexec` on its first line. Use sparingly — every
+   noexec block is a hole in the truth gate.
+6. Blocks must be idempotent-safe on the shared dev tenant: create what you
+   read, suffix names with `$RUN` (pre-exported unique stamp), and clean up
+   in a final block when you created durable rows.
+
+## Per-domain file format
+
+One file per domain. For each endpoint, in order:
+
+- **Purpose** — one sentence, when a storefront calls it.
+- **Auth** — which headers (anon `x-client-id` / publishable key / Bearer).
+- **Request** — method, path, query/body shape (jsonc block).
+- **Response** — shape (jsonc block), with field notes.
+- **Working curl** — executable per the contract above.
+- **Errors** — status + `code` for every contract-listed failure.
+- **SDK** — the `@cartbase/storefront/api` function that wraps it.
+- **Components** — which `@cartbase/storefront` UI components consume it.
+- **Settings** — admin settings that change its behavior (checkout rules,
+  locales, consent, accounts mode…).
+
+## Files
+
+| File | Domain |
+|---|---|
+| [BUILD-A-STOREFRONT.md](BUILD-A-STOREFRONT.md) | The agent runbook — blank app → completed checkout |
+| [products.md](products.md) | Products, variants, pricing context |
+| [search.md](search.md) | Search, facets, related products |
+| [collections.md](collections.md) | Collections + membership listings |
+| [categories.md](categories.md) | Categories, tags, types |
+| [regions.md](regions.md) | Regions, currencies, locales |
+| [carts.md](carts.md) | Cart lifecycle + line items |
+| [gift-cards.md](gift-cards.md) | Gift-card tender on carts |
+| [checkout.md](checkout.md) | Shipping options, payment providers/collections, prepare-checkout orchestration, complete |
+| [orders.md](orders.md) | Order reads, display-id lookup, transfers |
+| [customers.md](customers.md) | Customer profile, addresses, documents |
+| [subscriptions.md](subscriptions.md) | Subscription portal: schedule control, contract edits, payment-method recovery |
+| [auth.md](auth.md) | Passwordless code login + session discipline |
+| [content.md](content.md) | Pages + blogs |
+| [menus.md](menus.md) | Navigation menus |
+| [metaobjects.md](metaobjects.md) | Merchant-defined content types |
+| [reviews.md](reviews.md) | Review widget, token wizard, photo rewards |
+| [integrations.md](integrations.md) | Store config: carriers, COD, tracking block, lockers |
+| [consent.md](consent.md) | Consent Mode v2 banner config |
+| [redirects.md](redirects.md) | 404-path URL redirects |
+| [components.md](components.md) | UI component families: contracts + required SDK calls |
+| [platform.md](platform.md) | Platform fingerprints: generator meta, window.Cartbase, x-cartbase-version header, cart cookie naming |

package/template/app/docs/auth.md

@@ -1,4 +1,4 @@
-# Auth — passwordless code login + session discipline
+# Auth
 
 Passwordless email-code login (customer-accounts card, Shopify Customer
 Account API direction). Two calls: **request** emails a 6-digit code,

package/template/app/docs/carts.md

@@ -1,4 +1,4 @@
-# Carts — lifecycle + line items
+# Carts
 
 The cart is the storefront's working document: created anonymously, mutated
 through line-item and update calls, completed into an order (see
@@ -118,8 +118,8 @@ test -n "$CART_ID" && test -n "$REGION_ID"
     "item_total": 54, "item_subtotal": 45, "item_tax_total": 9,
     "original_total": 54, "original_subtotal": 45, "original_tax_total": 9,
     "credit_line_total": 0,
-    "cod_fee_total": 0,              // non-zero only with a live pp_cod session + enabled COD integration
-    "cod_fee_label": null,
+    "payment_method_fee_total": 0,              // the selected method's own fee — non-zero only with a live method session
+    "payment_method_fee_label": null,
     // gift-card tender decoration (totals above NEVER move):
     "gift_cards": [],                // [{id, last4, amount}] in apply order
     "gift_card_total": 0,            // Σ applied-card coverage
@@ -305,11 +305,11 @@ curl -sf -X DELETE "$BASE/api/store/carts/$CART_ID/line-items/$LINE_ID" \
   cart promotion and recomputes totals (automatic promotions layer in on
   their own — only coded ones travel through here).
 - **Auth** — anon `x-client-id`.
-- **Request** — `{promo_codes: string[]}` on BOTH verbs (Medusa reads the
-  DELETE body, not query).
+- **Request** — `{promo_codes: string[]}` on BOTH verbs (the DELETE reads
+  its body, not query params).
 - **Response** — `200 {cart}` (decorated; `cart.promotions` is the raw
   pivot embed `[{promotion: {...}}]`). Unknown codes on REMOVE silently
-  no-op (Medusa parity); on ADD they error.
+  no-op by design; on ADD they error.
 - **Errors** — 404 `cart_not_found`; 404 `promotion_not_found` (unknown
   code on add), 400 `promotion_inactive` (draft/expired code on add), 400
   zod (empty array / non-string entries).

package/template/app/docs/categories.md

@@ -1,4 +1,4 @@
-# Categories, tags, types
+# Categories
 
 Taxonomy reads for navigation trees and filter UIs. Categories are
 hierarchical (`parent_category_id`) with optional ancestor/descendant tree