@hanzo/commerce.js 1.0.0

package/README.md

@@ -0,0 +1,62 @@
+# @hanzo/commerce.js
+
+Modern e-commerce framework for React/Next.js. Wraps @hanzo/commerce with a standalone package.
+
+## Installation
+
+```bash
+npm install @hanzo/commerce.js
+```
+
+## Quick Start
+
+```tsx
+import { 
+  ProductCard, 
+  AddToCartWidget, 
+  CartPanel,
+  CommerceProvider 
+} from '@hanzo/commerce.js'
+
+function Shop({ products }) {
+  return (
+    <CommerceProvider>
+      <div className="products">
+        {products.map(product => (
+          <ProductCard key={product.id} product={product}>
+            <AddToCartWidget sku={product.sku} />
+          </ProductCard>
+        ))}
+      </div>
+      <CartPanel />
+    </CommerceProvider>
+  )
+}
+```
+
+## Components
+
+### Product Display
+- `ProductCard` - Display product information
+- `CarouselBuyCard` - Product card with carousel
+- `Icons` - Commerce icons
+
+### Cart
+- `CartPanel` - Shopping cart sidebar
+- `AddToCartWidget` - Add to cart button with quantity
+
+### Checkout
+- `PaymentStepForm` - Payment form step
+- `ShippingStepForm` - Shipping form step
+
+## Types
+
+Import types from the `/types` subpath:
+
+```ts
+import type { Product, LineItem, CartItem } from '@hanzo/commerce.js/types'
+```
+
+## License
+
+BSD-3-Clause

package/dist/billing.d.mts

@@ -0,0 +1,163 @@
+/**
+ * @hanzo/commerce.js/billing
+ *
+ * THE canonical billing client for the Hanzo platform.
+ * Talks to Commerce API (Go backend) for all billing operations:
+ * balance, usage, deposits, subscriptions, checkout, plans.
+ *
+ * One SDK, one way to do billing. All services use this.
+ *
+ * @example
+ * ```ts
+ * import { BillingClient } from '@hanzo/commerce.js/billing'
+ *
+ * const billing = new BillingClient({
+ *   commerceUrl: 'https://commerce.hanzo.ai',
+ *   token: iamAccessToken,
+ * })
+ *
+ * // Check balance
+ * const balance = await billing.getBalance('hanzo/alice')
+ *
+ * // Record usage
+ * await billing.addUsageRecord({
+ *   user: 'hanzo/alice',
+ *   amount: 150,
+ *   model: 'claude-opus-4-6',
+ *   tokens: 5000,
+ * })
+ *
+ * // Subscribe
+ * await billing.subscribe({ planId: 'growth', userId: 'hanzo/alice' })
+ * ```
+ */
+type CommerceConfig = {
+    /** Commerce API base URL (e.g. "https://commerce.hanzo.ai"). */
+    commerceUrl: string;
+    /** Optional IAM access token for authenticated requests. */
+    token?: string;
+};
+type Balance = {
+    balance: number;
+    holds: number;
+    available: number;
+};
+type Transaction = {
+    id?: string;
+    owner?: string;
+    type: 'hold' | 'hold-removed' | 'transfer' | 'deposit' | 'withdraw';
+    destinationId?: string;
+    destinationKind?: string;
+    sourceId?: string;
+    sourceKind?: string;
+    currency: string;
+    amount: number;
+    tags?: string[];
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+    createdAt?: string;
+};
+type Subscription = {
+    id?: string;
+    planId?: string;
+    userId?: string;
+    status?: 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid' | string;
+    billingType?: 'charge_automatically' | 'send_invoice';
+    periodStart?: string;
+    periodEnd?: string;
+    trialStart?: string;
+    trialEnd?: string;
+    quantity?: number;
+    createdAt?: string;
+};
+type Plan = {
+    slug?: string;
+    name?: string;
+    description?: string;
+    price?: number;
+    currency?: string;
+    interval?: 'monthly' | 'yearly' | string;
+    intervalCount?: number;
+    trialPeriodDays?: number;
+    metadata?: Record<string, unknown>;
+};
+type Payment = {
+    id?: string;
+    orderId?: string;
+    userId?: string;
+    amount?: number;
+    amountRefunded?: number;
+    fee?: number;
+    currency?: string;
+    status?: 'cancelled' | 'credit' | 'disputed' | 'failed' | 'fraudulent' | 'paid' | 'refunded' | 'unpaid' | string;
+    captured?: boolean;
+    live?: boolean;
+    createdAt?: string;
+};
+type UsageRecord = {
+    user: string;
+    currency?: string;
+    amount: number;
+    model?: string;
+    provider?: string;
+    tokens?: number;
+    promptTokens?: number;
+    completionTokens?: number;
+};
+declare class BillingClient {
+    private readonly baseUrl;
+    private token;
+    constructor(config: CommerceConfig);
+    /** Update the auth token (e.g. after IAM token refresh). */
+    setToken(token: string): void;
+    private request;
+    /** Get balance for a user in a specific currency. */
+    getBalance(user: string, currency?: string, token?: string): Promise<Balance>;
+    /** Get balances across all currencies for a user. */
+    getAllBalances(user: string, token?: string): Promise<Record<string, Balance>>;
+    /** Record API usage (creates a withdraw transaction). */
+    addUsageRecord(record: UsageRecord, token?: string): Promise<Transaction>;
+    /** Get usage transactions for a user. */
+    getUsageRecords(user: string, currency?: string, token?: string): Promise<Transaction[]>;
+    /** Create a deposit (credit) for a user. */
+    addDeposit(params: {
+        user: string;
+        currency?: string;
+        amount: number;
+        notes?: string;
+        tags?: string[];
+        expiresIn?: string;
+    }, token?: string): Promise<Transaction>;
+    /** Grant starter credit ($5 USD, 30-day expiry). */
+    grantStarterCredit(user: string, token?: string): Promise<Transaction>;
+    /** Create a new subscription. */
+    subscribe(params: {
+        planId: string;
+        userId: string;
+        paymentToken?: string;
+    }, token?: string): Promise<Subscription>;
+    /** Get a subscription by ID. */
+    getSubscription(subscriptionId: string, token?: string): Promise<Subscription | null>;
+    /** Update a subscription. */
+    updateSubscription(subscriptionId: string, update: Partial<Subscription>, token?: string): Promise<Subscription>;
+    /** Cancel a subscription. */
+    cancelSubscription(subscriptionId: string, token?: string): Promise<void>;
+    /** Authorize a payment for an order. */
+    authorize(orderId: string, token?: string): Promise<Payment>;
+    /** Capture a previously authorized payment. */
+    capture(orderId: string, token?: string): Promise<Payment>;
+    /** Authorize and capture (full charge). */
+    charge(orderId: string, token?: string): Promise<Payment>;
+    /** Refund a payment. */
+    refund(paymentId: string, token?: string): Promise<Payment>;
+    /** Get available plans. */
+    getPlans(token?: string): Promise<Plan[]>;
+    /** Get a specific plan by slug/ID. */
+    getPlan(planId: string, token?: string): Promise<Plan | null>;
+}
+declare class CommerceApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
+export { type Balance, BillingClient, CommerceApiError, type CommerceConfig, type Payment, type Plan, type Subscription, type Transaction, type UsageRecord };

