create-magic-storefront 0.2.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-magic-storefront",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Scaffold a Next.js storefront on the MagicStore Storefront API v2",
   "license": "MIT",
   "type": "module",

package/template/AGENTS.md

@@ -34,6 +34,10 @@ each error code means — then `PAGES.md` for how each page type is built, and
   every language it has (`ru`, `uz`, `en`).
 - Every page handles its empty, error and not-found states (`orNotFound` turns `NOT_FOUND` into
   the 404 page).
+- The storefront also runs as a Telegram Mini App (`PAGES.md`, "Running as a Telegram Mini App").
+  App-wide Telegram behaviour lives in `components/telegram-shell.tsx` only: one automatic
+  `useTelegramSignIn()` there, `{ auto: false }` anywhere else. Never put `initData` in a URL, a log
+  or analytics.
 
 ## Design
 
@@ -51,19 +55,20 @@ screenshot every page type at 390 and 1280px, fix what you see. Interactive UI f
 
 ## Where things go
 
-| Path                           | What                                                                                                              |
-| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| `app/`                         | Pages (server components) and route handlers                                                                      |
-| `app/error.tsx`                | Error boundary: the API's `detail`, a retry                                                                       |
-| `app/blog/`                    | Blog: index, category, author, tag and article pages (`PAGES.md`, Blog)                                           |
-| `app/sitemap.ts`               | Sitemap from `GET /sitemap`                                                                                       |
-| `app/page.tsx`                 | Home: renders `GET /home` sections in the merchant's order. Optional: a custom home composes its own (`PAGES.md`) |
-| `components/sections/`         | One renderer per home section type; an unknown type renders nothing                                               |
-| `components/`                  | Shared UI; client components start with `'use client'`                                                            |
-| `lib/api.ts`                   | The server-side client (`nextCacheFetch`), `orNotFound`                                                           |
-| `app/providers.tsx`            | `MagicStoreProvider`: customer, cart, wishlist, analytics in the browser                                          |
-| `app/storefront-api/[...path]` | Same-origin proxy for browser calls without a public storefront token                                             |
-| `app/api/magicstore/webhook`   | Signed webhook → `revalidateTag`                                                                                  |
+| Path                            | What                                                                                                              |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `app/`                          | Pages (server components) and route handlers                                                                      |
+| `app/error.tsx`                 | Error boundary: the API's `detail`, a retry                                                                       |
+| `app/blog/`                     | Blog: index, category, author, tag and article pages (`PAGES.md`, Blog)                                           |
+| `app/sitemap.ts`                | Sitemap from `GET /sitemap`                                                                                       |
+| `app/page.tsx`                  | Home: renders `GET /home` sections in the merchant's order. Optional: a custom home composes its own (`PAGES.md`) |
+| `components/sections/`          | One renderer per home section type; an unknown type renders nothing                                               |
+| `components/`                   | Shared UI; client components start with `'use client'`                                                            |
+| `components/telegram-shell.tsx` | Telegram Mini App: theme marks, back arrow, the one automatic Telegram sign-in (`PAGES.md`)                       |
+| `lib/api.ts`                    | The server-side client (`nextCacheFetch`), `orNotFound`                                                           |
+| `app/providers.tsx`             | `MagicStoreProvider`: customer, cart, wishlist, analytics in the browser                                          |
+| `app/storefront-api/[...path]`  | Same-origin proxy for browser calls without a public storefront token                                             |
+| `app/api/magicstore/webhook`    | Signed webhook → `revalidateTag`                                                                                  |
 
 ## Commands
 

package/template/PAGES.md

@@ -38,6 +38,11 @@ API's, not the build's. The fetch cache still spares the API.
 - Wraps the page in `Providers` (`MagicStoreProvider` with `shop` passed in, so the browser does not
   load it again).
 - Links the blog only when `shop.features.blog` is on (an article is readable in this language).
