create-magic-storefront 0.1.3 → 0.3.1

package/template/components/article-body.tsx

@@ -0,0 +1,58 @@
+import { articleBodyBlocks, type ArticleBlock } from '@magicstoreai/hydrogen/core';
+import type { Schema } from '@magicstoreai/storefront-client';
+import { ProductCard } from '@/components/product-grid';
+
+type Product = Schema<'Product'>;
+
+/**
+ * An article body (`bodyHtml`, sanitized by the server) with its inert markup turned into
+ * components: product cards from `products` (a marker whose product the list did not return is
+ * dropped), media embeds as links, callouts as boxes.
+ */
+export function ArticleBody({
+  bodyHtml,
+  products,
+}: {
+  bodyHtml: string;
+  products: ReadonlyMap<string, Product>;
+}) {
+  return <Blocks blocks={articleBodyBlocks(bodyHtml)} products={products} />;
+}
+
+function Blocks({
+  blocks,
+  products,
+}: {
+  blocks: ArticleBlock[];
+  products: ReadonlyMap<string, Product>;
+}) {
+  return blocks.map((block, index) => {
+    switch (block.type) {
+      case 'html':
+        return <div key={index} dangerouslySetInnerHTML={{ __html: block.html }} />;
+      case 'product': {
+        const product = products.get(block.handle);
+        return product ? (
+          <div key={index} className="article-product">
+            <ProductCard product={product} />
+          </div>
+        ) : null;
+      }
+      case 'embed':
+        return (
+          <p key={index}>
+            <a href={block.url} target="_blank" rel="noopener nofollow">
+              {block.url}
+            </a>
+          </p>
+        );
+      case 'callout':
+        return (
+          <aside key={index} className="callout" data-callout={block.kind}>
+            {block.title && <strong>{block.title}</strong>}
+            <Blocks blocks={block.blocks} products={products} />
+          </aside>
+        );
+    }
+  });
+}

package/template/components/article-card.tsx

@@ -0,0 +1,54 @@
+import { Image } from '@magicstoreai/hydrogen';
+import type { Schema } from '@magicstoreai/storefront-client';
+import Link from 'next/link';
+import { locale } from '@/lib/api';
+import { messages } from '@/lib/i18n';
+
+type Article = Schema<'BlogArticle'>;
+
+/** A date in the shop's time zone, so a server elsewhere does not move it by a day. */
+export function ArticleDate({ iso, timeZone }: { iso: string; timeZone: string }) {
+  return <time dateTime={iso}>{formatDate(iso, timeZone)}</time>;
+}
+
+function formatDate(iso: string, timeZone: string): string {
+  try {
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeZone }).format(new Date(iso));
+  } catch {
+    // A time zone this runtime does not know: the date in UTC beats a failed page.
+    return new Intl.DateTimeFormat(locale, { dateStyle: 'long', timeZone: 'UTC' }).format(
+      new Date(iso),
+    );
+  }
+}
+
+/** One article as a card: cover, category, title, excerpt, author, date and reading time. */
+export function ArticleCard({ article, timeZone }: { article: Article; timeZone: string }) {
+  const t = messages(locale);
+  return (
+    <Link href={`/blog/${article.handle}`} className="card article-card">
+      <Image data={article.image} alt={article.title} fallback={<div className="noimg" />} />
+      {article.category && <span className="badge">{article.category.title}</span>}
+      <strong>{article.title}</strong>
+      {article.excerpt && <span className="muted">{article.excerpt}</span>}
+      <span className="row muted">
+        {article.authorName && <span>{article.authorName}</span>}
+        <ArticleDate iso={article.publishedAt} timeZone={timeZone} />
+        <span>{t.readingTime(article.readingMinutes)}</span>
+      </span>
+    </Link>
+  );
+}
+
+export function ArticleGrid({ articles, timeZone }: { articles: Article[]; timeZone: string }) {
+  if (articles.length === 0) {
+    return <p className="muted">{messages(locale).nothingHere}</p>;
+  }
+  return (
+    <div className="grid articles">
+      {articles.map((article) => (
+        <ArticleCard key={article.id} article={article} timeZone={timeZone} />
+      ))}
+    </div>
+  );
+}