package/dist/billing.d.ts

@@ -0,0 +1,163 @@
+/**
+ * @hanzo/commerce.js/billing
+ *
+ * THE canonical billing client for the Hanzo platform.
+ * Talks to Commerce API (Go backend) for all billing operations:
+ * balance, usage, deposits, subscriptions, checkout, plans.
+ *
+ * One SDK, one way to do billing. All services use this.
+ *
+ * @example
+ * ```ts
+ * import { BillingClient } from '@hanzo/commerce.js/billing'
+ *
+ * const billing = new BillingClient({
+ *   commerceUrl: 'https://commerce.hanzo.ai',
+ *   token: iamAccessToken,
+ * })
+ *
+ * // Check balance
+ * const balance = await billing.getBalance('hanzo/alice')
+ *
+ * // Record usage
+ * await billing.addUsageRecord({
+ *   user: 'hanzo/alice',
+ *   amount: 150,
+ *   model: 'claude-opus-4-6',
+ *   tokens: 5000,
+ * })
+ *
+ * // Subscribe
+ * await billing.subscribe({ planId: 'growth', userId: 'hanzo/alice' })
+ * ```
+ */
+type CommerceConfig = {
+    /** Commerce API base URL (e.g. "https://commerce.hanzo.ai"). */
+    commerceUrl: string;
+    /** Optional IAM access token for authenticated requests. */
+    token?: string;
+};
+type Balance = {
+    balance: number;
+    holds: number;
+    available: number;
+};
+type Transaction = {
+    id?: string;
+    owner?: string;
+    type: 'hold' | 'hold-removed' | 'transfer' | 'deposit' | 'withdraw';
+    destinationId?: string;
+    destinationKind?: string;
+    sourceId?: string;
+    sourceKind?: string;
+    currency: string;
+    amount: number;
+    tags?: string[];
+    expiresAt?: string;
+    metadata?: Record<string, unknown>;
+    createdAt?: string;
+};
+type Subscription = {
+    id?: string;
+    planId?: string;
+    userId?: string;
+    status?: 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid' | string;
+    billingType?: 'charge_automatically' | 'send_invoice';
+    periodStart?: string;
+    periodEnd?: string;
+    trialStart?: string;
+    trialEnd?: string;
+    quantity?: number;
+    createdAt?: string;
+};
+type Plan = {
+    slug?: string;
+    name?: string;
+    description?: string;
+    price?: number;
+    currency?: string;
+    interval?: 'monthly' | 'yearly' | string;
+    intervalCount?: number;
+    trialPeriodDays?: number;
+    metadata?: Record<string, unknown>;
+};
+type Payment = {
+    id?: string;
+    orderId?: string;
+    userId?: string;
+    amount?: number;
+    amountRefunded?: number;
+    fee?: number;
+    currency?: string;
+    status?: 'cancelled' | 'credit' | 'disputed' | 'failed' | 'fraudulent' | 'paid' | 'refunded' | 'unpaid' | string;
+    captured?: boolean;
+    live?: boolean;
+    createdAt?: string;
+};
+type UsageRecord = {
+    user: string;
+    currency?: string;
+    amount: number;
+    model?: string;
+    provider?: string;
+    tokens?: number;
+    promptTokens?: number;
+    completionTokens?: number;
+};
+declare class BillingClient {
+    private readonly baseUrl;
+    private token;
+    constructor(config: CommerceConfig);
+    /** Update the auth token (e.g. after IAM token refresh). */
+    setToken(token: string): void;
+    private request;
+    /** Get balance for a user in a specific currency. */
+    getBalance(user: string, currency?: string, token?: string): Promise<Balance>;
+    /** Get balances across all currencies for a user. */
+    getAllBalances(user: string, token?: string): Promise<Record<string, Balance>>;
+    /** Record API usage (creates a withdraw transaction). */
+    addUsageRecord(record: UsageRecord, token?: string): Promise<Transaction>;
+    /** Get usage transactions for a user. */
+    getUsageRecords(user: string, currency?: string, token?: string): Promise<Transaction[]>;
+    /** Create a deposit (credit) for a user. */
+    addDeposit(params: {
+        user: string;
+        currency?: string;
+        amount: number;
+        notes?: string;
+        tags?: string[];
+        expiresIn?: string;
+    }, token?: string): Promise<Transaction>;
+    /** Grant starter credit ($5 USD, 30-day expiry). */
+    grantStarterCredit(user: string, token?: string): Promise<Transaction>;
+    /** Create a new subscription. */
+    subscribe(params: {
+        planId: string;
+        userId: string;
+        paymentToken?: string;
+    }, token?: string): Promise<Subscription>;
+    /** Get a subscription by ID. */
+    getSubscription(subscriptionId: string, token?: string): Promise<Subscription | null>;
+    /** Update a subscription. */
+    updateSubscription(subscriptionId: string, update: Partial<Subscription>, token?: string): Promise<Subscription>;
+    /** Cancel a subscription. */
+    cancelSubscription(subscriptionId: string, token?: string): Promise<void>;
+    /** Authorize a payment for an order. */
+    authorize(orderId: string, token?: string): Promise<Payment>;
+    /** Capture a previously authorized payment. */
+    capture(orderId: string, token?: string): Promise<Payment>;
+    /** Authorize and capture (full charge). */
+    charge(orderId: string, token?: string): Promise<Payment>;
+    /** Refund a payment. */
+    refund(paymentId: string, token?: string): Promise<Payment>;
+    /** Get available plans. */
+    getPlans(token?: string): Promise<Plan[]>;
+    /** Get a specific plan by slug/ID. */
+    getPlan(planId: string, token?: string): Promise<Plan | null>;
+}
+declare class CommerceApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+
+export { type Balance, BillingClient, CommerceApiError, type CommerceConfig, type Payment, type Plan, type Subscription, type Transaction, type UsageRecord };