+- Telegram: when `shop.features.telegramBot` is on, loads `TELEGRAM_WEB_APP_SCRIPT` (from
+  `@magicstoreai/hydrogen/core` — a plain string a server component may import) with
+  `<Script strategy="beforeInteractive">`; a shop without a bot pays nothing for it. Renders
+  `TelegramShell` (`components/telegram-shell.tsx`) inside `Providers` (see "Running as a Telegram
+  Mini App").
 
 ## Home — `app/page.tsx`, `components/sections/`
 
@@ -149,13 +154,68 @@ home: show new arrivals.
 
 ## Account — `app/account/page.tsx`
 
-- Client only. Signed out: `useCustomer().requestOtp(phone)` → `verifyOtp(phone, code)`
-  (`OTP_INVALID`: re-type; `OTP_EXPIRED`: ask again), or Telegram / OQ / Click sign-in in those apps.
-  Only offer OTP when `shop.features.otpLogin` is on.
+- Client only. Signed out:
+  - Phone: `useCustomer().requestOtp(phone)` → `verifyOtp(phone, code)` (`OTP_INVALID`: re-type;
+    `OTP_EXPIRED`: ask again). On a shop whose sign-in code is off
+    (`shop.features.otpLogin === false`) the same form calls `signInWithPhone(phone)` — no code
+    step.
+  - Inside a Telegram Mini App (`useTelegramWebApp().isTelegram`), above the phone form: "Sign in
+    with Telegram" — `useTelegramSignIn({ auto: false }).signIn()` (the automatic sign-in lives in
+    `components/telegram-shell.tsx`, never here). The hook shares the attempt's state, so this
+    block also shows the shell's automatic attempt: "Signing in…" while it runs, its failure
+    without a tap. `status: 'failed'` with `UNAUTHENTICATED` → the launch data is stale: ask to
+    close the shop and reopen it from the bot; `FORBIDDEN` → the shop has no bot: hide the button.
+    The phone form stays as the fallback.
+  - While `useTelegramWebApp().status` is `unknown` (server render and first paint) on a shop with
+    a bot (`shop.features.telegramBot`), an invisible copy of that block holds its place, so the
+    phone form does not jump down after mount. A shop without a bot gets no gap.
+  - OQ / Click sign-in in those apps.
 - Signed in: `customerOrdersIndex`, `customerOrdersShow`, `customerWishlistIndex`, addresses,
   rewards — through `useStorefrontClient()` (the provider adds the bearer and refreshes it).
+- Phone proof: signed in inside a Mini App with no `customer.phone` (a Telegram-only customer) and
+  `useTelegramWebApp().canRequestContact` (Bot API 6.9+; older clients cannot share) → a
+  "Share phone number" button → `useCustomer().shareTelegramPhone()` (null: the buyer declined —
+  nothing to show). Errors through `describePhoneShare` (`lib/errors.ts`): `CONTACT_EXPIRED` → share
+  again; `CONTACT_INVALID`, `CONTACT_NOT_OWN`, `INVALID_PHONE`, `TAKEN` → the API's message for
+  `telegramContact`. Never offer it to a signed-out visitor (`UNAUTHENTICATED`).
 - States: signed out, `UNAUTHENTICATED` (sign in again), no orders yet.
 
