create-magic-storefront 0.1.0

package/template/lib/errors.ts

@@ -0,0 +1,9 @@
+import { MagicStoreError } from '@magicstoreai/hydrogen';
+
+/** What to tell the buyer: the API's localized detail when there is one. */
+export function describe(
+  error: unknown,
+  fallback = 'Something went wrong. Please try again.',
+): string {
+  return error instanceof MagicStoreError ? (error.detail ?? error.message) : fallback;
+}

package/template/lib/upstream.ts

@@ -0,0 +1,12 @@
+/**
+ * Where the Storefront API is: `MAGICSTORE_API_URL` when set (a mock server, a staging API), else
+ * `https://<MAGICSTORE_SHOP_DOMAIN>/api/v2/storefront`.
+ */
+export function upstreamBaseUrl(): string | null {
+  const explicit = process.env.MAGICSTORE_API_URL;
+  if (explicit) {
+    return explicit.replace(/\/+$/, '');
+  }
+  const domain = process.env.MAGICSTORE_SHOP_DOMAIN;
+  return domain ? `https://${domain}/api/v2/storefront` : null;
+}

package/template/llms.txt

@@ -0,0 +1,128 @@
+# MagicStore Storefront SDK
+
+> TypeScript packages for building a storefront on the MagicStore Storefront API v2
+> (`/api/v2/storefront/*`). One backend serves every shop; a storefront only renders what the API
+> returns. Prices, stock, discounts and delivery are the server's — the SDK formats, caches and
+> keeps client state, it never computes them.
+
+Every storefront — hand-written or generated — imports the SDK **only** through these entry points:
+
+| Import                          | What                                                                                                        | Runs                    |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------- |
+| `@magicstoreai/storefront-client` | `createStorefrontClient`: one typed method per API `operationId`, `MagicStoreError`, `paginate`, `Schema<>` | anywhere, no React      |
+| `@magicstoreai/hydrogen`          | React: `MagicStoreProvider`, `useCart`, `useCustomer`, `useWishlist`, `<Money>`, `<Image>`, …               | client (`"use client"`) |
+| `@magicstoreai/hydrogen/core`     | The same state without React: `CartController`, `CustomerSessionController`, `formatMoney`, variants        | anywhere                |
+| `@magicstoreai/hydrogen/server`   | `nextCacheFetch` (cache tags), `createWebhookHandler` (signed webhooks → revalidation)                      | server, edge            |
+| `@magicstoreai/hydrogen/seo`      | `pageMeta`, `productJsonLd`, `breadcrumbJsonLd`, `jsonLdScript`                                             | anywhere                |
+
+Never import from `src/` or `dist/` of a package, and never call `/api/v2/storefront/…` by URL —
+call the client method. `npx create-magic-storefront check` fails on either.
+
+## Start
+
+```bash
+npm create magic-storefront@latest my-shop -- --shop shop.example.uz
+```
+
+scaffolds a Next.js App Router storefront (home from the merchant's sections, catalog, product,
+search, cart, checkout, sign-in, orders, SEO, webhook revalidation). Or install the packages:
+`npm i @magicstoreai/storefront-client @magicstoreai/hydrogen`.
+
+## Docs
+
+- `PAGES.md` (in a scaffolded storefront; `examples/starter/PAGES.md` in the SDK repository): how to
+  build each page type — home from the `/home` sections, collection, product, search, cart,
+  checkout, account — with its data calls, cache tags, SEO and required states.
+- [Hydrogen catalogue](node_modules/@magicstoreai/hydrogen/CATALOGUE.md): every export with its props
+  or signature, an example, and the API operations it calls. In the SDK repository:
+  `packages/hydrogen/CATALOGUE.md`.
+- [Client README](node_modules/@magicstoreai/storefront-client/README.md): options, headers,
+  idempotency, retries, errors, pagination.
+- [Hydrogen README](node_modules/@magicstoreai/hydrogen/README.md): provider, hooks, server helpers.
+- The API itself (normative): the backend repository's `docs/api/v2/` — `standards.md` (wire format,
+  every error code), `authentication.md`, `cart.md`, `checkout.md`, `customer.md`, `webhooks.md`.
+  Operation shapes: `Schema<'Name'>` and the client's method types, generated from the OpenAPI spec.
+
+## Two credentials
+
+- **Which shop** — a storefront access token (`storefrontToken`, header `X-Storefront-Token`), or
+  else the request host must be one of the shop's domains. A token may list browser origins; from
+  any other origin the API answers `ORIGIN_NOT_ALLOWED`. Without a token for the browser, proxy
+  browser calls through your own server (the starter's `app/storefront-api/[...path]`).
+- **Which customer** — a customer session: access token (60 min) + refresh token (30 days,
+  single-use), only on customer routes. `useCustomer()` signs in (OTP, Telegram, OQ, Click),
+  refreshes and signs out; `MagicStoreProvider` keeps the session in storage.
+
+Public catalog reads need no customer. Render them on the server with a client whose `fetch` is
+`nextCacheFetch()` so the webhook can revalidate them by tag.
+
+## Wire rules
+
+- Money is `{ amount: "12500.00", currencyCode }` — a decimal **string**, already rounded. Render it
+  with `<Money>` / `formatMoney` (the shop's `moneyFormat`); never parse it to a float, add it up
+  or round it again. Totals come from the cart and the checkout.
+- Every `id` and `*Id` is a string. Enums are `UPPER_SNAKE_CASE`. Links use `handle`.
+- Lists paginate with `page` + `perPage` (default 24, max 100); read `meta.pagination`, or
+  `<Pagination>`. Sorts order (`sort=-createdAt`), filters narrow (`filter[onSale]=true`).
+- A missing value is `null`, never `0` or `""`: show a fallback.
+- The home page is `GET /home`: an ordered list of sections, one `type` each
+  (`GET /theme/section-schema` has every type's JSON Schema). Render an unknown type as nothing.
+
+## Credentials in the browser
+
+The cart id and the checkout id are credentials. Never log them and never put them in a URL or
+query string. A guest proves an order with the `X-Checkout-Id` header. The same goes for tokens,
+OTP codes and full phone numbers.
+
+## Cart → checkout → payment
+
+1. The first `useCart().addLine(…)` creates the cart; its id is stored for you. Every cart answer
+   is fully priced: render `cart.cost`, never compute totals. Availability on the cart is soft —
+   there is no stock reservation; stock is taken at checkout completion.
+2. Signing in may move the lines into the customer's cart (a new cart id) — the provider handles it.
+3. `checkoutsStore({ body: { cartId } })` is safe to repeat; drive the form from `checkout.missing`
+   (contact, address or pickup point, delivery option, payment method).
+4. Delivery options are quotes: after any change to the address, pickup point or cart, list them
+   again and select by `id`.
+5. `checkoutsCompletion` needs an `Idempotency-Key` — the client adds one. Retrying the same
+   purchase, pass the same key: `client.checkoutsCompletion(input, { idempotencyKey })` with the
+   failed call's `error.idempotencyKey`; the same key never places a second order.
+6. After the payment page, read `ordersPayment` for the real status; never trust the redirect.
+
+## Errors → what the buyer sees
+
+Every failure is a `MagicStoreError`. Branch on `error.code`, show `error.detail` (localized, safe
+for buyers), quote `error.requestId` when reporting. GET calls retry on 429 / 5xx by themselves.
+
+| `code`                                           | Do                                                           |
+| ------------------------------------------------ | ------------------------------------------------------------ |
+| `NOT_FOUND`                                      | Render the 404 page.                                         |
+| `VALIDATION_FAILED`                              | Show `errors[].message` next to each `errors[].field`.       |
+| `UNAUTHENTICATED`                                | Sign the customer in again.                                  |
+| `RATE_LIMITED`, `SERVICE_UNAVAILABLE`            | Wait `retryAfter` seconds, then retry.                       |
+| `STORE_UNAVAILABLE`                              | Show "temporarily closed"; browsing still works.             |
+| `STORE_NOT_FOUND`, `STORE_NOT_IDENTIFIED`        | Configuration: wrong domain or token.                        |
+| `ORIGIN_NOT_ALLOWED`                             | Configuration: add the site's origin to the token, or proxy. |
+| `CART_NOT_FOUND`, `CART_CLOSED`                  | Start a new cart (the controller does).                      |
+| `CART_EMPTY`                                     | Back to the cart.                                            |
+| `CART_LINES_UNAVAILABLE`                         | Reload the cart; show each line's `issues`.                  |
+| `CHECKOUT_NOT_READY`                             | Fill in what `checkout.missing` names.                       |
+| `CHECKOUT_CLOSED`                                | Completed: show the order. Expired: start a new checkout.    |
+| `CHECKOUT_IN_PROGRESS`                           | Retry with the same `Idempotency-Key` after `retryAfter`.    |
+| `DELIVERY_QUOTE_EXPIRED`, `DELIVERY_UNAVAILABLE` | List delivery options again; choose another.                 |
+| `DISCOUNT_CODE_REJECTED`                         | Show the reason; remove the code.                            |
+| `PAYMENT_PROVIDER_UNAVAILABLE`                   | Retry with the same key, or offer another payment method.    |
+| `OTP_INVALID`                                    | Let the buyer re-type the code.                              |
+| `OTP_EXPIRED`                                    | Ask for a new code.                                          |
+| `NETWORK_ERROR`, `ABORTED`                       | No answer (client-side): offer to try again.                 |
+
+The full list, with the `meta` each code carries, is in the backend's `docs/api/v2/standards.md`.
+
+## What the SDK does not do
+
+- Compute or round prices, discounts, taxes, delivery fees or stock — the API returns them.
+- Reserve stock, or decide whether a product can be bought — read `availableForSale` and line
+  `issues`.
+- Personalise cached pages: anything personal (`FOR_YOU`, the cart, the customer) is read in the
+  browser or per request, never from a shared cache.
+- Log. The SDK never writes to the console.

package/template/next.config.ts

@@ -0,0 +1,9 @@
+import type { NextConfig } from 'next';
+
+const config: NextConfig = {
+  env: {
+    NEXT_PUBLIC_MAGICSTORE_SHOP_DOMAIN: process.env.MAGICSTORE_SHOP_DOMAIN ?? '',
+  },
+};
+
+export default config;

package/template/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "magic-storefront-starter",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@magicstoreai/hydrogen": "workspace:*",
+    "@magicstoreai/storefront-client": "workspace:*",
+    "next": "^16.3.6",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "server-only": "^0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "typescript": "5.9.3"
+  }
+}

package/template/tsconfig.json

@@ -0,0 +1,33 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["dom", "dom.iterable", "ES2022"],
+    "strict": true,
+    "noEmit": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "skipLibCheck": true,
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./*"]
+    },
+    "allowJs": true,
+    "esModuleInterop": true
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}