@magicstoreai/hydrogen 0.1.0

package/CATALOGUE.md

@@ -0,0 +1,931 @@
+# `@magicstoreai/hydrogen` catalogue
+
+<!-- Generated by `pnpm --filter @magicstoreai/hydrogen catalogue` from the TypeScript sources — do not edit. -->
+
+Every public export, by entry point: what it is, how to call it, an example, and the Storefront
+API operations it calls (`operationId`s of `@magicstoreai/storefront-client`). Import only from
+these entry points — anything else is internal and may change in any release.
+
+## `@magicstoreai/hydrogen`
+
+React bindings (a `"use client"` module). Also re-exports everything in `/core` and `MagicStoreError`.
+
+### Components
+
+#### `<Image>`
+
+An API image with lazy loading by default. Its intrinsic size is set (no layout shift) unless
+you pass `width` / `height` to draw it at another size, e.g. a 64×64 cart thumbnail.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `data` | `Schema<'Image'> \| null \| undefined` |  |
+| `alt?` | `string` | Used when the image has no alt text of its own. |
+| `fallback?` | `ReactNode` |  |
+
+Any other prop is passed to the rendered element.
+
+```tsx
+<Image data={product.featuredImage} alt={product.title} fallback={<div className="noimg" />} />
+```
+
+#### `<MagicStoreProvider>`
+
+The root of a storefront: one client, and the customer, cart, wishlist and analytics built on it.
+On sign-in the cart becomes the customer's and the guest wishlist moves into their list; on
+sign-out both are left behind with the customer.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `locale?` | `string` | The language the storefront renders in; the shop's default when omitted. |
+| `shop?` | `Shop` | The shop, when the page already has it (server-rendered) — saves a `/shop` call. |
+| `storage?` | `KeyValueStorage` | Where the session, cart id and guest wishlist are kept; `localStorage` by default. |
+| `children` | `ReactNode` |  |
+| `shopDomain?` | `string` | The shop's storefront domain, e.g. `shop.example.uz` → `https://shop.example.uz/api/v2/storefront`. |
+| `baseUrl?` | `string` | The full API base URL, instead of `shopDomain`. |
+| `storefrontToken?` | `string` | `X-Storefront-Token` — identifies the shop when the host is not one of its domains. |
+| `fetch?` | `typeof globalThis.fetch` | A `fetch` implementation; the global one by default. |
+| `retry?` | `RetryOptions \| false` | Retry policy for `GET`s answered `429` or `5xx`, or not answered at all. Writes are never retried by the client. `false` turns retries off. |
+
+API operations: `shop`.
+
+```tsx
+// app/providers.tsx ('use client'); `shop` comes from a server-side `api.shop()`.
+<MagicStoreProvider shopDomain="shop.example.uz" shop={shop} locale="ru">
+  {children}
+</MagicStoreProvider>
+```
+
+#### `<Money>`
+
+A price as the shop shows it (`shop.moneyFormat`, the storefront's locale).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `data` | `MoneyValue \| null \| undefined` |  |
+| `as?` | `As` |  |
+| `fallback?` | `ReactNode` | What to render for a missing price (the API sends null for "unknown", never 0). |
+
+```tsx
+<Money data={product.price} fallback={<span>—</span>} />
+```
+
+#### `<Pagination>`
+
+Headless pagination over `meta.pagination`: you render the links, it does the arithmetic.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `meta` | `Pagination` |  |
+| `around?` | `number` |  |
+| `children` | `(state: PaginationState) => ReactNode` |  |
+
+```tsx
+<Pagination meta={products.meta.pagination}>
+  {({ pages }) =>
+    pages.map((page, i) =>
+      page === null ? <span key={i}>…</span> : <a key={i} href={`?page=${page}`}>{page}</a>,
+    )
+  }
+</Pagination>
+```
+
+#### `<ProductProvider>`
+
+Shares one product's variant selection with everything under it (options, price, add-to-cart).
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `product` | `P` |  |
+| `initialVariantId?` | `string \| null` |  |
+| `children` | `ReactNode` |  |
+
+```tsx
+<ProductProvider product={product}>
+  <VariantPicker />
+  <AddToCart />
+</ProductProvider>
+```
+
+### Hooks
+
+#### `useAnalytics`
+
+Reports what the visitor looks at. Stable across renders.
+
+```ts
+function useAnalytics()
+```
+
+| Returns | Type | Description |
+| --- | --- | --- |
+| `queue` | `AnalyticsEvent[]` |  |
+| `timer` | `ReturnType<typeof setTimeout> \| null` |  |
+| `client` | `StorefrontClient` |  |
+| `sessionId` | `string` |  |
+| `options` | `{ flushAfterMs?: number; context?: AnalyticsPayload }` |  |
+| `pageView` | `void` | A page view — starts the session with its first-touch attribution (UTM, click ids, referrer). |
+| `productView` | `void` |  |
+| `collectionView` | `void` |  |
+| `search` | `void` |  |
+| `custom` | `void` |  |
+| `track` | `void` |  |
+| `flush` | `Promise<void>` | Sends what is queued now — call it when the page is hidden. |
+
+API operations: `analyticsEventsStore`.
+
+```tsx
+const analytics = useAnalytics();
+useEffect(() => analytics.productView(product.id), [analytics, product.id]);
+```
+
+#### `useCart`
+
+The visitor's cart and every change to it. The first `addLines` creates the cart.
+
+```ts
+function useCart()
+```
+
+| Returns | Type | Description |
+| --- | --- | --- |
+| `totalQuantity` | `number` |  |
+| `addLines` | `(lines: CartLineInput[]) => Promise<Cart \| null>` |  |
+| `addLine` | `(line: CartLineInput) => Promise<Cart \| null>` |  |
+| `updateLine` | `(lineId: string, quantity: number) => Promise<Cart \| null>` |  |
+| `removeLine` | `(lineId: string) => Promise<Cart \| null>` |  |
+| `setDiscountCodes` | `(codes: string[]) => Promise<Cart \| null>` |  |
+| `setNote` | `(note: string \| null) => Promise<Cart \| null>` |  |
+| `setAttributes` | `(attributes: CartAttribute[]) => Promise<Cart \| null>` |  |
+| `setGift` | `(promotionId: string \| null) => Promise<Cart \| null>` |  |
+| `setPoints` | `(points: number) => Promise<Cart \| null>` |  |
+| `cart` | `Cart \| null` |  |
+| `status` | `'idle' \| 'loading' \| 'updating'` | `loading` while the stored cart is fetched; `updating` while a change is on its way. |
+| `error` | `MagicStoreError \| null` | The last change that failed — the cart is back to what the server holds. |
+
+API operations: `cartsAttributes`, `cartsBuyerIdentity`, `cartsDiscountCodes`, `cartsGift`, `cartsLinesDestroy`, `cartsLinesStore`, `cartsLinesUpdate`, `cartsNote`, `cartsPoints`, `cartsShow`, `cartsStore`.
+
+```tsx
+const { cart, totalQuantity, status, error, addLine } = useCart();
+await addLine({ productId: product.id, variantId: selectedVariant?.id ?? null, quantity: 1 });
+```
+
+#### `useCustomer`
+
+The signed-in customer and every way to sign in and out.
+
+```ts
+function useCustomer()
+```
+
+| Returns | Type | Description |
+| --- | --- | --- |
+| `customer` | `{ createdAt: string \| null; deletionRequestedAt: string \| null; gender: "MALE" \| "FEMALE" \| null; id: string; locale: string \| null; name: string \| null; phone: string \| null; referralCode: string \| null; } \| null` |  |
+| `isSignedIn` | `boolean` |  |
+| `requestOtp` | `(phone: string) => Promise<Schema<'OtpChallenge'>>` |  |
+| `verifyOtp` | `(phone: string, code: string, referralCode?: string) => Promise<CustomerSession>` |  |
+| `signInWithTelegram` | `(initData: string, referralCode?: string) => Promise<CustomerSession>` |  |
+| `signInWithOq` | `(oqToken: string) => Promise<CustomerSession>` |  |
+| `signInWithClick` | `(webSession: string) => Promise<CustomerSession>` |  |
+| `signOut` | `() => Promise<void>` |  |
+| `reload` | `() => Promise<Customer \| null>` |  |
+
+API operations: `authClick`, `authOq`, `authOtp`, `authOtpVerification`, `authTelegram`, `authTokenDestroy`, `authTokenRefresh`, `customerShow`.
+
+```tsx
+const { customer, isSignedIn, requestOtp, verifyOtp, signOut } = useCustomer();
+await requestOtp('+998901234567');
+await verifyOtp('+998901234567', code);
+```
+
+#### `useMagicStore`
+
+Everything the provider holds: client, shop, locale and the controllers. Throws outside
+`<MagicStoreProvider>`.
+
+```ts
+function useMagicStore(): MagicStore
+```
+
+```tsx
+const { locale, sessionId } = useMagicStore();
+```
+
+#### `useProduct`
+
+The product and variant selection of the nearest `<ProductProvider>`; throws outside one.
+
+```ts
+function useProduct(): ProductContextValue
+```
+
+```tsx
+const { product, selectedVariant } = useProduct();
+return <Money data={selectedVariant?.price ?? product.price} />;
+```
+
+#### `useShop`
+
+The shop (`GET /shop`): name, currency, money format, locales, features, branding…
+
+```ts
+function useShop(): Shop | null
+```
+
+```tsx
+const shop = useShop();
+return <span>{shop?.name}</span>;
+```
+
+#### `useStorefrontClient`
+
+The typed API client, for anything the hooks do not cover.
+
+```ts
+function useStorefrontClient(): StorefrontClient
+```
+
+```tsx
+const client = useStorefrontClient();
+const { data } = await client.searchSuggestions({ query: { q } });
+```
+
+#### `useVariantSelection`
+
+Options → variant. `selectedVariant` is null only while a choice is missing; `isAvailable` says
+whether a value leads to a variant for sale given the other choices.
+
+```ts
+function useVariantSelection(product: SelectableProduct, initialVariantId?: string | null)
+```
+
+| Returns | Type | Description |
+| --- | --- | --- |
+| `selectedOptions` | `SelectedOptions` |  |
+| `selectedVariant` | `{ availableForSale: boolean; barcode: string \| null; compareAtPrice: { amount: string; currencyCode: string; } \| null; gtin: string \| null; id: string; image: { altText: string \| null; height: number \| null; url: string; width: number \| null; } \| null; ... 7 more ...; weight: { ...; } \| null; } \| null` |  |
+| `setOption` | `(name: string, value: string) => void` |  |
+| `isAvailable` | `(name: string, value: string) => boolean` |  |
+
+```tsx
+const { selectedOptions, selectedVariant, setOption, isAvailable } = useVariantSelection(product);
+<button disabled={!isAvailable('Size', 'M')} onClick={() => setOption('Size', 'M')}>M</button>
+```
+
+#### `useWishlist`
+
+Saved products: a guest's in this browser, a customer's on the server (merged at sign-in).
+
+```ts
+function useWishlist()
+```
+
+| Returns | Type | Description |
+| --- | --- | --- |
+| `has` | `(productId: string) => boolean` |  |
+| `add` | `(productId: string) => Promise<void>` |  |
+| `remove` | `(productId: string) => Promise<void>` |  |
+| `toggle` | `(productId: string) => Promise<void>` |  |
+| `productIds` | `string[]` | Product ids, most recent first. |
+| `owner` | `'guest' \| 'customer'` | Whose list it is: a guest's lives in this browser, a customer's on the server. |
+| `status` | `'idle' \| 'loading'` |  |
+
+API operations: `customerWishlistAdd`, `customerWishlistRemove`.
+
+```tsx
+const wishlist = useWishlist();
+<button aria-pressed={wishlist.has(product.id)} onClick={() => wishlist.toggle(product.id)}>♥</button>
+```
+
+### Classes
+
+#### `MagicStoreError`
+
+Every failed call. `code` is what to branch on — never the message, which is localized.
+
+```ts
+try {
+  await client.checkoutsCompletion({ path: { id } });
+} catch (error) {
+  if (error instanceof MagicStoreError && error.code === 'CHECKOUT_NOT_READY') { … }
+}
+```
+
+Re-exported from `@magicstoreai/storefront-client`.
+
+### Functions
+
+#### `paginationState`
+
+```ts
+function paginationState(meta: Pagination, around = 1): PaginationState
+```
+
+### Types
+
+#### `MagicStore`
+
+```ts
+export interface MagicStore {
+    client: StorefrontClient;
+    shop: Shop | null;
+    locale: string;
+    session: CustomerSessionController;
+    cart: CartController;
+    wishlist: WishlistController;
+    analytics: AnalyticsController;
+    sessionId: string;
+}
+```
+
+#### `MagicStoreProviderProps`
+
+```ts
+export interface MagicStoreProviderProps extends Pick<StorefrontClientOptions, 'shopDomain' | 'baseUrl' | 'storefrontToken' | 'fetch' | 'retry'> {
+    locale?: string;
+    shop?: Shop;
+    storage?: KeyValueStorage;
+    children: ReactNode;
+}
+```
+
+#### `PaginationState`
+
+```ts
+export interface PaginationState {
+    page: number;
+    totalPages: number;
+    hasPreviousPage: boolean;
+    hasNextPage: boolean;
+    previousPage: number | null;
+    nextPage: number | null;
+    pages: Array<number | null>;
+}
+```
+
+#### `Shop`
+
+```ts
+export type Shop = Schema<'Shop'>;
+```
+
+## `@magicstoreai/hydrogen/core`
+
+Framework-free controllers and helpers, safe on the server and in any UI library.
+
+### Classes
+
+#### `AnalyticsController`
+
+What the visitor looks at, sent in batches (`POST /analytics/events`). Cart and checkout steps
+are recorded by the server — never report them. Failures are dropped: analytics must never get
+in the way of shopping.
+
+```ts
+class AnalyticsController {
+  constructor(private readonly client: StorefrontClient, private readonly sessionId: string, private readonly options: {
+      flushAfterMs?: number;
+      context?: AnalyticsPayload;
+  } = {});
+  pageView(path: string, extra: AnalyticsPayload = {}): void;
+  productView(productId: string, variantId?: string | null): void;
+  collectionView(collectionId: string): void;
+  search(query: string, resultsCount?: number): void;
+  custom(name: string, properties?: Record<string, unknown>): void;
+  track(type: AnalyticsEventType, payload: AnalyticsPayload): void;
+  async flush(): Promise<void>;
+}
+```
+
+API operations: `analyticsEventsStore`.
+
+#### `CartController`
+
+The visitor's cart. Its id is a capability and lives only in storage; the cart itself always
+comes from the server, so prices, discounts and availability are the server's. Quantity changes
+show at once and roll back if the server refuses them. Changes run one after another.
+
+```ts
+class CartController {
+  constructor(private readonly client: StorefrontClient, private readonly storage: KeyValueStorage, private readonly key = 'magicstore.cart-id');
+  get cart(): Cart | null;
+  get cartId(): string | null;
+  load(): Promise<Cart | null>;
+  addLines(lines: CartLineInput[]): Promise<Cart | null>;
+  updateLine(lineId: string, quantity: number): Promise<Cart | null>;
+  removeLine(lineId: string): Promise<Cart | null>;
+  setDiscountCodes(discountCodes: string[]): Promise<Cart | null>;
+  setNote(note: string | null): Promise<Cart | null>;
+  setAttributes(attributes: CartAttribute[]): Promise<Cart | null>;
+  setGift(promotionId: string | null): Promise<Cart | null>;
+  setPoints(points: number): Promise<Cart | null>;
+  attachCustomer(): Promise<Cart | null>;
+  forget(): void;
+}
+```
+
+API operations: `cartsAttributes`, `cartsBuyerIdentity`, `cartsDiscountCodes`, `cartsGift`, `cartsLinesDestroy`, `cartsLinesStore`, `cartsLinesUpdate`, `cartsNote`, `cartsPoints`, `cartsShow`, `cartsStore`.
+
+#### `CustomerSessionController`
+
+The signed-in customer and their tokens. The access token lives an hour and is refreshed on
+demand; the refresh token works once, so concurrent callers share one refresh.
+
+```ts
+class CustomerSessionController {
+  constructor(private readonly storage: KeyValueStorage, private readonly key = 'magicstore.customer-session', private readonly now: () => number = () => Date.now());
+  attach(client: StorefrontClient): void;
+  get session(): CustomerSession | null;
+  get customer(): Customer | null;
+  accessToken;
+  refresh(): Promise<string | null>;
+  async requestOtp(phone: string): Promise<Schema<'OtpChallenge'>>;
+  async verifyOtp(phone: string, code: string, referralCode?: string): Promise<CustomerSession>;
+  async signInWithTelegram(initData: string, referralCode?: string): Promise<CustomerSession>;
+  async signInWithOq(oqToken: string): Promise<CustomerSession>;
+  async signInWithClick(webSession: string): Promise<CustomerSession>;
+  async signOut(): Promise<void>;
+  async reloadCustomer(): Promise<Customer | null>;
+}
+```
+
+API operations: `authClick`, `authOq`, `authOtp`, `authOtpVerification`, `authTelegram`, `authTokenDestroy`, `authTokenRefresh`, `customerShow`.
+
+#### `WishlistController`
+
+Saved products. A guest's list is kept in this browser; on sign-in it moves into the customer's
+list on the server and the local copy is cleared. Changes show at once and roll back if refused.
+
+```ts
+class WishlistController {
+  constructor(private readonly client: StorefrontClient, private readonly storage: KeyValueStorage, private readonly key = 'magicstore.guest-wishlist');
+  has(productId: string): boolean;
+  async add(productId: string): Promise<void>;
+  async remove(productId: string): Promise<void>;
+  toggle(productId: string): Promise<void>;
+  async signedIn(): Promise<void>;
+  signedOut(): void;
+  async reload(): Promise<void>;
+}
+```
+
+API operations: `customerWishlistAdd`, `customerWishlistRemove`.
+
+### Functions
+
+#### `attributionFrom`
+
+The first-touch attribution a landing URL carries, for the first `pageView`.
+
+```ts
+function attributionFrom(url: URL, referrer?: string): AnalyticsPayload
+```
+
+#### `browserStorage`
+
+`localStorage` when the browser allows it; memory otherwise (server render, private mode,
+blocked site data). Every access is guarded: storage can throw at any time.
+
+```ts
+function browserStorage(): KeyValueStorage
+```
+
+#### `currencySymbol`
+
+The currency's symbol or word in a locale: `сум`, `so‘m`, `$`.
+
+```ts
+function currencySymbol(currencyCode: string, locale: string): string
+```
+
+#### `formatMoney`
+
+Money as the shop shows it: `shop.moneyFormat.format` places the symbol or the code, and a shop
+with no format uses the currency's own convention (`12 500 сум`, `$129.99`).
+
+```ts
+function formatMoney(money: Money, options: {
+    locale: string;
+    format?: MoneyFormat | null;
+}): string
+```
+
+#### `groupAmount`
+
+`12500.00` → `12 500`: groups of three separated by a space, the fraction kept only when it is
+not zero. The amount is never rounded here — the API already applied the shop's rounding, and
+the string is exactly what will be charged.
+
+```ts
+function groupAmount(amount: string): string
+```
+
+#### `initialSelection`
+
+Where selection starts: the given variant, else the first one for sale, else the first one.
+A product with a single variant and no options is always "selected".
+
+```ts
+function initialSelection(product: SelectableProduct, variantId?: string | null): SelectedOptions
+```
+
+#### `isOptionValueAvailable`
+
+Whether picking `value` for `name` — keeping the other choices — lands on a variant for sale.
+What a storefront uses to grey out a size that is sold out in the chosen colour.
+
+```ts
+function isOptionValueAvailable(product: SelectableProduct, selected: SelectedOptions, name: string, value: string): boolean
+```
+
+#### `memoryStorage`
+
+In memory — for tests, the server, and when the browser refuses storage.
+
+```ts
+function memoryStorage(initial: Record<string, string> = {}): KeyValueStorage
+```
+
+#### `moneyAmount`
+
+The amount as a number, for arithmetic you must do on the client (sorting, a progress bar).
+
+```ts
+function moneyAmount(money: Money): number
+```
+
+#### `optionsOf`
+
+```ts
+function optionsOf(variant: ProductVariant): SelectedOptions
+```
+
+#### `selectOption`
+
+Choosing a value keeps the other choices when that combination exists; otherwise it moves to the
+closest variant that has the new value (for sale first), so the selection never dead-ends.
+
+```ts
+function selectOption(product: SelectableProduct, selected: SelectedOptions, name: string, value: string): SelectedOptions
+```
+
+#### `variantFor`
+
+The variant whose options are exactly these, or null while the selection is incomplete.
+
+```ts
+function variantFor(product: SelectableProduct, selected: SelectedOptions): ProductVariant | null
+```
+
+#### `visitorSessionId`
+
+The visitor's id for the shop's analytics and funnel: a UUID minted once per visitor and kept.
+The same value goes out as `X-Session-Id`, which ties carts and orders to the visit.
+
+```ts
+function visitorSessionId(storage: KeyValueStorage, key = 'magicstore.session-id'): string
+```
+
+### Constants
+
+#### `WISHLIST_LIMIT`
+
+The server keeps up to this many; a guest list is capped the same.
+
+```ts
+const WISHLIST_LIMIT = 500
+```
+
+### Types
+
+#### `AnalyticsEvent`
+
+```ts
+export type AnalyticsEvent = EventsBody['events'][number];
+```
+
+#### `AnalyticsEventType`
+
+```ts
+export type AnalyticsEventType = Schema<'StorefrontEventType'>;
+```
+
+#### `AnalyticsPayload`
+
+```ts
+export type AnalyticsPayload = AnalyticsEvent['payload'];
+```
+
+#### `Cart`
+
+```ts
+export type Cart = Schema<'Cart'>;
+```
+
+#### `CartAttribute`
+
+```ts
+export type CartAttribute = {
+    key: string;
+    value: string | null;
+};
+```
+
+#### `CartLine`
+
+```ts
+export type CartLine = Schema<'CartLine'>;
+```
+
+#### `CartLineInput`
+
+A line to add: the product, its variant (null for a product without variants) and how many.
+
+```ts
+export interface CartLineInput {
+    productId: string;
+    variantId?: string | null;
+    quantity?: number;
+    attributes?: CartAttribute[];
+}
+```
+
+#### `CartState`
+
+```ts
+export interface CartState {
+    cart: Cart | null;
+    status: 'idle' | 'loading' | 'updating';
+    error: MagicStoreError | null;
+}
+```
+
+#### `Customer`
+
+```ts
+export type Customer = Schema<'Customer'>;
+```
+
+#### `CustomerSession`
+
+```ts
+export type CustomerSession = Schema<'CustomerSession'>;
+```
+
+#### `KeyValueStorage`
+
+Where the SDK keeps what outlives a page: the customer session, the cart id, the guest wishlist.
+
+```ts
+export interface KeyValueStorage {
+    get(key: string): string | null;
+    set(key: string, value: string): void;
+    remove(key: string): void;
+}
+```
+
+#### `Money`
+
+```ts
+export type Money = Schema<'Money'>;
+```
+
+#### `MoneyFormat`
+
+```ts
+export type MoneyFormat = Schema<'Shop'>['moneyFormat'];
+```
+
+#### `ProductOption`
+
+```ts
+export type ProductOption = Schema<'ProductOption'>;
+```
+
+#### `ProductVariant`
+
+```ts
+export type ProductVariant = Schema<'ProductVariant'>;
+```
+
+#### `SelectableProduct`
+
+What variant selection needs of a product — `Product` and `ProductDetail` both fit.
+
+```ts
+export interface SelectableProduct {
+    options: ProductOption[];
+    variants: ProductVariant[];
+}
+```
+
+#### `SelectedOptions`
+
+```ts
+export type SelectedOptions = Record<string, string>;
+```
+
+#### `SessionState`
+
+```ts
+export interface SessionState {
+    session: CustomerSession | null;
+}
+```
+
+#### `WishlistState`
+
+```ts
+export interface WishlistState {
+    productIds: string[];
+    owner: 'guest' | 'customer';
+    status: 'idle' | 'loading';
+}
+```
+
+## `@magicstoreai/hydrogen/server`
+
+Server only: webhook verification and Next.js cache tags.
+
+### Functions
+
+#### `createWebhookHandler`
+
+A route handler for the platform's webhook: `export const POST = createWebhookHandler({ secret,
+revalidateTag })` in `app/api/magicstore/webhook/route.ts`. Answers 401 on a bad signature, 400
+on a body that is not an event, 200 otherwise — including for a topic it does not know. Events
+seen before (same id, this instance) are acknowledged and skipped.
+
+```ts
+function createWebhookHandler(options: WebhookHandlerOptions): (request: Request) => Promise<Response>
+```
+
+#### `nextCacheFetch`
+
+A `fetch` for `createStorefrontClient` on a Next.js server: public GETs are cached under the tag
+a webhook revalidates (and at most `revalidate` seconds); everything else is `no-store`.
+
+```ts
+const client = createStorefrontClient({ shopDomain, fetch: nextCacheFetch() });
+```
+
+```ts
+function nextCacheFetch(options: {
+    revalidate?: number | false;
+    fetch?: typeof globalThis.fetch;
+} = {}): typeof globalThis.fetch
+```
+
+#### `tagForPath`
+
+The cache tag of an API path — what a webhook topic will invalidate. Personal and live data
+(customer, cart, checkout, orders, search, stock-bearing listings are still catalog) get none:
+they must never be cached across visitors.
+
+```ts
+function tagForPath(pathname: string): string | null
+```
+
+#### `tagsForTopic`
+
+```ts
+function tagsForTopic(topic: string): string[]
+```
+
+#### `verifyWebhookSignature`
+
+Verifies `X-MagicStore-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<raw body>")>` over
+the RAW body, in constant time, with Web Crypto — so it runs in Node, edge runtimes and Workers.
+
+```ts
+async function verifyWebhookSignature(secret: string, header: string | null, rawBody: string, nowSeconds: number = Math.floor(Date.now() / 1000)): Promise<boolean>
+```
+
+### Constants
+
+#### `CACHE_TAGS`
+
+The cache tags a storefront gives what each topic invalidates.
+
+```ts
+const CACHE_TAGS = {
+  shop: 'magicstore:shop',
+  catalog: 'magicstore:catalog',
+  pages: 'magicstore:pages',
+  home: 'magicstore:home',
+} as const
+```
+
+#### `SIGNATURE_TOLERANCE_SECONDS`
+
+How far the signature's timestamp may be from this clock (replay window).
+
+```ts
+const SIGNATURE_TOLERANCE_SECONDS = 300
+```
+
+### Types
+
+#### `WebhookEvent`
+
+```ts
+export interface WebhookEvent {
+    id: string;
+    topic: WebhookTopic | (string & {});
+    shop: string;
+    occurredAt: string;
+    data: Record<string, unknown>;
+}
+```
+
+#### `WebhookHandlerOptions`
+
+```ts
+export interface WebhookHandlerOptions {
+    secret: string;
+    revalidateTag?: (tag: string, profile: 'max') => void | Promise<void>;
+    onEvent?: (event: WebhookEvent) => void | Promise<void>;
+    now?: () => number;
+}
+```
+
+#### `WebhookTopic`
+
+Topics the platform sends today. New ones may be added — ignore what you do not know.
+
+```ts
+export type WebhookTopic = 'SHOP_UPDATED' | 'CATALOG_UPDATED' | 'PAGES_UPDATED' | 'HOME_UPDATED';
+```
+
+## `@magicstoreai/hydrogen/seo`
+
+Page meta and JSON-LD from API resources; server-safe.
+
+### Functions
+
+#### `breadcrumbJsonLd`
+
+schema.org `BreadcrumbList` from `[{ name, url }]`.
+
+```ts
+function breadcrumbJsonLd(items: Array<{
+    name: string;
+    url: string;
+}>): { '@context': string; '@type': string; itemListElement: { '@type': string; position: number; name: string; item: string; }[]; }
+```
+
+#### `jsonLdScript`
+
+A JSON-LD object as a string safe inside `<script>` (no `</script>` break-out).
+
+```ts
+function jsonLdScript(data: unknown): string
+```
+
+#### `pageMeta`
+
+Title and description for a page: the merchant's SEO fields first, then the page's own. Shaped so
+a Next.js `generateMetadata` can return most of it as is.
+
+```ts
+function pageMeta(input: {
+    seo?: Seo | null;
+    title: string;
+    description?: string | null;
+    url?: string | null;
+    images?: Array<{
+        url: string;
+    } | null | undefined>;
+    type?: string;
+    shop?: Pick<Shop, 'name'> | null;
+}): PageMeta
+```
+
+#### `productJsonLd`
+
+schema.org `Product` with its offers — for a `<script type="application/ld+json">`.
+
+```ts
+function productJsonLd(product: Product, options: {
+    url: string;
+    shop?: Pick<Shop, 'name'> | null;
+}): { '@context': string; '@type': string; name: string; description: string | undefined; image: string[]; sku: string | undefined; brand: { '@type': string; name: string; } | undefined; offers: { '@type': string; ... 4 more ...; url: string; }[] | undefined; aggregateRating: { ...; } | undefined; seller: { ...; } | und...
+```
+
+### Types
+
+#### `PageMeta`
+
+```ts
+export interface PageMeta {
+    title: string;
+    description: string | null;
+    canonical: string | null;
+    openGraph: {
+        title: string;
+        description: string | null;
+        url: string | null;
+        images: string[];
+        type: string;
+    };
+}
+```