package/dist/billing.js

@@ -0,0 +1,200 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/billing.ts
+var billing_exports = {};
+__export(billing_exports, {
+  BillingClient: () => BillingClient,
+  CommerceApiError: () => CommerceApiError
+});
+module.exports = __toCommonJS(billing_exports);
+var DEFAULT_TIMEOUT_MS = 1e4;
+var BillingClient = class {
+  constructor(config) {
+    this.baseUrl = config.commerceUrl.replace(/\/+$/, "");
+    this.token = config.token;
+  }
+  /** Update the auth token (e.g. after IAM token refresh). */
+  setToken(token) {
+    this.token = token;
+  }
+  async request(path, opts) {
+    const url = new URL(path, this.baseUrl);
+    if (opts?.params) {
+      for (const [k, v] of Object.entries(opts.params)) {
+        url.searchParams.set(k, v);
+      }
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    const headers = { Accept: "application/json" };
+    const authToken = opts?.token ?? this.token;
+    if (authToken) headers.Authorization = `Bearer ${authToken}`;
+    if (opts?.body) headers["Content-Type"] = "application/json";
+    try {
+      const res = await fetch(url.toString(), {
+        method: opts?.method ?? "GET",
+        headers,
+        body: opts?.body ? JSON.stringify(opts.body) : void 0,
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new CommerceApiError(res.status, `${res.statusText}: ${text}`.trim());
+      }
+      return await res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Balance
+  // -----------------------------------------------------------------------
+  /** Get balance for a user in a specific currency. */
+  async getBalance(user, currency = "usd", token) {
+    return this.request("/api/v1/billing/balance", {
+      params: { user, currency },
+      token
+    });
+  }
+  /** Get balances across all currencies for a user. */
+  async getAllBalances(user, token) {
+    return this.request("/api/v1/billing/balance/all", {
+      params: { user },
+      token
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Usage
+  // -----------------------------------------------------------------------
+  /** Record API usage (creates a withdraw transaction). */
+  async addUsageRecord(record, token) {
+    return this.request("/api/v1/billing/usage", {
+      method: "POST",
+      body: record,
+      token
+    });
+  }
+  /** Get usage transactions for a user. */
+  async getUsageRecords(user, currency = "usd", token) {
+    return this.request("/api/v1/billing/usage", {
+      params: { user, currency },
+      token
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Deposits / Credits
+  // -----------------------------------------------------------------------
+  /** Create a deposit (credit) for a user. */
+  async addDeposit(params, token) {
+    return this.request("/api/v1/billing/deposit", {
+      method: "POST",
+      body: params,
+      token
+    });
+  }
+  /** Grant starter credit ($5 USD, 30-day expiry). */
+  async grantStarterCredit(user, token) {
+    return this.request("/api/v1/billing/credit", {
+      method: "POST",
+      body: { user },
+      token
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Subscriptions
+  // -----------------------------------------------------------------------
+  /** Create a new subscription. */
+  async subscribe(params, token) {
+    return this.request("/api/v1/subscribe", {
+      method: "POST",
+      body: params,
+      token
+    });
+  }
+  /** Get a subscription by ID. */
+  async getSubscription(subscriptionId, token) {
+    try {
+      return await this.request(`/api/v1/subscribe/${subscriptionId}`, { token });
+    } catch {
+      return null;
+    }
+  }
+  /** Update a subscription. */
+  async updateSubscription(subscriptionId, update, token) {
+    return this.request(`/api/v1/subscribe/${subscriptionId}`, {
+      method: "PATCH",
+      body: update,
+      token
+    });
+  }
+  /** Cancel a subscription. */
+  async cancelSubscription(subscriptionId, token) {
+    await this.request(`/api/v1/subscribe/${subscriptionId}`, {
+      method: "DELETE",
+      token
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Checkout
+  // -----------------------------------------------------------------------
+  /** Authorize a payment for an order. */
+  async authorize(orderId, token) {
+    return this.request(`/api/v1/authorize/${orderId}`, { method: "POST", token });
+  }
+  /** Capture a previously authorized payment. */
+  async capture(orderId, token) {
+    return this.request(`/api/v1/capture/${orderId}`, { method: "POST", token });
+  }
+  /** Authorize and capture (full charge). */
+  async charge(orderId, token) {
+    return this.request(`/api/v1/charge/${orderId}`, { method: "POST", token });
+  }
+  /** Refund a payment. */
+  async refund(paymentId, token) {
+    return this.request(`/api/v1/refund/${paymentId}`, { method: "POST", token });
+  }
+  // -----------------------------------------------------------------------
+  // Plans
+  // -----------------------------------------------------------------------
+  /** Get available plans. */
+  async getPlans(token) {
+    return this.request("/api/v1/plan", { token });
+  }
+  /** Get a specific plan by slug/ID. */
+  async getPlan(planId, token) {
+    try {
+      return await this.request(`/api/v1/plan/${planId}`, { token });
+    } catch {
+      return null;
+    }
+  }
+};
+var CommerceApiError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.name = "CommerceApiError";
+    this.status = status;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BillingClient,
+  CommerceApiError
+});

package/dist/billing.mjs

@@ -0,0 +1,174 @@
+// src/billing.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+var BillingClient = class {
+  constructor(config) {
+    this.baseUrl = config.commerceUrl.replace(/\/+$/, "");
+    this.token = config.token;
+  }
+  /** Update the auth token (e.g. after IAM token refresh). */
+  setToken(token) {
+    this.token = token;
+  }
+  async request(path, opts) {
+    const url = new URL(path, this.baseUrl);
+    if (opts?.params) {
+      for (const [k, v] of Object.entries(opts.params)) {
+        url.searchParams.set(k, v);
+      }
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+    const headers = { Accept: "application/json" };
+    const authToken = opts?.token ?? this.token;
+    if (authToken) headers.Authorization = `Bearer ${authToken}`;
+    if (opts?.body) headers["Content-Type"] = "application/json";
+    try {
+      const res = await fetch(url.toString(), {
+        method: opts?.method ?? "GET",
+        headers,
+        body: opts?.body ? JSON.stringify(opts.body) : void 0,
+        signal: controller.signal
+      });
+      if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new CommerceApiError(res.status, `${res.statusText}: ${text}`.trim());
+      }
+      return await res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  // -----------------------------------------------------------------------
+  // Balance
+  // -----------------------------------------------------------------------
+  /** Get balance for a user in a specific currency. */
+  async getBalance(user, currency = "usd", token) {
+    return this.request("/api/v1/billing/balance", {
+      params: { user, currency },
+      token
+    });
+  }
+  /** Get balances across all currencies for a user. */
+  async getAllBalances(user, token) {
+    return this.request("/api/v1/billing/balance/all", {
+      params: { user },
+      token
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Usage
+  // -----------------------------------------------------------------------
+  /** Record API usage (creates a withdraw transaction). */
+  async addUsageRecord(record, token) {
+    return this.request("/api/v1/billing/usage", {
+      method: "POST",
+      body: record,
+      token
+    });
+  }
+  /** Get usage transactions for a user. */
+  async getUsageRecords(user, currency = "usd", token) {
+    return this.request("/api/v1/billing/usage", {
+      params: { user, currency },
+      token
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Deposits / Credits
+  // -----------------------------------------------------------------------
+  /** Create a deposit (credit) for a user. */
+  async addDeposit(params, token) {
+    return this.request("/api/v1/billing/deposit", {
+      method: "POST",
+      body: params,
+      token
+    });
+  }
+  /** Grant starter credit ($5 USD, 30-day expiry). */
+  async grantStarterCredit(user, token) {
+    return this.request("/api/v1/billing/credit", {
+      method: "POST",
+      body: { user },
+      token
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Subscriptions
+  // -----------------------------------------------------------------------
+  /** Create a new subscription. */
+  async subscribe(params, token) {
+    return this.request("/api/v1/subscribe", {
+      method: "POST",
+      body: params,
+      token
+    });
+  }
+  /** Get a subscription by ID. */
+  async getSubscription(subscriptionId, token) {
+    try {
+      return await this.request(`/api/v1/subscribe/${subscriptionId}`, { token });
+    } catch {
+      return null;
+    }
+  }
+  /** Update a subscription. */
+  async updateSubscription(subscriptionId, update, token) {
+    return this.request(`/api/v1/subscribe/${subscriptionId}`, {
+      method: "PATCH",
+      body: update,
+      token
+    });
+  }
+  /** Cancel a subscription. */
+  async cancelSubscription(subscriptionId, token) {
+    await this.request(`/api/v1/subscribe/${subscriptionId}`, {
+      method: "DELETE",
+      token
+    });
+  }
+  // -----------------------------------------------------------------------
+  // Checkout
+  // -----------------------------------------------------------------------
+  /** Authorize a payment for an order. */
+  async authorize(orderId, token) {
+    return this.request(`/api/v1/authorize/${orderId}`, { method: "POST", token });
+  }
+  /** Capture a previously authorized payment. */
+  async capture(orderId, token) {
+    return this.request(`/api/v1/capture/${orderId}`, { method: "POST", token });
+  }
+  /** Authorize and capture (full charge). */
+  async charge(orderId, token) {
+    return this.request(`/api/v1/charge/${orderId}`, { method: "POST", token });
+  }
+  /** Refund a payment. */
+  async refund(paymentId, token) {
+    return this.request(`/api/v1/refund/${paymentId}`, { method: "POST", token });
+  }
+  // -----------------------------------------------------------------------
+  // Plans
+  // -----------------------------------------------------------------------
+  /** Get available plans. */
+  async getPlans(token) {
+    return this.request("/api/v1/plan", { token });
+  }
+  /** Get a specific plan by slug/ID. */
+  async getPlan(planId, token) {
+    try {
+      return await this.request(`/api/v1/plan/${planId}`, { token });
+    } catch {
+      return null;
+    }
+  }
+};
+var CommerceApiError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.name = "CommerceApiError";
+    this.status = status;
+  }
+};
+export {
+  BillingClient,
+  CommerceApiError
+};

package/dist/index.d.mts

@@ -0,0 +1,2 @@
+export * from '@hanzo/commerce';
+import '@hanzo/commerce/types';

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from '@hanzo/commerce';
+import '@hanzo/commerce/types';

package/dist/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+module.exports = __toCommonJS(index_exports);
+__reExport(index_exports, require("@hanzo/commerce"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("@hanzo/commerce")
+});

package/dist/index.mjs

@@ -0,0 +1,2 @@
+// src/index.ts
+export * from "@hanzo/commerce";

package/dist/types.d.mts

@@ -0,0 +1 @@
+export * from '@hanzo/commerce/types';

package/dist/types.d.ts

@@ -0,0 +1 @@
+export * from '@hanzo/commerce/types';

package/dist/types.js

@@ -0,0 +1,24 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/types.ts
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);
+__reExport(types_exports, require("@hanzo/commerce/types"), module.exports);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ...require("@hanzo/commerce/types")
+});

package/dist/types.mjs

@@ -0,0 +1,2 @@
+// src/types.ts
+export * from "@hanzo/commerce/types";

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@hanzo/commerce.js",
+  "version": "1.0.0",
+  "description": "Hanzo Commerce SDK - Modern e-commerce framework. Wraps @hanzo/commerce.",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./types": {
+      "import": "./dist/types.mjs",
+      "require": "./dist/types.js",
+      "types": "./dist/types.d.ts"
+    },
+    "./billing": {
+      "import": "./dist/billing.mjs",
+      "require": "./dist/billing.js",
+      "types": "./dist/billing.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/types.ts src/billing.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts src/types.ts src/billing.ts --format cjs,esm --dts --watch",
+    "prepublishOnly": "npm run build",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hanzo-js/commerce.js.git"
+  },
+  "keywords": [
+    "commerce",
+    "ecommerce",
+    "cart",
+    "checkout",
+    "payments",
+    "hanzo",
+    "react",
+    "nextjs"
+  ],
+  "author": "Hanzo AI, Inc. <hi@hanzo.ai>",
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/hanzo-js/commerce.js/issues"
+  },
+  "homepage": "https://github.com/hanzo-js/commerce.js#readme",
+  "dependencies": {
+    "@hanzo/commerce": "^7.3.10"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "next": ">=14.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  }
+}

package/src/billing.ts

@@ -0,0 +1,328 @@
+/**
+ * @hanzo/commerce.js/billing
+ *
+ * THE canonical billing client for the Hanzo platform.
+ * Talks to Commerce API (Go backend) for all billing operations:
+ * balance, usage, deposits, subscriptions, checkout, plans.
+ *
+ * One SDK, one way to do billing. All services use this.
+ *
+ * @example
+ * ```ts
+ * import { BillingClient } from '@hanzo/commerce.js/billing'
+ *
+ * const billing = new BillingClient({
+ *   commerceUrl: 'https://commerce.hanzo.ai',
+ *   token: iamAccessToken,
+ * })
+ *
+ * // Check balance
+ * const balance = await billing.getBalance('hanzo/alice')
+ *
+ * // Record usage
+ * await billing.addUsageRecord({
+ *   user: 'hanzo/alice',
+ *   amount: 150,
+ *   model: 'claude-opus-4-6',
+ *   tokens: 5000,
+ * })
+ *
+ * // Subscribe
+ * await billing.subscribe({ planId: 'growth', userId: 'hanzo/alice' })
+ * ```
+ */
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+export type CommerceConfig = {
+  /** Commerce API base URL (e.g. "https://commerce.hanzo.ai"). */
+  commerceUrl: string
+  /** Optional IAM access token for authenticated requests. */
+  token?: string
+}
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type Balance = {
+  balance: number
+  holds: number
+  available: number
+}
+
+export type Transaction = {
+  id?: string
+  owner?: string
+  type: 'hold' | 'hold-removed' | 'transfer' | 'deposit' | 'withdraw'
+  destinationId?: string
+  destinationKind?: string
+  sourceId?: string
+  sourceKind?: string
+  currency: string
+  amount: number
+  tags?: string[]
+  expiresAt?: string
+  metadata?: Record<string, unknown>
+  createdAt?: string
+}
+
+export type Subscription = {
+  id?: string
+  planId?: string
+  userId?: string
+  status?: 'trialing' | 'active' | 'past_due' | 'canceled' | 'unpaid' | string
+  billingType?: 'charge_automatically' | 'send_invoice'
+  periodStart?: string
+  periodEnd?: string
+  trialStart?: string
+  trialEnd?: string
+  quantity?: number
+  createdAt?: string
+}
+
+export type Plan = {
+  slug?: string
+  name?: string
+  description?: string
+  price?: number
+  currency?: string
+  interval?: 'monthly' | 'yearly' | string
+  intervalCount?: number
+  trialPeriodDays?: number
+  metadata?: Record<string, unknown>
+}
+
+export type Payment = {
+  id?: string
+  orderId?: string
+  userId?: string
+  amount?: number
+  amountRefunded?: number
+  fee?: number
+  currency?: string
+  status?: 'cancelled' | 'credit' | 'disputed' | 'failed' | 'fraudulent' | 'paid' | 'refunded' | 'unpaid' | string
+  captured?: boolean
+  live?: boolean
+  createdAt?: string
+}
+
+export type UsageRecord = {
+  user: string
+  currency?: string
+  amount: number
+  model?: string
+  provider?: string
+  tokens?: number
+  promptTokens?: number
+  completionTokens?: number
+}
+
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
+
+const DEFAULT_TIMEOUT_MS = 10_000
+
+export class BillingClient {
+  private readonly baseUrl: string
+  private token: string | undefined
+
+  constructor(config: CommerceConfig) {
+    this.baseUrl = config.commerceUrl.replace(/\/+$/, '')
+    this.token = config.token
+  }
+
+  /** Update the auth token (e.g. after IAM token refresh). */
+  setToken(token: string) {
+    this.token = token
+  }
+
+  private async request<T>(
+    path: string,
+    opts?: {
+      method?: string
+      body?: unknown
+      token?: string
+      params?: Record<string, string>
+    },
+  ): Promise<T> {
+    const url = new URL(path, this.baseUrl)
+    if (opts?.params) {
+      for (const [k, v] of Object.entries(opts.params)) {
+        url.searchParams.set(k, v)
+      }
+    }
+
+    const controller = new AbortController()
+    const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS)
+
+    const headers: Record<string, string> = { Accept: 'application/json' }
+    const authToken = opts?.token ?? this.token
+    if (authToken) headers.Authorization = `Bearer ${authToken}`
+    if (opts?.body) headers['Content-Type'] = 'application/json'
+
+    try {
+      const res = await fetch(url.toString(), {
+        method: opts?.method ?? 'GET',
+        headers,
+        body: opts?.body ? JSON.stringify(opts.body) : undefined,
+        signal: controller.signal,
+      })
+
+      if (!res.ok) {
+        const text = await res.text().catch(() => '')
+        throw new CommerceApiError(res.status, `${res.statusText}: ${text}`.trim())
+      }
+
+      return (await res.json()) as T
+    } finally {
+      clearTimeout(timer)
+    }
+  }
+
+  // -----------------------------------------------------------------------
+  // Balance
+  // -----------------------------------------------------------------------
+
+  /** Get balance for a user in a specific currency. */
+  async getBalance(user: string, currency = 'usd', token?: string): Promise<Balance> {
+    return this.request<Balance>('/api/v1/billing/balance', {
+      params: { user, currency }, token,
+    })
+  }
+
+  /** Get balances across all currencies for a user. */
+  async getAllBalances(user: string, token?: string): Promise<Record<string, Balance>> {
+    return this.request<Record<string, Balance>>('/api/v1/billing/balance/all', {
+      params: { user }, token,
+    })
+  }
+
+  // -----------------------------------------------------------------------
+  // Usage
+  // -----------------------------------------------------------------------
+
+  /** Record API usage (creates a withdraw transaction). */
+  async addUsageRecord(record: UsageRecord, token?: string): Promise<Transaction> {
+    return this.request<Transaction>('/api/v1/billing/usage', {
+      method: 'POST', body: record, token,
+    })
+  }
+
+  /** Get usage transactions for a user. */
+  async getUsageRecords(user: string, currency = 'usd', token?: string): Promise<Transaction[]> {
+    return this.request<Transaction[]>('/api/v1/billing/usage', {
+      params: { user, currency }, token,
+    })
+  }
+
+  // -----------------------------------------------------------------------
+  // Deposits / Credits
+  // -----------------------------------------------------------------------
+
+  /** Create a deposit (credit) for a user. */
+  async addDeposit(
+    params: { user: string; currency?: string; amount: number; notes?: string; tags?: string[]; expiresIn?: string },
+    token?: string,
+  ): Promise<Transaction> {
+    return this.request<Transaction>('/api/v1/billing/deposit', {
+      method: 'POST', body: params, token,
+    })
+  }
+
+  /** Grant starter credit ($5 USD, 30-day expiry). */
+  async grantStarterCredit(user: string, token?: string): Promise<Transaction> {
+    return this.request<Transaction>('/api/v1/billing/credit', {
+      method: 'POST', body: { user }, token,
+    })
+  }
+
+  // -----------------------------------------------------------------------
+  // Subscriptions
+  // -----------------------------------------------------------------------
+
+  /** Create a new subscription. */
+  async subscribe(params: { planId: string; userId: string; paymentToken?: string }, token?: string): Promise<Subscription> {
+    return this.request<Subscription>('/api/v1/subscribe', {
+      method: 'POST', body: params, token,
+    })
+  }
+
+  /** Get a subscription by ID. */
+  async getSubscription(subscriptionId: string, token?: string): Promise<Subscription | null> {
+    try {
+      return await this.request<Subscription>(`/api/v1/subscribe/${subscriptionId}`, { token })
+    } catch { return null }
+  }
+
+  /** Update a subscription. */
+  async updateSubscription(subscriptionId: string, update: Partial<Subscription>, token?: string): Promise<Subscription> {
+    return this.request<Subscription>(`/api/v1/subscribe/${subscriptionId}`, {
+      method: 'PATCH', body: update, token,
+    })
+  }
+
+  /** Cancel a subscription. */
+  async cancelSubscription(subscriptionId: string, token?: string): Promise<void> {
+    await this.request<void>(`/api/v1/subscribe/${subscriptionId}`, {
+      method: 'DELETE', token,
+    })
+  }
+
+  // -----------------------------------------------------------------------
+  // Checkout
+  // -----------------------------------------------------------------------
+
+  /** Authorize a payment for an order. */
+  async authorize(orderId: string, token?: string): Promise<Payment> {
+    return this.request<Payment>(`/api/v1/authorize/${orderId}`, { method: 'POST', token })
+  }
+
+  /** Capture a previously authorized payment. */
+  async capture(orderId: string, token?: string): Promise<Payment> {
+    return this.request<Payment>(`/api/v1/capture/${orderId}`, { method: 'POST', token })
+  }
+
+  /** Authorize and capture (full charge). */
+  async charge(orderId: string, token?: string): Promise<Payment> {
+    return this.request<Payment>(`/api/v1/charge/${orderId}`, { method: 'POST', token })
+  }
+
+  /** Refund a payment. */
+  async refund(paymentId: string, token?: string): Promise<Payment> {
+    return this.request<Payment>(`/api/v1/refund/${paymentId}`, { method: 'POST', token })
+  }
+
+  // -----------------------------------------------------------------------
+  // Plans
+  // -----------------------------------------------------------------------
+
+  /** Get available plans. */
+  async getPlans(token?: string): Promise<Plan[]> {
+    return this.request<Plan[]>('/api/v1/plan', { token })
+  }
+
+  /** Get a specific plan by slug/ID. */
+  async getPlan(planId: string, token?: string): Promise<Plan | null> {
+    try {
+      return await this.request<Plan>(`/api/v1/plan/${planId}`, { token })
+    } catch { return null }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Error
+// ---------------------------------------------------------------------------
+
+export class CommerceApiError extends Error {
+  readonly status: number
+
+  constructor(status: number, message: string) {
+    super(message)
+    this.name = 'CommerceApiError'
+    this.status = status
+  }
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+/**
+ * commerce.js
+ *
+ * Hanzo Commerce SDK - Modern e-commerce framework for React/Next.js.
+ * This package re-exports @hanzo/commerce for easy standalone usage.
+ *
+ * @example
+ * ```tsx
+ * import { AddToCartWidget, CartPanel, ProductCard } from 'commerce.js'
+ *
+ * function ProductPage({ product }) {
+ *   return (
+ *     <div>
+ *       <ProductCard product={product} />
+ *       <AddToCartWidget sku={product.sku} />
+ *     </div>
+ *   )
+ * }
+ * ```
+ */
+
+// Re-export everything from @hanzo/commerce
+export * from '@hanzo/commerce'

package/src/types.ts

@@ -0,0 +1,7 @@
+/**
+ * commerce.js/types
+ *
+ * Type definitions for Hanzo Commerce
+ */
+
+export * from '@hanzo/commerce/types'