@hanzo/commerce 7.6.1 → 7.6.3

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 hanzo
+
+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/client.ts

@@ -67,6 +67,29 @@ export type Balance = {
   available: number
 }
 
+/**
+ * Tier-aware balance from GET /v1/billing/tier. effectiveAvailable folds the
+ * tenant's included plan allotment (e.g. the free-tier daily credit) into the
+ * prepaid available balance — gate on this to honor included usage first.
+ */
+export type TierResponse = {
+  user: string
+  tier: {
+    name: string
+    displayName?: string
+    maxAgents?: number
+    unlimitedAgents?: boolean
+    dailyCreditsCents?: number
+    allowedModels?: string[]
+  }
+  balance: {
+    currency: string
+    prepaidAvailable: number
+    dailyRemaining: number
+    effectiveAvailable: number
+  }
+}
+
 export type Transaction = {
   id?: string
   owner?: string
@@ -270,6 +293,17 @@ export type PaymentMethod = {
     expMonth: number
     expYear: number
   }
+  bank_account?: {
+    bankName?: string
+    last4?: string
+    accountType?: 'checking' | 'savings'
+    routingNumber?: string
+  }
+  crypto?: {
+    chain: string
+    address: string
+    label?: string
+  }
   providerRef?: string
   providerType?: string
   createdAt?: string
@@ -349,6 +383,8 @@ export class Commerce {
       body?: unknown
       token?: string
       params?: Record<string, string>
+      /** Extra request headers, e.g. X-IAM-Org-Id for S2S calls. */
+      headers?: Record<string, string>
     },
   ): Promise<T> {
     const url = new URL(path, this.baseUrl)
@@ -365,6 +401,7 @@ export class Commerce {
     const authToken = opts?.token ?? this.token
     if (authToken) headers['Authorization'] = `Bearer ${authToken}`
     if (opts?.body) headers['Content-Type'] = 'application/json'
+    if (opts?.headers) Object.assign(headers, opts.headers)
 
     try {
       const res = await fetch(url.toString(), {
@@ -389,9 +426,9 @@ export class Commerce {
   // Balance
   // -----------------------------------------------------------------------
 
-  async getBalance(user: string, currency = 'usd', token?: string): Promise<Balance> {
+  async getBalance(user: string, currency = 'usd', token?: string, headers?: Record<string, string>): Promise<Balance> {
     return this.request<Balance>('/v1/billing/balance', {
-      params: { user, currency }, token,
+      params: { user, currency }, token, headers,
     })
   }
 
@@ -401,13 +438,25 @@ export class Commerce {
     })
   }
 
+  /**
+   * Tier-aware balance: prepaid available plus the tenant's included plan
+   * allotment (effectiveAvailable). Use this for the metering gate when you
+   * want included usage (e.g. free-tier daily credit) honored before prepaid
+   * funds are drawn down.
+   */
+  async getTier(user: string, opts?: { token?: string; headers?: Record<string, string> }): Promise<TierResponse> {
+    return this.request<TierResponse>('/v1/billing/tier', {
+      params: { user }, token: opts?.token, headers: opts?.headers,
+    })
+  }
+
   // -----------------------------------------------------------------------
   // Usage
   // -----------------------------------------------------------------------
 
-  async addUsageRecord(record: UsageRecord, token?: string): Promise<Transaction> {
+  async addUsageRecord(record: UsageRecord, token?: string, headers?: Record<string, string>): Promise<Transaction> {
     return this.request<Transaction>('/v1/billing/usage', {
-      method: 'POST', body: record, token,
+      method: 'POST', body: record, token, headers,
     })
   }
 
@@ -687,6 +736,73 @@ export class Commerce {
       method: 'POST', body: params, token,
     })
   }
+
+  // -----------------------------------------------------------------------
+  // Crypto wallet deposit address
+  // -----------------------------------------------------------------------
+
+  /**
+   * Get or create a deposit address for a given chain.
+   * Used for crypto top-up — user sends funds to this address.
+   */
+  async getWalletAddress(params: { chain: string; userId: string }, token?: string): Promise<{ address: string; chain: string; qrCode?: string }> {
+    return this.request<{ address: string; chain: string; qrCode?: string }>('/api/wallet/account', {
+      method: 'POST',
+      body: { name: `${params.userId}-${params.chain}`, blockchainType: params.chain },
+      token,
+    })
+  }
+
+  // -----------------------------------------------------------------------
+  // Bank account (ACH) and crypto payment methods
+  // -----------------------------------------------------------------------
+
+  /**
+   * Add a bank account payment method (ACH).
+   * plaidToken from Plaid Link or Square bank OAuth.
+   */
+  async addBankAccount(
+    params: {
+      customerId: string
+      plaidToken?: string  // Plaid public token
+      bankName?: string
+      accountType?: 'checking' | 'savings'
+    },
+    token?: string,
+  ): Promise<PaymentMethod> {
+    return this.request<PaymentMethod>('/v1/billing/payment-methods', {
+      method: 'POST',
+      body: { customerId: params.customerId, type: 'bank_account', plaidToken: params.plaidToken, bankName: params.bankName, accountType: params.accountType },
+      token,
+    })
+  }
+
+  async addCryptoWallet(
+    params: { customerId: string; chain: string; address: string; label?: string },
+    token?: string,
+  ): Promise<PaymentMethod> {
+    return this.request<PaymentMethod>('/v1/billing/payment-methods', {
+      method: 'POST',
+      body: { customerId: params.customerId, type: 'crypto', chain: params.chain, address: params.address, label: params.label },
+      token,
+    })
+  }
+
+  // -----------------------------------------------------------------------
+  // Top-up
+  // -----------------------------------------------------------------------
+
+  /**
+   * Convenience: charge a saved payment method and deposit credits.
+   * amount is in cents.
+   */
+  async topup(params: { userId: string; paymentMethodId: string; amountCents: number; currency?: string }, token?: string): Promise<Transaction> {
+    return this.request<Transaction>('/v1/billing/topup', {
+      method: 'POST',
+      body: params,
+      token,
+    })
+  }
 }
 
 // ---------------------------------------------------------------------------

package/dist/billing.d.ts

@@ -0,0 +1,2 @@
+/** @hanzo/commerce/billing — re-exports from @hanzo/commerce/client */
+export * from './client';

package/dist/billing.js

@@ -0,0 +1,3 @@
+/** @hanzo/commerce/billing — re-exports from @hanzo/commerce/client */
+export * from './client';
+//# sourceMappingURL=billing.js.map

package/dist/billing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"billing.js","sourceRoot":"","sources":["../billing.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,cAAc,UAAU,CAAA"}

package/dist/client.d.ts

@@ -0,0 +1,464 @@
+/**
+ * @hanzo/commerce/client
+ *
+ * Universal TypeScript client for the Hanzo Commerce API.
+ * Works in browser, Node.js, and edge runtimes — no backend required.
+ * Covers billing, subscriptions, payments, checkout, coupons,
+ * referrals, affiliates, usage, and plans.
+ *
+ * @example
+ * ```ts
+ * import { Commerce } from '@hanzo/commerce/client'
+ *
+ * const commerce = new Commerce({ baseUrl: 'https://api.hanzo.ai', token: iamToken })
+ *
+ * // Validate a coupon before checkout
+ * const coupon = await commerce.validateCoupon('LAUNCH50')
+ *
+ * // Create a checkout session
+ * const session = await commerce.createCheckoutSession({
+ *   items: [{ id: 'plan_pro', quantity: 1 }],
+ *   couponCode: 'LAUNCH50',
+ *   referrerId: 'ref_abc123',
+ *   successUrl: 'https://app.example.com/success',
+ *   cancelUrl: 'https://app.example.com/cancel',
+ * })
+ * window.location.href = session.checkoutUrl
+ *
+ * // Tokenize a card (S2S — no external SDK required)
+ * const token = await commerce.tokenizeCard({
+ *   number: '4242424242424242',
+ *   expiryMonth: '12',
+ *   expiryYear: '2027',
+ *   cvc: '123',
+ *   name: 'Jane Smith',
+ * })
+ *
+ * // Subscribe
+ * const sub = await commerce.subscribe({ planId: 'pro', userId: 'user_xyz' })
+ * ```
+ */
+export type CommerceClientConfig = {
+    /**
+     * Commerce API base URL.
+     * Defaults to https://api.hanzo.ai
+     */
+    baseUrl?: string;
+    /** @deprecated use baseUrl */
+    commerceUrl?: string;
+    /** IAM access token for authenticated requests. */
+    token?: string;
+    /** Request timeout in milliseconds. Default 15 000. */
+    timeoutMs?: number;
+};
+export type Balance = {
+    balance: number;
+    holds: number;
+    available: number;
+};
+/**
+ * Tier-aware balance from GET /v1/billing/tier. effectiveAvailable folds the
+ * tenant's included plan allotment (e.g. the free-tier daily credit) into the
+ * prepaid available balance — gate on this to honor included usage first.
+ */
+export type TierResponse = {
+    user: string;
+    tier: {
+        name: string;
+        displayName?: string;
+        maxAgents?: number;
+        unlimitedAgents?: boolean;
+        dailyCreditsCents?: number;
+        allowedModels?: string[];
+    };
+    balance: {
+        currency: string;
+        prepaidAvailable: number;
+        dailyRemaining: number;
+        effectiveAvailable: 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;
+    customerId?: 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;
+    cancelAtPeriodEnd?: boolean;
+    currentPeriodEnd?: string;
+};
+export type Plan = {
+    id?: string;
+    slug?: string;
+    name?: string;
+    description?: string;
+    price?: number;
+    priceMonthly?: number;
+    priceAnnual?: number;
+    currency?: string;
+    interval?: 'monthly' | 'yearly' | string;
+    intervalCount?: number;
+    trialPeriodDays?: number;
+    features?: string[];
+    popular?: boolean;
+    contactSales?: boolean;
+    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;
+};
+export type CouponType = 'Percent' | 'Flat' | 'FreeShipping' | 'FreeItem';
+export type Coupon = {
+    id?: string;
+    code: string;
+    type: CouponType;
+    /** Amount: percentage (0-100) for Percent, cents for Flat */
+    amount: number;
+    description?: string;
+    limit?: number;
+    used?: number;
+    startDate?: string;
+    endDate?: string;
+    enabled?: boolean;
+    /** Calculated discount in cents (returned by validateCoupon) */
+    discountCents?: number;
+};
+export type CouponValidateResult = {
+    valid: boolean;
+    coupon?: Coupon;
+    error?: string;
+    /** Discount in cents for a given subtotal */
+    discountCents?: number;
+};
+export type Discount = {
+    id?: string;
+    type: 'Percent' | 'Flat' | 'FreeShipping' | 'FreeItem' | 'Bulk';
+    amount: number;
+    scope?: 'Product' | 'Variant' | 'Collection' | 'Store';
+    enabled?: boolean;
+    startDate?: string;
+    endDate?: string;
+};
+export type CheckoutItem = {
+    id: string;
+    quantity?: number;
+    /** Price override in cents */
+    price?: number;
+    name?: string;
+    description?: string;
+    imageUrl?: string;
+    metadata?: Record<string, unknown>;
+};
+export type CheckoutSessionRequest = {
+    items: CheckoutItem[];
+    successUrl: string;
+    cancelUrl: string;
+    couponCode?: string;
+    referrerId?: string;
+    affiliateId?: string;
+    currency?: string;
+    customer?: {
+        email?: string;
+        name?: string;
+        address?: string;
+        city?: string;
+        zip?: string;
+    };
+    metadata?: Record<string, unknown>;
+};
+export type CheckoutSessionResponse = {
+    checkoutUrl: string;
+    sessionId: string;
+    /** Original total in cents before discount */
+    originalTotal?: number;
+    /** Final total in cents after discount */
+    finalTotal?: number;
+    discount?: {
+        code: string;
+        type: CouponType;
+        amount: number;
+        discountCents: number;
+    };
+};
+export type CardTokenizeRequest = {
+    number: string;
+    expiryMonth: string;
+    expiryYear: string;
+    cvc: string;
+    name?: string;
+    zip?: string;
+};
+export type CardTokenizeResult = {
+    token: string;
+    brand: string;
+    last4: string;
+    expiryMonth: string;
+    expiryYear: string;
+    provider: string;
+};
+export type PaymentMethodType = 'card' | 'bank_account' | 'balance' | 'crypto' | 'wire';
+export type PaymentMethod = {
+    id: string;
+    type: PaymentMethodType;
+    isDefault?: boolean;
+    customerId?: string;
+    card?: {
+        brand: string;
+        last4: string;
+        expMonth: number;
+        expYear: number;
+    };
+    bank_account?: {
+        bankName?: string;
+        last4?: string;
+        accountType?: 'checking' | 'savings';
+        routingNumber?: string;
+    };
+    crypto?: {
+        chain: string;
+        address: string;
+        label?: string;
+    };
+    providerRef?: string;
+    providerType?: string;
+    createdAt?: string;
+};
+export type Referral = {
+    id?: string;
+    userId?: string;
+    referrerId?: string;
+    affiliateId?: string;
+    orderId?: string;
+    fee?: number;
+    createdAt?: string;
+};
+export type Referrer = {
+    id?: string;
+    userId?: string;
+    enabled?: boolean;
+    code?: string;
+    referrals?: Referral[];
+};
+export type Affiliate = {
+    id?: string;
+    userId?: string;
+    enabled?: boolean;
+    commission?: number;
+    couponId?: string;
+    connectUrl?: string;
+};
+export type CreditGrant = {
+    id?: string;
+    userId?: string;
+    amount: number;
+    currency: string;
+    expiresAt?: string;
+    tags?: string[];
+};
+export declare class Commerce {
+    private readonly baseUrl;
+    private token;
+    private readonly timeoutMs;
+    constructor(config?: CommerceClientConfig);
+    /** Update the auth token (e.g. after IAM token refresh). */
+    setToken(token: string): void;
+    private request;
+    getBalance(user: string, currency?: string, token?: string, headers?: Record<string, string>): Promise<Balance>;
+    getAllBalances(user: string, token?: string): Promise<Record<string, Balance>>;
+    /**
+     * Tier-aware balance: prepaid available plus the tenant's included plan
+     * allotment (effectiveAvailable). Use this for the metering gate when you
+     * want included usage (e.g. free-tier daily credit) honored before prepaid
+     * funds are drawn down.
+     */
+    getTier(user: string, opts?: {
+        token?: string;
+        headers?: Record<string, string>;
+    }): Promise<TierResponse>;
+    addUsageRecord(record: UsageRecord, token?: string, headers?: Record<string, string>): Promise<Transaction>;
+    getUsageRecords(user: string, currency?: string, token?: string): Promise<Transaction[]>;
+    addDeposit(params: {
+        user: string;
+        currency?: string;
+        amount: number;
+        notes?: string;
+        tags?: string[];
+        expiresIn?: string;
+    }, token?: string): Promise<Transaction>;
+    grantStarterCredit(user: string, token?: string): Promise<Transaction>;
+    getPlans(token?: string): Promise<Plan[]>;
+    getPlan(planId: string, token?: string): Promise<Plan | null>;
+    subscribe(params: {
+        planId: string;
+        userId?: string;
+        customerId?: string;
+        paymentMethodId?: string;
+        couponCode?: string;
+        trialDays?: number;
+    }, token?: string): Promise<Subscription>;
+    getSubscription(subscriptionId: string, token?: string): Promise<Subscription | null>;
+    listSubscriptions(params?: {
+        customerId?: string;
+    }, token?: string): Promise<Subscription[]>;
+    updateSubscription(subscriptionId: string, update: Partial<Subscription>, token?: string): Promise<Subscription>;
+    cancelSubscription(subscriptionId: string, immediately?: boolean, token?: string): Promise<Subscription>;
+    reactivateSubscription(subscriptionId: string, token?: string): Promise<Subscription>;
+    /**
+     * Create a hosted checkout session.
+     * Returns a URL to redirect the customer to for payment.
+     * Supports coupons, referral tracking, and multiple currencies.
+     */
+    createCheckoutSession(params: CheckoutSessionRequest, token?: string): Promise<CheckoutSessionResponse>;
+    /**
+     * Tokenize a payment card server-side.
+     * No external SDK (Square.js, Stripe.js, etc.) is needed on the frontend.
+     * The card data is sent to the Hanzo Commerce API over HTTPS, which
+     * tokenizes via the configured payment provider (Stripe).
+     */
+    tokenizeCard(card: CardTokenizeRequest, token?: string): Promise<CardTokenizeResult>;
+    addPaymentMethod(params: {
+        customerId: string;
+        type: PaymentMethodType;
+        token?: string;
+        providerRef?: string;
+        providerType?: string;
+    }, token?: string): Promise<PaymentMethod>;
+    listPaymentMethods(customerId: string, token?: string): Promise<PaymentMethod[]>;
+    removePaymentMethod(paymentMethodId: string, token?: string): Promise<void>;
+    setDefaultPaymentMethod(customerId: string, paymentMethodId: string, token?: string): Promise<PaymentMethod>;
+    /**
+     * Validate a coupon code.
+     * Optionally pass a subtotalCents to get the calculated discount amount.
+     */
+    validateCoupon(code: string, subtotalCents?: number, token?: string): Promise<CouponValidateResult>;
+    /**
+     * Redeem a coupon for a user. Creates credit grant records.
+     */
+    redeemCoupon(code: string, userId: string, token?: string): Promise<CreditGrant[]>;
+    /**
+     * Get or create a referrer record for a user.
+     * Returns the referral code/link the user can share.
+     */
+    getOrCreateReferrer(userId: string, token?: string): Promise<Referrer>;
+    getReferrals(userId: string, token?: string): Promise<Referral[]>;
+    getReferrers(userId: string, token?: string): Promise<Referrer[]>;
+    /**
+     * Get affiliate details for a user.
+     */
+    getAffiliate(userId: string, token?: string): Promise<Affiliate | null>;
+    /**
+     * Create an affiliate account for a user.
+     * After creation, user can connect their bank via the returnedconnectUrl.
+     */
+    createAffiliate(userId: string, token?: string): Promise<Affiliate>;
+    getAffiliateReferrals(affiliateId: string, token?: string): Promise<Referral[]>;
+    getAffiliateOrders(affiliateId: string, token?: string): Promise<unknown[]>;
+    getAffiliateTransactions(affiliateId: string, token?: string): Promise<Transaction[]>;
+    authorize(orderId: string, token?: string): Promise<Payment>;
+    capture(orderId: string, token?: string): Promise<Payment>;
+    charge(orderId: string, token?: string): Promise<Payment>;
+    refund(paymentId: string, token?: string): Promise<Payment>;
+    billingRefund(params: {
+        user: string;
+        amount: number;
+        originalTransactionId: string;
+        currency?: string;
+        notes?: string;
+    }, token?: string): Promise<Transaction>;
+    /**
+     * Get or create a deposit address for a given chain.
+     * Used for crypto top-up — user sends funds to this address.
+     */
+    getWalletAddress(params: {
+        chain: string;
+        userId: string;
+    }, token?: string): Promise<{
+        address: string;
+        chain: string;
+        qrCode?: string;
+    }>;
+    /**
+     * Add a bank account payment method (ACH).
+     * plaidToken from Plaid Link or Square bank OAuth.
+     */
+    addBankAccount(params: {
+        customerId: string;
+        plaidToken?: string;
+        bankName?: string;
+        accountType?: 'checking' | 'savings';
+    }, token?: string): Promise<PaymentMethod>;
+    addCryptoWallet(params: {
+        customerId: string;
+        chain: string;
+        address: string;
+        label?: string;
+    }, token?: string): Promise<PaymentMethod>;
+    /**
+     * Convenience: charge a saved payment method and deposit credits.
+     * amount is in cents.
+     */
+    topup(params: {
+        userId: string;
+        paymentMethodId: string;
+        amountCents: number;
+        currency?: string;
+    }, token?: string): Promise<Transaction>;
+}
+/**
+ * Create a commerce client pre-configured for api.hanzo.ai.
+ * Pass your IAM access token (read from localStorage or cookie).
+ *
+ * @example
+ * ```ts
+ * import { hanzoCommerce } from '@hanzo/commerce/client'
+ * const commerce = hanzoCommerce(localStorage.getItem('hanzo-auth-token') ?? undefined)
+ * const plans = await commerce.getPlans()
+ * ```
+ */
+export declare function hanzoCommerce(token?: string): Commerce;
+export declare class CommerceApiError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}