create-cartbase 0.1.20 → 0.1.21

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Cartbase
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Cartbase
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,25 +1,25 @@
-# create-cartbase
-
-Scaffold a storefront on the [Cartbase](https://cartbase.net) commerce
-platform. One input: your store's publishable key, handed out on the
-**Storefront** page of your Cartbase admin.
-
-```bash
-npx create-cartbase@latest my-store --key pk_…
-# or
-npm create cartbase my-store -- --key pk_…
-bun create cartbase my-store --key pk_…
-```
-
-You get a working Next.js storefront wired to your store through
-`@cartbase/storefront`, styled, with the **complete platform docs
-included in `docs/`** and a `CLAUDE.md` brief. Hand the folder to a
-coding agent and it has everything it needs offline. `--url` points the
-app at a local or staging platform; without it the app talks to the
-platform. Deploy with the
-[`cartbase`](https://www.npmjs.com/package/cartbase) CLI: `cartbase login`,
-then `cartbase deploy`.
-
-Run it in a folder of its own. Inside an existing project, Next.js takes
-that project's folder as the workspace root; the scaffold notices and
-prints the one line to add to `next.config.ts` if that is what you meant.
+# create-cartbase
+
+Scaffold a storefront on the [Cartbase](https://cartbase.net) commerce
+platform. One input: your store's publishable key, handed out on the
+**Storefront** page of your Cartbase admin.
+
+```bash
+npx create-cartbase@latest my-store --key pk_…
+# or
+npm create cartbase my-store -- --key pk_…
+bun create cartbase my-store --key pk_…
+```
+
+You get a working Next.js storefront wired to your store through
+`@cartbase/storefront`, styled, with the **complete platform docs
+included in `docs/`** and a `CLAUDE.md` brief. Hand the folder to a
+coding agent and it has everything it needs offline. `--url` points the
+app at a local or staging platform; without it the app talks to the
+platform. Deploy with the
+[`cartbase`](https://www.npmjs.com/package/cartbase) CLI: `cartbase login`,
+then `cartbase deploy`.
+
+Run it in a folder of its own. Inside an existing project, Next.js takes
+that project's folder as the workspace root; the scaffold notices and
+prints the one line to add to `next.config.ts` if that is what you meant.

package/dist/index.js

@@ -53,13 +53,13 @@ function envFile(input) {
 function main() {
     const { dir, flags } = parseArgs(process.argv.slice(2));
     if (!dir || flags.get("help") === true) {
-        console.log(`create-cartbase — scaffold a Cartbase storefront
-
-Usage:
-  npx create-cartbase@latest <directory> --key <pk_…>
-
-The key is your store's publishable key (Cartbase admin, Storefront page).
-Given as a flag it is written into .env.local; otherwise a placeholder is.
+        console.log(`create-cartbase — scaffold a Cartbase storefront
+
+Usage:
+  npx create-cartbase@latest <directory> --key <pk_…>
+
+The key is your store's publishable key (Cartbase admin, Storefront page).
+Given as a flag it is written into .env.local; otherwise a placeholder is.
 --url points at a local or staging platform; the default is the platform.`);
         process.exitCode = dir ? 0 : 1;
         return;
@@ -86,21 +86,21 @@ Given as a flag it is written into .env.local; otherwise a placeholder is.
     // A store scaffolded inside another project inherits that project's
     // workspace root in Next's eyes; said once, here, while it is cheap to move.
     const enclosing = findEnclosingProject(target);
-    console.log(`
-Created ${path.basename(target)}/
-
-Next steps:
-  cd ${dir}
+    console.log(`
+Created ${path.basename(target)}/
+
+Next steps:
+  cd ${dir}
   bun install        (or npm install)${key
         ? ""
-        : `
-  open .env.local and paste your store's publishable key
-    (Cartbase admin, Storefront page)`}
-  bun run dev
-
-The complete storefront reference is in docs/ — hand CLAUDE.md (or
-AGENTS.md) to your coding agent and it has everything. Deploy with the
-Cartbase CLI: cartbase login, then cartbase deploy.
+        : `
+  open .env.local and paste your store's publishable key
+    (Cartbase admin, Storefront page)`}
+  bun run dev
+
+The complete storefront reference is in docs/ — hand CLAUDE.md (or
+AGENTS.md) to your coding agent and it has everything. Deploy with the
+Cartbase CLI: cartbase login, then cartbase deploy.
 ${enclosing ? `\n${enclosingProjectNote(target, enclosing)}\n` : ""}`);
 }
 main();

package/package.json

@@ -1,24 +1,24 @@
-{
-  "name": "create-cartbase",
-  "version": "0.1.20",
-  "description": "Scaffold a Cartbase storefront: npm create cartbase my-store",
-  "license": "MIT",
-  "type": "module",
-  "bin": {
-    "create-cartbase": "./dist/index.js"
-  },
-  "files": [
-    "dist",
-    "template"
-  ],
-  "scripts": {
-    "build": "bun scripts/build-template.mjs && tsc -p tsconfig.json",
-    "prepack": "bun scripts/build-template.mjs && tsc -p tsconfig.json"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "devDependencies": {
-    "typescript": "^5"
-  }
-}
+{
+  "name": "create-cartbase",
+  "version": "0.1.21",
+  "description": "Scaffold a Cartbase storefront: npm create cartbase my-store",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "create-cartbase": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "build": "bun scripts/build-template.mjs && tsc -p tsconfig.json",
+    "prepack": "bun scripts/build-template.mjs && tsc -p tsconfig.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  }
+}

package/template/app/docs/auth.md

@@ -1,105 +1,105 @@
-# Auth
-
-Passwordless email-code login (customer-accounts card, Shopify Customer
-Account API direction). Two calls: **request** emails a 6-digit code,
-**verify** exchanges it for a session. Password login
-(`supabase.auth.signInWithPassword` client-side) stays available and yields
-an equivalent JWT — nothing here is needed for it.
-
-## The session discipline (one rule)
-
-`verify` mints a **real Supabase session**. Its `access_token` is the SAME
-`authorization: Bearer <jwt>` every `/api/store/*` route accepts — wire it
-into `StorefrontClient` once and every customer surface (customers/me,
-orders, documents, cart attach) is authenticated:
-
-```jsonc
-// new StorefrontClient({ baseUrl, clientId, getAuthToken: () => storedAccessToken })
-```
-
-Persist `access_token` + `refresh_token`; refresh client-side with the
-Supabase SDK (`setSession` → `refreshSession`) — the Cartbase API does not
-proxy token refresh. `expires_in` is seconds; `expires_at` epoch-seconds.
-
-## Server-enforced security posture (the SDK adds nothing)
-
-- Request NEVER reveals whether the email is registered — `{ok: true}`
-  always (no enumeration oracle). The code exists ONLY in the sent email.
-- Codes: hashed at rest, TTL **10 min**, single-use, one live code per
-  email (a new request supersedes prior codes), **5-wrong-attempt lockout**.
-- Rate limits per 15-min window: **5 requests per email**, **20 per IP** →
-  `429 rate_limited` — the only distinguishable request failure.
-- Every verify failure — wrong code, expired, consumed, locked out, unknown
-  email — is the SAME `401 invalid_code`.
-
-## POST /api/store/auth/code/request — step 1
-
-- **Purpose**: email a 6-digit one-time login code. First-time emails
-  register lazily at VERIFY, not here.
-- **Auth**: anon (`x-client-id` only).
-- **Request**: `{email: string}`.
-- **Response**: `{ok: true}` — always, by design.
-- **Errors**: `429 rate_limited` · `400 validation_failed` (malformed
-  email) · `400 missing_client_id`.
-- **SDK**: `auth.requestLoginCode(client, {email})`
-- **Components**: login form (account pages family).
-- **Settings**: the `auth-code` notification template carries the code.
-
-```bash
-# The request contract: {ok:true}, nothing else — no code echo, no
-# registered-or-not oracle. RUN-stamped email → no rate-limit collisions.
-curl -sf -X POST "$BASE/api/store/auth/code/request" \
-  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
-  -d '{"email": "doc-auth-'$RUN'@doc.test"}' \
-  | grep -q '^{"ok":true}$'
-```
-
-## POST /api/store/auth/code/verify — step 2
-
-- **Purpose**: exchange (email, code) for a session. This is ALSO
-  passwordless **registration** — a first-time email lazy-creates the
-  customer (`account_status` per store policy) and triggers the welcome
-  email.
-- **Auth**: anon (`x-client-id` only).
-- **Request**: `{email: string, code: string}` — code is exactly 6 digits
-  (leading zeros count; any other shape → `400 validation_failed`).
-- **Response**:
-
-```jsonc
-{
-  "access_token": "eyJ…",        // the Bearer JWT for every store route
-  "refresh_token": "…",
-  "expires_in": 3600,             // seconds
-  "expires_at": 1789300000,       // epoch seconds (may be absent)
-  "token_type": "bearer",
-  "customer": { /* full customer + addresses — see customers.md */ }
-}
-```
-
-- **Errors**: `401 invalid_code` (every auth failure, generic) ·
-  `400 validation_failed` · `400 missing_client_id`.
-- **SDK**: `auth.verifyLoginCode(client, {email, code})`
-- **Components**: code-entry form (account pages family).
-- **Settings**: store approval policy (new-customer `account_status`);
-  `account-welcome` template.
-
-```bash
-# The 401 invalid_code contract — a well-formed but wrong code against the
-# RUN-stamped email (its real code lives only in the email we never read).
-STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
-  -X POST "$BASE/api/store/auth/code/verify" \
-  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
-  -d '{"email": "doc-auth-'$RUN'@doc.test", "code": "000000"}')
-test "$STATUS" = 401
-curl -s -X POST "$BASE/api/store/auth/code/verify" \
-  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
-  -d '{"email": "doc-auth-'$RUN'@doc.test", "code": "000000"}' \
-  | grep -q '"code":"invalid_code"'
-```
-
-> Cleanup note: the code rows this doc creates are single-per-run
-> (RUN-stamped email), superseded on any later request and dead after the
-> 10-minute TTL — there is no store-surface delete for them by design (they
-> are the auth trail). The happy-path session mint is exercised with a real
-> inbox-free code by `tests/store/customer-accounts-auth.test.ts` and the
-> SDK contract test (server-side code issue via the lib).
+# Auth
+
+Passwordless email-code login (customer-accounts card, Shopify Customer
+Account API direction). Two calls: **request** emails a 6-digit code,
+**verify** exchanges it for a session. Password login
+(`supabase.auth.signInWithPassword` client-side) stays available and yields
+an equivalent JWT — nothing here is needed for it.
+
+## The session discipline (one rule)
+
+`verify` mints a **real Supabase session**. Its `access_token` is the SAME
+`authorization: Bearer <jwt>` every `/api/store/*` route accepts — wire it
+into `StorefrontClient` once and every customer surface (customers/me,
+orders, documents, cart attach) is authenticated:
+
+```jsonc
+// new StorefrontClient({ baseUrl, clientId, getAuthToken: () => storedAccessToken })
+```
+
+Persist `access_token` + `refresh_token`; refresh client-side with the
+Supabase SDK (`setSession` → `refreshSession`) — the Cartbase API does not
+proxy token refresh. `expires_in` is seconds; `expires_at` epoch-seconds.
+
+## Server-enforced security posture (the SDK adds nothing)
+
+- Request NEVER reveals whether the email is registered — `{ok: true}`
+  always (no enumeration oracle). The code exists ONLY in the sent email.
+- Codes: hashed at rest, TTL **10 min**, single-use, one live code per
+  email (a new request supersedes prior codes), **5-wrong-attempt lockout**.
+- Rate limits per 15-min window: **5 requests per email**, **20 per IP** →
+  `429 rate_limited` — the only distinguishable request failure.
+- Every verify failure — wrong code, expired, consumed, locked out, unknown
+  email — is the SAME `401 invalid_code`.
+
+## POST /api/store/auth/code/request — step 1
+
+- **Purpose**: email a 6-digit one-time login code. First-time emails
+  register lazily at VERIFY, not here.
+- **Auth**: anon (`x-client-id` only).
+- **Request**: `{email: string}`.
+- **Response**: `{ok: true}` — always, by design.
+- **Errors**: `429 rate_limited` · `400 validation_failed` (malformed
+  email) · `400 missing_client_id`.
+- **SDK**: `auth.requestLoginCode(client, {email})`
+- **Components**: login form (account pages family).
+- **Settings**: the `auth-code` notification template carries the code.
+
+```bash
+# The request contract: {ok:true}, nothing else — no code echo, no
+# registered-or-not oracle. RUN-stamped email → no rate-limit collisions.
+curl -sf -X POST "$BASE/api/store/auth/code/request" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"email": "doc-auth-'$RUN'@doc.test"}' \
+  | grep -q '^{"ok":true}$'
+```
+
+## POST /api/store/auth/code/verify — step 2
+
+- **Purpose**: exchange (email, code) for a session. This is ALSO
+  passwordless **registration** — a first-time email lazy-creates the
+  customer (`account_status` per store policy) and triggers the welcome
+  email.
+- **Auth**: anon (`x-client-id` only).
+- **Request**: `{email: string, code: string}` — code is exactly 6 digits
+  (leading zeros count; any other shape → `400 validation_failed`).
+- **Response**:
+
+```jsonc
+{
+  "access_token": "eyJ…",        // the Bearer JWT for every store route
+  "refresh_token": "…",
+  "expires_in": 3600,             // seconds
+  "expires_at": 1789300000,       // epoch seconds (may be absent)
+  "token_type": "bearer",
+  "customer": { /* full customer + addresses — see customers.md */ }
+}
+```
+
+- **Errors**: `401 invalid_code` (every auth failure, generic) ·
+  `400 validation_failed` · `400 missing_client_id`.
+- **SDK**: `auth.verifyLoginCode(client, {email, code})`
+- **Components**: code-entry form (account pages family).
+- **Settings**: store approval policy (new-customer `account_status`);
+  `account-welcome` template.
+
+```bash
+# The 401 invalid_code contract — a well-formed but wrong code against the
+# RUN-stamped email (its real code lives only in the email we never read).
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  -X POST "$BASE/api/store/auth/code/verify" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"email": "doc-auth-'$RUN'@doc.test", "code": "000000"}')
+test "$STATUS" = 401
+curl -s -X POST "$BASE/api/store/auth/code/verify" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" \
+  -d '{"email": "doc-auth-'$RUN'@doc.test", "code": "000000"}' \
+  | grep -q '"code":"invalid_code"'
+```
+
+> Cleanup note: the code rows this doc creates are single-per-run
+> (RUN-stamped email), superseded on any later request and dead after the
+> 10-minute TTL — there is no store-surface delete for them by design (they
+> are the auth trail). The happy-path session mint is exercised with a real
+> inbox-free code by `tests/store/customer-accounts-auth.test.ts` and the
+> SDK contract test (server-side code issue via the lib).

package/template/app/docs/carts.md

@@ -47,10 +47,20 @@ SDK module: `@cartbase/storefront/api/carts`.
 ```
 
 - **Response** — `201 {cart}` (decorated shape below).
+- **Limits**: `items` carries at most **100** entries and `promo_codes` at
+  most **10**. A longer array is `400 validation_failed`, never a silent
+  trim.
 - **Errors** — 400 `validation_failed` | `invalid_region` | `region_required`
   (no `region_id` and no store default) | `invalid_sales_channel` (channel
   outside the publishable key's scope) | `price_not_found` (an initial item
   has no price in the cart currency); 404 `variant_not_found`.
+
+> **A saved basket longer than 100 lines.** The browser's basket is the
+> shopper's, and it can outlive any cart, so restore it in two moves: send
+> the first 100 entries in `items`, then add the remainder one at a time
+> through `POST /carts/:id/line-items`. A cart itself holds 100 lines, so an
+> add past that answers `400 cart_item_limit` and the storefront tells the
+> shopper which lines did not fit rather than dropping them without a word.
 - **SDK** — `carts.createCart(client, input)`.
 - **Components** — cart drawer / add-to-cart buttons.
 - **Settings** — store default region (`stores.default_region_id`); enabled
@@ -227,12 +237,18 @@ test "$STATUS" = 401
   the storefront never computes it. The line comes back with
   `selling_plan_id` set.
 - **Response** — `200 {cart}`.
+- **Limits**: a cart holds at most **100** lines. An add that would create
+  the 101st is `400 cart_item_limit` with `details {limit, lines}`; bumping
+  the quantity of a line the cart already holds is not a new line and is
+  never refused. The cap holds under concurrent adds too: when several adds
+  race for the last free line, one lands and the others answer
+  `400 cart_item_limit`, so show that message rather than retrying.
 - **Errors** — 404 `cart_not_found` | `variant_not_found`; 409
   `cart_completed`; 400 `insufficient_inventory` (kit-aware — every linked
   inventory component is checked; `details` carries `{variant_id,
-  inventory_item_id, available, requested}`) | `price_not_found` |
-  `invalid_selling_plan` (unknown, disabled, or not attached to this
-  product) | `validation_failed`.
+  inventory_item_id, available, requested}`) | `cart_item_limit` |
+  `price_not_found` | `invalid_selling_plan` (unknown, disabled, or not
+  attached to this product) | `validation_failed`.
 - **SDK** — `carts.addLineItem(client, cartId, input)`.
 - **Components** — PDP add-to-cart, cart drawer upsell.
 - **Settings** — B2B price lists (cart customer's groups); gift-card
@@ -306,7 +322,10 @@ curl -sf -X DELETE "$BASE/api/store/carts/$CART_ID/line-items/$LINE_ID" \
   their own — only coded ones travel through here).
 - **Auth** — anon `x-client-id`.
 - **Request** — `{promo_codes: string[]}` on BOTH verbs (the DELETE reads
-  its body, not query params).
+  its body, not query params). At most **10** codes per call
+  (`MAX_PROMO_CODES`); a longer array is `400 validation_failed` on both
+  verbs. More than ten codes on one cart is more than any campaign stacks,
+  so send them in calls of ten if a saved cart ever carries more.
 - **Response** — `200 {cart}` (decorated; `cart.promotions` is the raw
   pivot embed `[{promotion: {...}}]`). Unknown codes on REMOVE silently
   no-op by design; on ADD they error.