create-magic-storefront 0.1.3 → 0.2.0

package/template/llms.txt

@@ -11,12 +11,15 @@ Every storefront — hand-written or generated — imports the SDK **only** thro
 | ------------------------------- | ----------------------------------------------------------------------------------------------------------- | ----------------------- |
 | `@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/core`     | The same state without React: `CartController`, `CustomerSessionController`, `formatMoney`, variants, blog | anywhere                |
 | `@magicstoreai/hydrogen/server`   | `nextCacheFetch` (cache tags), `createWebhookHandler` (signed webhooks → revalidation)                      | server, edge            |
-| `@magicstoreai/hydrogen/seo`      | `pageMeta`, `productJsonLd`, `breadcrumbJsonLd`, `jsonLdScript`                                             | anywhere                |
+| `@magicstoreai/hydrogen/seo`      | `pageMeta`, `productJsonLd`, `articleMeta`, `articleJsonLd`, `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.
+call the client method. A server component takes only components (`<Image>`, `<Money>`, …) from
+`@magicstoreai/hydrogen`, a client module; functions and classes (`paginationState`,
+`MagicStoreError`, `formatMoney`) come from `/core`, `/server`, `/seo` or
+`@magicstoreai/storefront-client`. `npx create-magic-storefront check` fails on any of these.
 
 ## Start
 
@@ -25,14 +28,14 @@ npm create magic-storefront@latest my-shop -- --shop shop.example.uz
 ```
 
 scaffolds a Next.js App Router storefront (home from the merchant's sections or your own, catalog,
-product, search, cart, checkout, sign-in, orders, SEO, webhook revalidation). Or install the packages:
+product, search, blog, 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 or custom), collection, product, search,
-  cart, checkout, account — with its data calls, cache tags, SEO and required states.
+  blog, 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`.
@@ -40,7 +43,8 @@ product, search, cart, checkout, sign-in, orders, SEO, webhook revalidation). Or
   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`.
+  every error code), `authentication.md`, `cart.md`, `checkout.md`, `customer.md`, `blog.md`,
+  `webhooks.md`.
   Operation shapes: `Schema<'Name'>` and the client's method types, generated from the OpenAPI spec.
 
 ## Two credentials
@@ -70,6 +74,26 @@ Public catalog reads need no customer. Render them on the server with a client w
   merchant arrange the page from the admin, or compose a custom home from catalog and content
   data. When you render it, an unknown type renders as nothing.
 
+## Blog
+
+- Only when `shop.features.blog` is on: at least one article is readable in the response language.
+  `shop.blog` is the blog home's `{ title, description }` or `null`.
+- `blogArticlesIndex` (12 a page; `sort`, `q`, `filter[category|author|tag|featured]`),
+  `blogArticlesShow`, `blogArticlesRelated`, `blogCategoriesIndex`, `blogAuthorsIndex`. An unknown
+  `sort` or filter is `422 VALIDATION_FAILED`, never ignored.
+- Articles are strict about language: one not written in the response locale is a `404`, with no
+  fallback. Build `hreflang` only from `availableLocales` (`articleMeta` does).
+- `bodyHtml` is sanitized by the server. Split it with `articleBodyBlocks()` (`/core`, server-safe):
+  `<product-embed handle>` → a product card, `<oembed url>` → media, `<aside data-callout>` → a
+  callout. Fetch the embedded products in one `productsIndex({ query: { 'filter[handles]' } })` per
+  `embeddedProductFilters(article.products)` value, put them back in order with
+  `orderEmbeddedProducts`, and drop a marker whose product did not come back.
+- «Was this helpful?»: `useArticleVote(handle, helpfulCount)`. A guest votes as the browser
+  (`X-Anonymous-Id`, `anonymousId()`), a customer as themselves. Report reads with
+  `useAnalytics().articleView(article.id)` (`ARTICLE_VIEW`).
+- Blog reads are cached under `magicstore:pages` (`PAGES_UPDATED`); view and vote counters may be
+  up to 10 minutes old.
+
 ## Credentials in the browser
 
 The cart id and the checkout id are credentials. Never log them and never put them in a URL or