package/template/components/article-vote.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import { useArticleVote, useMagicStore } from '@magicstoreai/hydrogen';
+import { describe } from '@/lib/errors';
+import { messages } from '@/lib/i18n';
+
+/** «Was this helpful?»: a guest votes as this browser, a signed-in customer as themselves. */
+export function ArticleVote({ handle, helpfulCount }: { handle: string; helpfulCount: number }) {
+  const t = messages(useMagicStore().locale);
+  const vote = useArticleVote(handle, helpfulCount);
+  const choose = (value: 'HELPFUL' | 'NOT_HELPFUL') =>
+    void (vote.viewerVote === value ? vote.clear() : vote.vote(value)).catch(() => undefined);
+
+  return (
+    <section className="stack" aria-live="polite">
+      <strong>{t.wasHelpful}</strong>
+      <div className="row">
+        <button
+          aria-pressed={vote.viewerVote === 'HELPFUL'}
+          disabled={vote.status === 'pending'}
+          onClick={() => choose('HELPFUL')}
+        >
+          {t.helpful}
+        </button>
+        <button
+          aria-pressed={vote.viewerVote === 'NOT_HELPFUL'}
+          disabled={vote.status === 'pending'}
+          onClick={() => choose('NOT_HELPFUL')}
+        >
+          {t.notHelpful}
+        </button>
+        {vote.helpfulCount > 0 && (
+          <span className="muted">{t.helpfulCount(vote.helpfulCount)}</span>
+        )}
+      </div>
+      {vote.error ? (
+        <p className="error">{describe(vote.error, t.tryAgainLater)}</p>
+      ) : (
+        vote.viewerVote !== null && <p className="muted">{t.thanksForVote}</p>
+      )}
+    </section>
+  );
+}

package/template/components/blog-listing.tsx

@@ -0,0 +1,93 @@
+import { MagicStoreError } from '@magicstoreai/storefront-client';
+import Link from 'next/link';
+import { ArticleGrid } from '@/components/article-card';
+import { Pager } from '@/components/pager';
+import { api, locale } from '@/lib/api';
+import { describe } from '@/lib/errors';
+import { messages } from '@/lib/i18n';
+
+export type ArticlesQuery = NonNullable<
+  NonNullable<Parameters<typeof api.blogArticlesIndex>[0]>['query']
+>;
+
+/** 12 a page, the API's default: a blog page reads better short. */
+export const ARTICLES_PER_PAGE = 12;
+
+/**
+ * One page of articles with its pager. A query the API refuses (`422`: an unknown `sort`, a `q`
+ * over 200 characters) shows the API's message instead of failing the page. Articles in
+ * `exclude` (already shown above, e.g. editor's picks) are left out; when that leaves nothing on a
+ * single page, nothing renders — not even `heading`.
+ */
+export async function ArticleListing({
+  query,
+  href,
+  timeZone,
+  exclude = [],
+  heading,
+}: {
+  query: ArticlesQuery;
+  href: (page: number) => string;
+  timeZone: string;
+  exclude?: readonly string[];
+  heading?: string;
+}) {
+  try {
+    const { data, meta } = await api.blogArticlesIndex({
+      query: { perPage: ARTICLES_PER_PAGE, ...query },
+    });
+    const articles = data.filter((article) => !exclude.includes(article.id));
+    if (articles.length === 0 && data.length > 0 && meta.pagination.totalPages <= 1) {
+      return null;
+    }
+    return (
+      <>
+        {heading && <h2>{heading}</h2>}
+        <ArticleGrid articles={articles} timeZone={timeZone} />
+        <Pager meta={meta.pagination} href={href} />
+      </>
+    );
+  } catch (error) {
+    if (error instanceof MagicStoreError && error.code === 'VALIDATION_FAILED') {
+      return <p className="error">{describe(error, messages(locale).tryAgainLater)}</p>;
+    }
+    throw error;
+  }
+}
+
+/** The blog's categories as links; the current one is marked. Nothing when there are none. */
+export async function CategoryNav({ current }: { current?: string }) {
+  const t = messages(locale);
+  const { data: categories } = await api.blogCategoriesIndex();
+  if (categories.length === 0) {
+    return null;
+  }
+  return (
+    <nav className="row chips" aria-label={t.blog}>
+      <Link href="/blog" aria-current={current === undefined ? 'page' : undefined}>
+        {t.allArticles}
+      </Link>
+      {categories.map((category) => (
+        <Link
+          key={category.id}
+          href={`/blog/category/${category.handle}`}
+          aria-current={current === category.handle ? 'page' : undefined}
+        >
+          {category.title} <span className="muted">{category.articlesCount}</span>
+        </Link>
+      ))}
+    </nav>
+  );
+}
+
+const SORTS = ['-publishedAt', 'publishedAt', 'relevance', '-recentViews'] as const;
+
+/** `?sort=` when it is one the API knows; anything else means the default order. */
+export function sortParam(value: string | undefined): ArticlesQuery['sort'] {
+  return SORTS.find((sort) => sort === value);
+}
+
+/** `?page=` as a page number, 1 for anything else. */
+export function pageParam(value: string | undefined): number {
+  return Math.max(1, Number(value) || 1);
+}