+## Running as a Telegram Mini App
+
+The same app opens inside Telegram when the shop's bot points at it: in BotFather, set the bot's
+Mini App (or menu button) URL to this site's `https://` address. Nothing else changes — same pages,
+same API.
+
+- **Script.** `app/layout.tsx` loads it only for a shop with a bot (above). It defines
+  `window.Telegram.WebApp` and writes `--tg-theme-*` / `--tg-viewport-*` / `--tg-safe-area-*` CSS
+  variables on `<html>`.
+- **Shell.** `components/telegram-shell.tsx` (`'use client'`, renders nothing) holds every
+  app-wide Telegram behaviour:
+  - `useTelegramWebApp({ documentAttributes: true })` marks `<html>` with `data-telegram` and
+    `data-color-scheme`;
+  - `useTelegramBackButton(pathname !== '/', onBack)` shows the header's back arrow off the home
+    page. `onBack` calls `router.back()` while there is app history behind the page, and
+    `router.push('/')` on the history entry the Mini App opened on (a deep link from the bot, the
+    return from a payment page), where the history before it is not the app's. The entry is told by
+    its Navigation API history index, so revisiting the first page through a link still goes back;
+    without that API, by its path;
+  - `useTelegramSignIn()` signs the buyer in with the launch data — the **only** automatic sign-in
+    in the app. A failure keeps them browsing as a guest; `/account` shows it (the hook's state is
+    shared). A referral in the `startapp` parameter is read by the server: pass no `referralCode`
+    and never parse `start_param`.
+- **Theme.** `app/globals.css` maps Telegram's colors onto the starter's tokens under
+  `html[data-telegram]` (`--bg`, `--fg`, `--muted`, `--surface`, `--placeholder`, `--accent`,
+  `--on-accent`, `--danger`), with the web values as fallbacks, and darkens `--line` for
+  `data-color-scheme="dark"`. The merchant's own accent (`brandStyle`, inline on `<html>`) still
+  wins over Telegram's button color. The merchant's `--nav-*` and `--label-*` brand tokens are not
+  overridden in Telegram's dark theme either: brand colors are the merchant's choice.
+- **Viewport.** `body` takes `--tg-viewport-stable-height` (else `100dvh`, never `100vh`) and the
+  safe-area insets; tap targets are at least 44px.
+- **MainButton.** `useTelegramMainButton` exists in the SDK; the starter does not use it.
+- **Credentials.** `initData`, tokens and the cart id never go into a URL, a log or analytics.
+- **Check by hand** with the shop's bot: opened from the bot → signed in, back arrow off the home
+  page, Telegram's colors in light and dark.
+
 ## Blog — `app/blog/`, `components/article-body.tsx`, `components/blog-listing.tsx`
 
 All blog reads are `magicstore:pages`. Rules: the backend's `docs/api/v2/blog.md`.

package/template/README.md

