@numueg/theme-sdk 0.1.2

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to `@numueg/theme-sdk` are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-11
+
+First public release. Full surface documented at [numueg.app/docs/sdk/overview](https://numueg.app/docs/sdk/overview).
+
+### Added
+
+- **25+ hooks**: `useShop`, `useThemeSettings`, `useLocalization`, `useDirection`, `useTranslation`, `useCurrency`, `usePage`, `useProduct(Optional)`, `useProducts`, `useCollection(Optional)`, `useCollections`, `useVariantSelection`, `useRelatedProducts`, `useCart`, `useCustomer`, `useCustomerActions`, `useCustomerAddresses`, `useOrders`, `useOrder`, `useReorder`, `useGiftCardBalance`, `useCheckout`, `useShippingRates`, `useSearch`, `useNavigation`, `useAnalytics`, `useApp`, `useWishlist`, `useSection(Optional)`, `useImage`, `useMoney`.
+- **15+ components**: `NuMuProvider`, `ProductProvider`, `CollectionProvider`, `Section`, `Block`, `Image`, `Money`, `Link`, `Form`, `AddToCartButton`, `ProductCard`, `CollectionCard`, `RichText`, `CurrencySwitcher`, `LocaleSwitcher`, `CookieConsent`.
+- **Variant helpers**: `findVariantByOptions`, `defaultVariant`, `availableValues`.
+- **Federation runtime helpers**: `registerSdkSingleton`, `getSdkSingleton`, `registerReactSingleton`, `getReactSingleton`, `isSdkAvailable`.
+- **Asset + format helpers**: `assetUrl`, `sanitizeHtml`, `resolveThemeSettings`.
+- Dual ESM + CJS build via `tsup` with full `.d.ts` types.
+- React 18 + 19 supported via `peerDependencies`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NUMU
+
+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,64 @@
+# @numueg/theme-sdk
+
+> React hooks + components + helpers for building NUMU storefront themes.
+
+[![npm](https://img.shields.io/npm/v/@numueg/theme-sdk.svg)](https://www.npmjs.com/package/@numueg/theme-sdk)
+[![license](https://img.shields.io/npm/l/@numueg/theme-sdk.svg)](./LICENSE)
+
+The SDK every NUMU theme consumes. 25+ hooks (`useCart`, `useProduct`, `useCheckout`, `useVariantSelection`, `useGiftCardBalance`, …), 15+ components (`AddToCartButton`, `ProductCard`, `Money`, `Section`, `NuMuProvider`, …), and helpers for variant resolution, asset URLs, and federation singletons.
+
+Themes import via the bare specifier `@numueg/theme-sdk` — at runtime the storefront's import map resolves it to the host-loaded singleton so every theme on the platform shares one React identity.
+
+## Install
+
+```bash
+npm install --save-peer @numueg/theme-sdk react react-dom
+```
+
+Then externalize all three in `vite.config.ts`:
+
+```ts
+export default defineConfig({
+  build: {
+    rollupOptions: {
+      external: ["react", "react-dom", "react/jsx-runtime", "react-dom/client", "@numueg/theme-sdk"],
+    },
+  },
+});
+```
+
+The `@numueg/theme-plugin` Vite plugin does this for you automatically.
+
+## Usage
+
+```tsx
+import { createRoot } from "react-dom/client";
+import { NuMuProvider, useCart, AddToCartButton } from "@numueg/theme-sdk";
+import type { MountContext } from "@numueg/theme-sdk";
+
+function App() {
+  const { cart } = useCart();
+  return <p>Items in cart: {cart.item_count}</p>;
+}
+
+export function mount(ctx: MountContext) {
+  const root = createRoot(document.getElementById("numu-root")!);
+  root.render(<NuMuProvider {...ctx}><App /></NuMuProvider>);
+  return () => root.unmount();
+}
+```
+
+## Docs
+
+- [SDK Overview](https://numueg.app/docs/sdk/overview)
+- [Hooks Reference](https://numueg.app/docs/sdk/hooks)
+- [Components Reference](https://numueg.app/docs/sdk/components)
+- [Type Definitions](https://numueg.app/docs/sdk/types)
+
+## React versions
+
+Supports React 18 and 19. Declared via `peerDependencies`.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/index-CGx6FNqb.d.ts

@@ -0,0 +1,167 @@
+import './theme-NWJAU9jd.js';
+
+/** Core store entity */
+interface Store {
+    id: string;
+    name: string;
+    slug: string;
+    domain?: string;
+    subdomain?: string;
+    logo_url?: string;
+    description?: string;
+    currency: string;
+    default_language: string;
+    use_nextjs_storefront: boolean;
+    social_links?: Record<string, string>;
+}
+/** Product entity */
+interface Product {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    price: number;
+    compare_at_price?: number;
+    currency: string;
+    images: ProductImage[];
+    /** Option axes (Size / Color / Material / ...). Phase 8.1. */
+    options?: ProductOption[];
+    variants: ProductVariant[];
+    category?: string;
+    tags?: string[];
+    in_stock: boolean;
+    seo_title?: string;
+    seo_description?: string;
+}
+interface ProductImage {
+    id: string;
+    url: string;
+    alt?: string;
+    position: number;
+}
+/**
+ * One option axis declared on a product — Phase 8.1.
+ *
+ * Variants reference these by `name`, picking one value per axis to
+ * form their `option_values` map. A T-shirt with options
+ * `[{name:"Size",values:["S","M","L"]}, {name:"Color",values:["Red","Blue"]}]`
+ * has 6 variants, one per (Size, Color) pair.
+ */
+interface ProductOption {
+    name: string;
+    position: number;
+    values: string[];
+}
+/**
+ * One purchasable variant — Phase 8.1.
+ *
+ * Themes render a variant picker by mapping each `ProductOption` to a
+ * set of radio buttons / swatches, then finding the matching variant
+ * via `option_values`. The matching variant's `id` is what
+ * `add-to-cart` sends. Use the SDK helper `findVariantByOptions()` to
+ * pick the right row given a partial selection.
+ *
+ * Note: `price` and `compare_at_price` are cents (integers), not
+ * decimal — the backend ships these as string-decimals; the SDK
+ * parses them to numbers when hydrating.
+ */
+interface ProductVariant {
+    id: string;
+    position: number;
+    /** Axis-name → chosen-value map. Single-variant products have `{}`. */
+    option_values: Record<string, string>;
+    price: number;
+    price_currency?: string;
+    compare_at_price?: number | null;
+    sku?: string | null;
+    barcode?: string | null;
+    inventory_quantity: number;
+    is_in_stock: boolean;
+    image_url?: string | null;
+    weight?: number | null;
+    /** Legacy field — kept for backward compat with pre-Phase-8.1 themes
+     *  that read `variant.name`. The backend stops setting this in 8.1;
+     *  themes should switch to formatting `option_values` themselves. */
+    name?: string;
+    /** Alias for `is_in_stock`; preserved for backward compat. */
+    in_stock?: boolean;
+    /** Alias for `option_values`; preserved for backward compat. */
+    options?: Record<string, string>;
+}
+/** Collection entity */
+interface Collection {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    image_url?: string;
+    product_count: number;
+    products?: Product[];
+}
+/** Cart entity */
+interface Cart {
+    id: string;
+    items: CartItem[];
+    subtotal: number;
+    total: number;
+    currency: string;
+    discount_code?: string;
+    discount_amount?: number;
+    note?: string;
+}
+interface CartItem {
+    id: string;
+    product_id: string;
+    variant_id?: string;
+    name: string;
+    image_url?: string;
+    price: number;
+    quantity: number;
+    variant_name?: string;
+}
+/** Customer entity */
+interface Customer {
+    id: string;
+    email: string;
+    first_name?: string;
+    last_name?: string;
+    phone?: string;
+    avatar_url?: string;
+    orders_count: number;
+    total_spent: number;
+}
+/** Order entity */
+interface Order {
+    id: string;
+    order_number: string;
+    status: string;
+    total: number;
+    currency: string;
+    items: OrderItem[];
+    created_at: string;
+    shipping_address?: Address;
+}
+interface OrderItem {
+    product_id: string;
+    variant_id?: string;
+    name: string;
+    quantity: number;
+    price: number;
+}
+interface Address {
+    line1: string;
+    line2?: string;
+    city: string;
+    state?: string;
+    postal_code?: string;
+    country: string;
+}
+/** Page entity */
+interface Page {
+    type: string;
+    title: string;
+    handle?: string;
+    data?: Record<string, any>;
+}
+
+export type { Address as A, Collection as C, Order as O, Product as P, Store as S, Cart as a, Customer as b, Page as c, ProductVariant as d, CartItem as e, OrderItem as f, ProductImage as g, ProductOption as h };

package/dist/index-zSb0FIyh.d.mts

@@ -0,0 +1,167 @@
+import './theme-NWJAU9jd.mjs';
+
+/** Core store entity */
+interface Store {
+    id: string;
+    name: string;
+    slug: string;
+    domain?: string;
+    subdomain?: string;
+    logo_url?: string;
+    description?: string;
+    currency: string;
+    default_language: string;
+    use_nextjs_storefront: boolean;
+    social_links?: Record<string, string>;
+}
+/** Product entity */
+interface Product {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    price: number;
+    compare_at_price?: number;
+    currency: string;
+    images: ProductImage[];
+    /** Option axes (Size / Color / Material / ...). Phase 8.1. */
+    options?: ProductOption[];
+    variants: ProductVariant[];
+    category?: string;
+    tags?: string[];
+    in_stock: boolean;
+    seo_title?: string;
+    seo_description?: string;
+}
+interface ProductImage {
+    id: string;
+    url: string;
+    alt?: string;
+    position: number;
+}
+/**
+ * One option axis declared on a product — Phase 8.1.
+ *
+ * Variants reference these by `name`, picking one value per axis to
+ * form their `option_values` map. A T-shirt with options
+ * `[{name:"Size",values:["S","M","L"]}, {name:"Color",values:["Red","Blue"]}]`
+ * has 6 variants, one per (Size, Color) pair.
+ */
+interface ProductOption {
+    name: string;
+    position: number;
+    values: string[];
+}
+/**
+ * One purchasable variant — Phase 8.1.
+ *
+ * Themes render a variant picker by mapping each `ProductOption` to a
+ * set of radio buttons / swatches, then finding the matching variant
+ * via `option_values`. The matching variant's `id` is what
+ * `add-to-cart` sends. Use the SDK helper `findVariantByOptions()` to
+ * pick the right row given a partial selection.
+ *
+ * Note: `price` and `compare_at_price` are cents (integers), not
+ * decimal — the backend ships these as string-decimals; the SDK
+ * parses them to numbers when hydrating.
+ */
+interface ProductVariant {
+    id: string;
+    position: number;
+    /** Axis-name → chosen-value map. Single-variant products have `{}`. */
+    option_values: Record<string, string>;
+    price: number;
+    price_currency?: string;
+    compare_at_price?: number | null;
+    sku?: string | null;
+    barcode?: string | null;
+    inventory_quantity: number;
+    is_in_stock: boolean;
+    image_url?: string | null;
+    weight?: number | null;
+    /** Legacy field — kept for backward compat with pre-Phase-8.1 themes
+     *  that read `variant.name`. The backend stops setting this in 8.1;
+     *  themes should switch to formatting `option_values` themselves. */
+    name?: string;
+    /** Alias for `is_in_stock`; preserved for backward compat. */
+    in_stock?: boolean;
+    /** Alias for `option_values`; preserved for backward compat. */
+    options?: Record<string, string>;
+}
+/** Collection entity */
+interface Collection {
+    id: string;
+    name: string;
+    slug: string;
+    description?: string;
+    image_url?: string;
+    product_count: number;
+    products?: Product[];
+}
+/** Cart entity */
+interface Cart {
+    id: string;
+    items: CartItem[];
+    subtotal: number;
+    total: number;
+    currency: string;
+    discount_code?: string;
+    discount_amount?: number;
+    note?: string;
+}
+interface CartItem {
+    id: string;
+    product_id: string;
+    variant_id?: string;
+    name: string;
+    image_url?: string;
+    price: number;
+    quantity: number;
+    variant_name?: string;
+}
+/** Customer entity */
+interface Customer {
+    id: string;
+    email: string;
+    first_name?: string;
+    last_name?: string;
+    phone?: string;
+    avatar_url?: string;
+    orders_count: number;
+    total_spent: number;
+}
+/** Order entity */
+interface Order {
+    id: string;
+    order_number: string;
+    status: string;
+    total: number;
+    currency: string;
+    items: OrderItem[];
+    created_at: string;
+    shipping_address?: Address;
+}
+interface OrderItem {
+    product_id: string;
+    variant_id?: string;
+    name: string;
+    quantity: number;
+    price: number;
+}
+interface Address {
+    line1: string;
+    line2?: string;
+    city: string;
+    state?: string;
+    postal_code?: string;
+    country: string;
+}
+/** Page entity */
+interface Page {
+    type: string;
+    title: string;
+    handle?: string;
+    data?: Record<string, any>;
+}
+
+export type { Address as A, Collection as C, Order as O, Product as P, Store as S, Cart as a, Customer as b, Page as c, ProductVariant as d, CartItem as e, OrderItem as f, ProductImage as g, ProductOption as h };