@magicstoreai/hydrogen 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MagicStore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @magicstoreai/hydrogen
+
+React building blocks for MagicStore storefronts, on top of
+[`@magicstoreai/storefront-client`](../storefront-client). The backend is the same for every
+storefront; this package is the part every storefront would otherwise write again.
+
+| Entry                           | What                                                                                                                                                          | Runs                    |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
+| `@magicstoreai/hydrogen`        | `MagicStoreProvider`, `useCustomer`, `useCart`, `useWishlist`, `useAnalytics`, `useVariantSelection`, `ProductProvider`, `<Money>`, `<Image>`, `<Pagination>` | client (`"use client"`) |
+| `@magicstoreai/hydrogen/core`   | The same logic without React: `CartController`, `CustomerSessionController`, `WishlistController`, `AnalyticsController`, `formatMoney`, variant selection    | anywhere                |
+| `@magicstoreai/hydrogen/server` | `createWebhookHandler`, `verifyWebhookSignature`, `nextCacheFetch`, cache tags                                                                                | server, edge            |
+| `@magicstoreai/hydrogen/seo`    | `pageMeta`, `productJsonLd`, `breadcrumbJsonLd`, `jsonLdScript`                                                                                               | anywhere                |
+
+Every export with its props or signature, an example and the API operations it calls:
+[CATALOGUE.md](CATALOGUE.md) — generated from the sources (`pnpm --filter @magicstoreai/hydrogen
+catalogue`) and shipped in the package. A test fails when it is stale or a component or hook has no
+`@example` in its TSDoc; `@wraps Controller` gives a hook its controller's operations.
+
+## A storefront in a few lines
+
+```tsx
+'use client';
+import { MagicStoreProvider, Money, useCart, useVariantSelection } from '@magicstoreai/hydrogen';
+
+export function Providers({ shop, children }) {
+  return (
+    <MagicStoreProvider shopDomain="shop.example.uz" shop={shop} locale="uz">
+      {children}
+    </MagicStoreProvider>
+  );
+}
+
+export function BuyBox({ product }) {
+  const { selectedVariant, setOption, isAvailable } = useVariantSelection(product);
+  const { addLine, status } = useCart();
+  return (
+    <>
+      <Money data={selectedVariant?.price ?? product.price} />
+      {product.options.map((option) =>
+        option.values.map((value) => (
+          <button
+            key={value}
+            disabled={!isAvailable(option.name, value)}
+            onClick={() => setOption(option.name, value)}
+          >
+            {value}
+          </button>
+        )),
+      )}
+      <button
+        disabled={!selectedVariant?.availableForSale || status === 'updating'}
+        onClick={() => addLine({ productId: product.id, variantId: selectedVariant!.id })}
+      >
+        Add to cart
+      </button>
+    </>
+  );
+}
+```
+
+## What it takes care of
+
+- **Customer.** OTP, Telegram `initData`, OQ and Click sign-in; the session is kept in storage and the
+  hourly access token is refreshed before it expires — one refresh for every caller waiting.
+- **Cart.** The cart id is kept, never shown; the first add creates the cart; quantity changes show
+  at once and roll back if the server refuses; changes go out in order; a cart the server no longer
+  has is dropped. On sign-in the cart becomes the customer's (merged into theirs if they had one);
+  on sign-out it stays with the customer.
+- **Wishlist.** A guest's list lives in the browser and moves into the customer's list at sign-in.
+- **Money.** `shop.moneyFormat` and the locale decide the symbol and its place (`12 500 сум`,
+  `$129.99`). Amounts are never rounded on the client.
+- **Analytics.** Page, product, collection views and searches, batched; the visitor id also goes out
+  as `X-Session-Id`, so carts and orders join the visit. Cart and checkout steps are recorded by the
+  server.
+
+## Next.js cache + webhooks
+
+```ts
+// lib/magicstore.ts — server side
+import { createStorefrontClient } from '@magicstoreai/storefront-client';
+import { nextCacheFetch } from '@magicstoreai/hydrogen/server';
+
+export const api = createStorefrontClient({
+  shopDomain: process.env.SHOP_DOMAIN!,
+  fetch: nextCacheFetch(),
+});
+
+// app/api/magicstore/webhook/route.ts
+import { revalidateTag } from 'next/cache';
+import { createWebhookHandler } from '@magicstoreai/hydrogen/server';
+
+export const POST = createWebhookHandler({
+  secret: process.env.MAGICSTORE_WEBHOOK_SECRET!,
+  revalidateTag,
+});
+```
+
+Public reads are cached under `magicstore:shop | catalog | pages | home`; the matching webhook topic
+revalidates them. Anything personal (a customer token on the call, carts, checkouts, orders) is
+`no-store`.