@@ -3,7 +3,8 @@
 A Next.js (App Router) storefront on the MagicStore Storefront API v2, built only on the public SDK
 (`@magicstoreai/storefront-client`, `@magicstoreai/hydrogen`). The home page from the merchant's
 sections (or your own composition: `GET /home` is optional), catalog, collections, search, product with variants, cart, checkout (pickup or delivery,
-payment), OTP sign-in and orders, SEO and JSON-LD, and a webhook that revalidates cached pages.
+payment), OTP sign-in and orders, SEO and JSON-LD, a webhook that revalidates cached pages — and it
+runs as a Telegram Mini App (sign-in from the bot, back button, Telegram's theme, phone sharing).
 
 ```bash
 cp .env.example .env.local   # set MAGICSTORE_SHOP_DOMAIN
@@ -24,6 +25,11 @@ npm run dev
 origin) the browser calls the shop's API directly. Without it, calls go through the proxy route,
 which forwards the buyer's address in `X-Forwarded-For`.
 
+**Telegram Mini App.** For a shop with a connected bot, set the bot's Mini App URL in BotFather to
+this site's `https://` address. The layout loads Telegram's script only for such a shop;
+`components/telegram-shell.tsx` signs the buyer in, shows the back arrow and applies Telegram's
+theme. Details: `PAGES.md`, "Running as a Telegram Mini App".
+
 **Offline.** `MAGICSTORE_API_URL=http://127.0.0.1:4010` with `pnpm mock` running in the SDK repository
 serves every page from the spec's example data.
 

package/template/app/account/page.tsx

@@ -5,19 +5,29 @@ import {
   useCustomer,
   useMagicStore,
   useStorefrontClient,
+  useTelegramSignIn,
+  useTelegramWebApp,
   useWishlist,
 } from '@magicstoreai/hydrogen';
 import type { Schema } from '@magicstoreai/storefront-client';
 import { useEffect, useState } from 'react';
-import { describe } from '@/lib/errors';
+import { describe, describePhoneShare } from '@/lib/errors';
 import { messages } from '@/lib/i18n';
 
 export default function AccountPage() {
   const { customer, isSignedIn, signOut } = useCustomer();
-  const t = messages(useMagicStore().locale);
+  const { status, isTelegram, canRequestContact } = useTelegramWebApp();
+  const { locale, shop } = useMagicStore();
+  const t = messages(locale);
+  // Until the app has looked (`unknown`, server render included), a shop with a bot may be open in
+  // Telegram: hold the Telegram block's place so the phone form does not jump down after mount.
+  const maybeTelegram = status === 'unknown' && shop?.features.telegramBot === true;
   return isSignedIn && customer ? (
     <div className="stack">
       <h1>{customer.name || customer.phone}</h1>
+      {/* A customer who only ever signed in through Telegram has no phone yet; older Telegram
+          clients cannot share it. */}
+      {canRequestContact && !customer.phone && <SharePhone />}
       <Orders />
       <SavedCount />
       <div>
@@ -25,13 +35,76 @@ export default function AccountPage() {
       </div>
     </div>
   ) : (
-    <SignIn />
+    <div className="stack" style={{ maxWidth: 360 }}>
+      <h1>{t.signIn}</h1>
+      {isTelegram && <TelegramBlock />}
+      {maybeTelegram && <TelegramBlock placeholder />}
+      <PhoneSignIn />
+    </div>
+  );
+}
+
+/**
+ * The Telegram sign-in above the phone form. As a `placeholder` it renders the same markup, hidden,
+ * so the reserved space always matches the real block.
+ */
+function TelegramBlock({ placeholder = false }: { placeholder?: boolean }) {
+  const t = messages(useMagicStore().locale);
+  return (
+    <div
+      className="stack"
+      aria-hidden={placeholder || undefined}
+      style={placeholder ? { visibility: 'hidden' } : undefined}
+    >
+      <TelegramSignIn />
+      <p className="muted">{t.orWithPhone}</p>
+    </div>
   );
 }
 
-function SignIn() {
-  const { requestOtp, verifyOtp } = useCustomer();
+/**
+ * Inside a Mini App: sign in with the launch data. The automatic sign-in runs in
+ * components/telegram-shell.tsx; this is the manual retry. The hook shares the attempt's state, so
+ * this shows the automatic attempt too: "Signing in…" while it runs, the relaunch hint when it failed.
+ */
+function TelegramSignIn() {
+  const { status, error, signIn } = useTelegramSignIn({ auto: false });
   const t = messages(useMagicStore().locale);
+  // FORBIDDEN: the shop has no bot, so retrying is pointless.
+  const unavailable = error?.code === 'FORBIDDEN';
+  return (
+    <div className="stack">
+      {!unavailable && (
+        <button
+          className="primary"
+          disabled={status === 'signing-in'}
+          onClick={() => void signIn()}
+        >
+          {status === 'signing-in' ? t.signingIn : t.signInWithTelegram}
+        </button>
+      )}
+      {status === 'failed' && (
+        <p className="error" role="alert">
+          {error?.code === 'UNAUTHENTICATED'
+            ? t.telegramRelaunch
+            : unavailable
+              ? t.telegramUnavailable
+              : describe(error, t.tryAgainLater)}
+        </p>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Phone sign-in: a code by SMS, or — on a shop whose sign-in code is off
+ * (`shop.features.otpLogin === false`) — the phone alone.
+ */
+function PhoneSignIn() {
+  const { requestOtp, verifyOtp, signInWithPhone } = useCustomer();
+  const { locale, shop } = useMagicStore();
+  const t = messages(locale);
+  const withoutCode = shop?.features.otpLogin === false;
   const [phone, setPhone] = useState('');
   const [sent, setSent] = useState(false);
   const [code, setCode] = useState('');
@@ -49,11 +122,12 @@ function SignIn() {
   return (
     <form
       className="stack"
-      style={{ maxWidth: 360 }}
       onSubmit={(event) => {
         event.preventDefault();
         void attempt(async () => {
-          if (!sent) {
+          if (withoutCode) {
+            await signInWithPhone(phone);
+          } else if (!sent) {
             await requestOtp(phone);
             setSent(true);
           } else {
@@ -62,7 +136,6 @@ function SignIn() {
         });
       }}
     >
-      <h1>{t.signIn}</h1>
       <input
         value={phone}
         onChange={(e) => setPhone(e.target.value)}
@@ -84,12 +157,55 @@ function SignIn() {
           required
         />
       )}
-      <button className="primary">{sent ? t.signIn : t.sendCode}</button>
-      {error && <p className="error">{error}</p>}
+      <button className="primary">{sent || withoutCode ? t.signIn : t.sendCode}</button>
+      {error && (
+        <p className="error" role="alert">
+          {error}
+        </p>
+      )}
     </form>
   );
 }
 
+/**
+ * Signed in inside a Mini App without a phone: share the Telegram contact, which proves the phone.
+ * A declined request changes nothing.
+ */
+function SharePhone() {
+  const { shareTelegramPhone } = useCustomer();
+  const t = messages(useMagicStore().locale);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function share() {
+    setBusy(true);
+    setError(null);
+    try {
+      await shareTelegramPhone();
+    } catch (e) {
+      setError(describePhoneShare(e, t));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  return (
+    <section className="stack">
+      <p className="muted">{t.sharePhoneHint}</p>
+      <div>
+        <button className="primary" disabled={busy} onClick={() => void share()}>
+          {t.sharePhone}
+        </button>
+      </div>
+      {error && (
+        <p className="error" role="alert">
+          {error}
+        </p>
+      )}
+    </section>
+  );
+}
+
 function Orders() {
   const client = useStorefrontClient();
   const [orders, setOrders] = useState<Schema<'Order'>[] | null>(null);

package/template/app/globals.css

@@ -4,6 +4,9 @@
   --muted: #6b6b76;
   --line: #e7e7ec;
   --danger: #c62828;
+  /* Controls and image placeholders: white and light grey here, Telegram's colors in a Mini App. */
+  --surface: #fff;
+  --placeholder: #f3f3f6;
   /* Brand tokens: app/layout.tsx overrides them with the merchant's colors (lib/brand.ts). */
   --accent: #1f5eff;
   --on-accent: #fff;
@@ -20,6 +23,32 @@
   color: var(--fg);
   background: var(--bg);
 }
+/*
+ * Inside a Telegram Mini App (components/telegram-shell.tsx marks <html>): Telegram's theme, which
+ * its script writes as --tg-theme-* on <html>, with the defaults above as fallbacks. The merchant's
+ * accent from <html style> (lib/brand.ts) still wins over Telegram's button color.
+ */
+html[data-telegram] {
+  --bg: var(--tg-theme-bg-color, #fff);
+  --fg: var(--tg-theme-text-color, #16161a);
+  --muted: var(--tg-theme-hint-color, #6b6b76);
+  --danger: var(--tg-theme-destructive-text-color, #c62828);
+  --surface: var(--tg-theme-secondary-bg-color, #fff);
+  --placeholder: var(--tg-theme-secondary-bg-color, #f3f3f6);
+  --accent: var(--tg-theme-button-color, #1f5eff);
+  --on-accent: var(--tg-theme-button-text-color, #fff);
+}
+html[data-telegram][data-color-scheme='dark'] {
+  --line: rgba(255, 255, 255, 0.14);
+  color-scheme: dark;
+}
+html[data-telegram] body {
+  /* Telegram's stable viewport (the sheet can be dragged), the dynamic viewport outside it. */
+  min-height: var(--tg-viewport-stable-height, 100dvh);
+  padding-left: max(env(safe-area-inset-left), var(--tg-safe-area-inset-left, 0px));
+  padding-right: max(env(safe-area-inset-right), var(--tg-safe-area-inset-right, 0px));
+  padding-bottom: max(env(safe-area-inset-bottom), var(--tg-safe-area-inset-bottom, 0px));
+}
 * {
   box-sizing: border-box;
 }
@@ -76,7 +105,7 @@ header.site .brand img {
   height: auto;
   aspect-ratio: 1;
   object-fit: cover;
-  background: #f3f3f6;
+  background: var(--placeholder);
   border-radius: 8px;
 }
 .muted {
@@ -117,7 +146,9 @@ button,
   padding: 10px 16px;
   border-radius: 8px;
   border: 1px solid var(--line);
-  background: #fff;
+  background: var(--surface);
+  color: var(--fg);
+  min-height: 44px;
   cursor: pointer;
   text-decoration: none;
 }
@@ -137,7 +168,10 @@ button:disabled {
 input,
 select {
   font: inherit;
+  min-height: 44px;
   padding: 9px 12px;
+  background: var(--surface);
+  color: var(--fg);
   border: 1px solid var(--line);
   border-radius: 8px;
 }
@@ -286,7 +320,7 @@ fieldset {
   width: 80px;
   height: 80px;
   object-fit: cover;
-  background: #f3f3f6;
+  background: var(--placeholder);
   border-radius: 12px;
 }
 .stories-circle .story img,
@@ -364,7 +398,7 @@ footer.site nav {
   padding: 12px 16px;
   border-left: 4px solid var(--accent);
   border-radius: 8px;
-  background: #f6f7fb;
+  background: var(--placeholder);
 }
 .callout[data-callout='warning'] {
   border-left-color: var(--danger);

package/template/app/layout.tsx

@@ -1,8 +1,12 @@
 import type { Metadata } from 'next';
 import Link from 'next/link';
+import Script from 'next/script';
 import type { ReactNode } from 'react';
 import { Image } from '@magicstoreai/hydrogen';
+// From /core, not the "use client" entry: a plain string a server component can read.
+import { TELEGRAM_WEB_APP_SCRIPT } from '@magicstoreai/hydrogen/core';
 import { CartLink } from '@/components/cart-link';
+import { TelegramShell } from '@/components/telegram-shell';
 import { api, locale } from '@/lib/api';
 import { brandStyle } from '@/lib/brand';
 import { messages } from '@/lib/i18n';
@@ -34,7 +38,12 @@ export default async function RootLayout({ children }: { children: ReactNode })
     // The merchant's colors, read per request: a change in the admin shows after SHOP_UPDATED.
     <html lang={locale} style={brandStyle(shop.branding)}>
       <body>
+        {/* Telegram's Mini App script, only for a shop with a bot: nobody else can open it in Telegram. */}
+        {shop.features.telegramBot && (
+          <Script src={TELEGRAM_WEB_APP_SCRIPT} strategy="beforeInteractive" />
+        )}
         <Providers shop={shop}>
+          <TelegramShell />
           <header className="site">
             <nav>
               <Link href="/" className="brand">

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

@@ -5,3 +5,24 @@ import { MagicStoreError } from '@magicstoreai/storefront-client';
 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

@@ -117,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…',
@@ -227,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: 'Загружаем заказы…',
@@ -334,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/llms.txt

@@ -54,7 +54,7 @@ product, search, blog, cart, checkout, sign-in, orders, SEO, webhook revalidatio
   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
@@ -144,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.

package/template/package.json

@@ -18,9 +18,11 @@
     "server-only": "^0.0.1"
   },
   "devDependencies": {
+    "@testing-library/react": "^16.3.3",
     "@types/node": "^26.6.2",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
+    "jsdom": "^30.1.1",
     "typescript": "5.9.3"
   }
 }