package/template/components/pager.tsx

@@ -1,9 +1,15 @@
-import { paginationState, type Pagination } from '@magicstoreai/hydrogen';
+import { paginationState } from '@magicstoreai/hydrogen/core';
+import type { Schema } from '@magicstoreai/storefront-client';
 import Link from 'next/link';
 import { locale } from '@/lib/api';
 import { messages } from '@/lib/i18n';
 
-/** Server-rendered page links (`paginationState` is plain arithmetic, no hooks). */
+type Pagination = Schema<'Pagination'>;
+
+/**
+ * Server-rendered page links. `paginationState` comes from `/core`: the root entry is a client
+ * module, and a server component cannot call its functions.
+ */
 export function Pager({ meta, href }: { meta: Pagination; href: (page: number) => string }) {
   if (meta.totalPages <= 1) {
     return null;

package/template/components/product-grid.tsx

@@ -28,32 +28,39 @@ function ProductBadges({ product }: { product: Schema<'Product'> }) {
   );
 }
 
-export function ProductGrid({ products }: { products: Schema<'Product'>[] }) {
+/** One product as a card: the whole card is one link. */
+export function ProductCard({ product }: { product: Schema<'Product'> }) {
   const t = messages(locale);
+  return (
+    <Link href={`/products/${product.handle}`} className="card">
+      <Image
+        data={product.featuredImage}
+        alt={product.title}
+        fallback={<div className="noimg" />}
+      />
+      <ProductBadges product={product} />
+      <span>{product.title}</span>
+      <span className="row">
+        <Money data={product.price} fallback={<span className="muted">—</span>} />
+        {product.compareAtPrice && (
+          <s className="muted">
+            <Money data={product.compareAtPrice} />
+          </s>
+        )}
+      </span>
+      {!product.availableForSale && <span className="muted">{t.soldOut}</span>}
+    </Link>
+  );
+}
+
+export function ProductGrid({ products }: { products: Schema<'Product'>[] }) {
   if (products.length === 0) {
-    return <p className="muted">{t.nothingHere}</p>;
+    return <p className="muted">{messages(locale).nothingHere}</p>;
   }
   return (
     <div className="grid">
       {products.map((product) => (
-        <Link key={product.id} href={`/products/${product.handle}`} className="card">
-          <Image
-            data={product.featuredImage}
-            alt={product.title}
-            fallback={<div className="noimg" />}
-          />
-          <ProductBadges product={product} />
-          <span>{product.title}</span>
-          <span className="row">
-            <Money data={product.price} fallback={<span className="muted">—</span>} />
-            {product.compareAtPrice && (
-              <s className="muted">
-                <Money data={product.compareAtPrice} />
-              </s>
-            )}
-          </span>
-          {!product.availableForSale && <span className="muted">{t.soldOut}</span>}
-        </Link>
+        <ProductCard key={product.id} product={product} />
       ))}
     </div>
   );

package/template/components/telegram-shell.tsx

@@ -0,0 +1,54 @@
+'use client';
+
+import {
+  useTelegramBackButton,
+  useTelegramSignIn,
+  useTelegramWebApp,
+} from '@magicstoreai/hydrogen';
+import { usePathname, useRouter } from 'next/navigation';
+import { useEffect, useRef } from 'react';
+
+/**
+ * The storefront as a Telegram Mini App. Renders nothing; outside Telegram every hook is a no-op.
+ *
+ * - marks `<html>` with `data-telegram` / `data-color-scheme`, so `globals.css` takes Telegram's
+ *   theme colors;
+ * - shows the header's back arrow on every page but the home page. It goes back only while there is
+ *   history of ours behind the page; on the history entry the Mini App opened on (a deep link from
+ *   the bot, the return from a payment page) it goes home. Where the browser has the Navigation API
+ *   the entry is told by its history index, so revisiting the first page through a link still goes
+ *   back; elsewhere by its path;
+ * - signs the buyer in with the launch data once per visit — the only automatic Telegram sign-in in
+ *   the app (`/account` offers a manual one). A failure keeps the buyer browsing as a guest;
+ *   `/account` explains it. A referral in the `startapp` parameter is read by the server.
+ */
+export function TelegramShell() {
+  const pathname = usePathname();
+  const router = useRouter();
+  useTelegramWebApp({ documentAttributes: true });
+  // The page the Mini App opened on: history before it is not ours.
+  const entry = useRef<{ pathname: string; index: number | null }>({ pathname, index: null });
+  useEffect(() => {
+    entry.current.index = historyIndex();
+  }, []);
+  useTelegramBackButton(pathname !== '/', () => {
+    const index = historyIndex();
+    const atEntry =
+      index !== null && entry.current.index !== null
+        ? index <= entry.current.index
+        : pathname === entry.current.pathname;
+    if (atEntry) {
+      router.push('/');
+    } else {
+      router.back();
+    }
+  });
+  useTelegramSignIn();
+  return null;
+}
+
+/** The current history entry's index (Navigation API), or null where the browser lacks the API. */
+function historyIndex(): number | null {
+  const { navigation } = window as { navigation?: { currentEntry: NavigationHistoryEntry | null } };
+  return navigation?.currentEntry?.index ?? null;
+}

package/template/lib/errors.ts

@@ -1,6 +1,28 @@
-import { MagicStoreError } from '@magicstoreai/hydrogen';
+// From the client package, not the "use client" hydrogen entry: this runs in server components too.
+import { MagicStoreError } from '@magicstoreai/storefront-client';
 
 /** What to tell the buyer: the API's localized detail when there is one. */
 export function describe(error: unknown, fallback: string): string {
   return error instanceof MagicStoreError ? (error.detail ?? error.message) : fallback;
 }
+
+/**
+ * Why sharing the Telegram phone (`POST /customer/phone-verification`) failed. `CONTACT_EXPIRED`
+ * asks to share again; `CONTACT_INVALID`, `CONTACT_NOT_OWN`, `INVALID_PHONE` and `TAKEN` show the
+ * API's localized message for `telegramContact`; anything else falls back to `describe()`.
+ */
+export function describePhoneShare(
+  error: unknown,
+  text: { sharePhoneAgain: string; tryAgainLater: string },
+): string {
+  if (error instanceof MagicStoreError) {
+    const refusal = error.errors.find((entry) => entry.field === 'telegramContact');
+    if (refusal?.code === 'CONTACT_EXPIRED') {
+      return text.sharePhoneAgain;
+    }
+    if (refusal !== undefined) {
+      return refusal.message;
+    }
+  }
+  return describe(error, text.tryAgainLater);
+}

package/template/lib/i18n.ts

@@ -57,6 +57,22 @@ const en = {
     `${count} ${plural('en', count, { one: 'review', other: 'reviews' })}`,
   recommendUs: (percent: number) => `${percent}% recommend us`,
   leaveReview: 'Leave a review',
+  // Blog
+  blog: 'Blog',
+  allArticles: 'All articles',
+  featured: "Editor's picks",
+  readingTime: (minutes: number) => `${minutes} min read`,
+  relatedArticles: 'Read also',
+  productsInArticle: 'Products in this article',
+  wasHelpful: 'Was this article helpful?',
+  helpful: 'Yes',
+  notHelpful: 'No',
+  helpfulCount: (count: number) => `Helpful for ${count}`,
+  thanksForVote: 'Thank you for your feedback',
+  searchArticles: 'Search articles',
+  sortNewest: 'Newest',
+  sortPopular: 'Popular',
+  tag: 'Tag',
   // Product
   addToCart: 'Add to cart',
   addedToCart: 'Added to cart.',
@@ -101,6 +117,16 @@ const en = {
   signIn: 'Sign in',
   sendCode: 'Send code',
   smsCode: 'Code from the SMS',
+  // Telegram Mini App
+  signInWithTelegram: 'Sign in with Telegram',
+  signingIn: 'Signing in…',
+  telegramRelaunch:
+    'Your Telegram sign-in has expired. Close the shop and open it again from the bot.',
+  telegramUnavailable: 'Sign-in with Telegram is not available in this shop.',
+  orWithPhone: 'Or sign in with your phone number',
+  sharePhone: 'Share phone number',
+  sharePhoneHint: 'Share your Telegram phone number so the shop can reach you about orders.',
+  sharePhoneAgain: 'That contact has expired. Share it again.',
   signOut: 'Sign out',
   orders: 'Orders',
   loadingOrders: 'Loading orders…',
@@ -156,6 +182,21 @@ const ru: Messages = {
     `${count} ${plural('ru', count, { one: 'отзыв', few: 'отзыва', other: 'отзывов' })}`,
   recommendUs: (percent) => `${percent}% рекомендуют нас`,
   leaveReview: 'Оставить отзыв',
+  blog: 'Блог',
+  allArticles: 'Все статьи',
+  featured: 'Выбор редакции',
+  readingTime: (minutes) => `${minutes} мин чтения`,
+  relatedArticles: 'Читайте также',
+  productsInArticle: 'Товары из статьи',
+  wasHelpful: 'Статья была полезной?',
+  helpful: 'Да',
+  notHelpful: 'Нет',
+  helpfulCount: (count) => `Полезно: ${count}`,
+  thanksForVote: 'Спасибо за отзыв',
+  searchArticles: 'Поиск по статьям',
+  sortNewest: 'Новые',
+  sortPopular: 'Популярные',
+  tag: 'Тег',
   addToCart: 'В корзину',
   addedToCart: 'Добавлено в корзину.',
   couldNotAdd: 'Не удалось добавить в корзину.',
@@ -196,6 +237,14 @@ const ru: Messages = {
   signIn: 'Войти',
   sendCode: 'Получить код',
   smsCode: 'Код из SMS',
+  signInWithTelegram: 'Войти через Telegram',
+  signingIn: 'Входим…',
+  telegramRelaunch: 'Вход через Telegram устарел. Закройте магазин и откройте его снова из бота.',
+  telegramUnavailable: 'Вход через Telegram в этом магазине недоступен.',
+  orWithPhone: 'Или войдите по номеру телефона',
+  sharePhone: 'Поделиться номером',
+  sharePhoneHint: 'Поделитесь номером из Telegram, чтобы магазин мог связаться с вами по заказам.',
+  sharePhoneAgain: 'Контакт устарел. Поделитесь им ещё раз.',
   signOut: 'Выйти',
   orders: 'Заказы',
   loadingOrders: 'Загружаем заказы…',
@@ -248,6 +297,21 @@ const uz: Messages = {
   reviewsCount: (count) => `${count} ta sharh`,
   recommendUs: (percent) => `${percent}% bizni tavsiya qiladi`,
   leaveReview: 'Sharh qoldirish',
+  blog: 'Blog',
+  allArticles: 'Barcha maqolalar',
+  featured: 'Muharrir tanlovi',
+  readingTime: (minutes) => `${minutes} daqiqa o'qish`,
+  relatedArticles: "Shuningdek o'qing",
+  productsInArticle: 'Maqoladagi mahsulotlar',
+  wasHelpful: "Maqola foydali bo'ldimi?",
+  helpful: 'Ha',
+  notHelpful: "Yo'q",
+  helpfulCount: (count) => `Foydali: ${count}`,
+  thanksForVote: 'Fikringiz uchun rahmat',
+  searchArticles: 'Maqolalardan qidirish',
+  sortNewest: 'Yangilari',
+  sortPopular: 'Ommaboplari',
+  tag: 'Teg',
   addToCart: "Savatga qo'shish",
   addedToCart: "Savatga qo'shildi.",
   couldNotAdd: "Savatga qo'shib bo'lmadi.",
@@ -288,6 +352,15 @@ const uz: Messages = {
   signIn: 'Kirish',
   sendCode: 'Kod olish',
   smsCode: 'SMS dagi kod',
+  signInWithTelegram: 'Telegram orqali kirish',
+  signingIn: 'Kirilmoqda…',
+  telegramRelaunch: "Telegram orqali kirish eskirdi. Do'konni yoping va botdan qayta oching.",
+  telegramUnavailable: "Bu do'konda Telegram orqali kirish mavjud emas.",
+  orWithPhone: 'Yoki telefon raqami bilan kiring',
+  sharePhone: 'Raqamni ulashish',
+  sharePhoneHint:
+    "Do'kon buyurtmalar bo'yicha bog'lana olishi uchun Telegram raqamingizni ulashing.",
+  sharePhoneAgain: 'Kontakt eskirdi. Uni qayta ulashing.',
   signOut: 'Chiqish',
   orders: 'Buyurtmalar',
   loadingOrders: 'Buyurtmalar yuklanmoqda…',

package/template/lib/site.ts

@@ -0,0 +1,12 @@
+import type { Schema } from '@magicstoreai/storefront-client';
+
+/**
+ * The storefront's public origin for absolute URLs (sitemap, canonical links): `SITE_URL`, else
+ * the shop's primary domain.
+ */
+export function siteOrigin(shop: Pick<Schema<'Shop'>, 'primaryDomain'>): string {
+  return (
+    process.env.SITE_URL?.replace(/\/+$/, '') ??
+    `https://${shop.primaryDomain ?? process.env.MAGICSTORE_SHOP_DOMAIN}`
+  );
+}

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
@@ -50,7 +54,7 @@ product, search, cart, checkout, sign-in, orders, SEO, webhook revalidation). Or
   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),
+  single-use), only on customer routes. `useCustomer()` signs in (OTP, Telegram, phone-only, 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
@@ -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
@@ -120,6 +144,40 @@ for buyers), quote `error.requestId` when reporting. GET calls retry on 429 / 5x
 
 The full list, with the `meta` each code carries, is in the backend's `docs/api/v2/standards.md`.
 
+## Telegram Mini App
+
+The same storefront runs inside Telegram as a Mini App (`shop.features.telegramBot` says the shop has
+a bot). The app loads `TELEGRAM_WEB_APP_SCRIPT` (from `@magicstoreai/hydrogen/core`) in the document
+head; the SDK never injects it.
+
+- `useTelegramWebApp({ documentAttributes: true })`: `status` is `unknown` on the server and the first
+  client render, then `telegram` or `browser` (a Mini App = `window.Telegram.WebApp` with a non-empty
+  `initData`). Marks `<html data-telegram data-color-scheme>`; map Telegram's `--tg-theme-*` CSS
+  variables onto your tokens under `html[data-telegram]`.
+- `useTelegramSignIn()`: signs in once per provider with `initData` (`POST /auth/telegram`) when
+  opened from the bot, unless the stored session was signed in as that same Telegram user (any other
+  session is signed out first). `failed` + `UNAUTHENTICATED` → "reopen the shop from the bot";
+  `FORBIDDEN` → the shop has no bot. `status` / `error` are shared under one provider, so an
+  `{ auto: false }` page shows the automatic attempt's progress and failure.
+- `useTelegramBackButton(visible, onBack)`, `useTelegramMainButton(options | null)`: one button per
+  page, registrations stack (the latest owns it); MainButton changes apply in place.
+- `useCustomer().shareTelegramPhone()`: `requestContact` → `POST /customer/phone-verification` with
+  the signed `response`; `null` when declined; rejects `UNAUTHENTICATED` at once when nobody is
+  signed in (show the button to signed-in customers only, and only while
+  `useTelegramWebApp().canRequestContact` — older clients resolve `null` without asking). Refusals: `VALIDATION_FAILED` with `CONTACT_EXPIRED`
+  (share again), `CONTACT_INVALID`, `CONTACT_NOT_OWN`, `INVALID_PHONE`, `TAKEN` on `telegramContact`.
+- `useCustomer().signInWithPhone(phone)`: only when `shop.features.otpLogin === false`.
+
+- `useCustomer().verifyPhoneWithTelegram(telegramContact)`: the same proof with a contact the app
+  got itself. `/core`: `TelegramWebAppController.mainButton(options)` → `{ update, release }`.
+- Call `useTelegramSignIn()` with `auto` in exactly one app-wide component; anywhere else
+  `{ auto: false }` + `signIn()`. Load the script only when `shop.features.telegramBot` is on. Starter
+  reference: `examples/starter/PAGES.md` → "Running as a Telegram Mini App".
+
+The SDK does not validate `initData` (the server does), does not parse referrals out of `startapp`
+(the server attributes them), and never sends `responseUnsafe`. Never put `initData` in a URL, a log
+or analytics.
+
 ## What the SDK does not do
 
 - Compute or round prices, discounts, taxes, delivery fees or stock — the API returns them.