@hanzo/commerce 7.7.1 → 7.7.3

package/client.ts

@@ -1,783 +0,0 @@
-/**
- * @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
- *
- * // Subscribe
- * const sub = await commerce.subscribe({ planId: 'pro', userId: 'user_xyz' })
- * ```
- */
-
-// ---------------------------------------------------------------------------
-// Config
-// ---------------------------------------------------------------------------
-
-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
-}
-
-// ---------------------------------------------------------------------------
-// Core types
-// ---------------------------------------------------------------------------
-
-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
-}
-
-// ---------------------------------------------------------------------------
-// Coupon / Discount types
-// ---------------------------------------------------------------------------
-
-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
-}
-
-// ---------------------------------------------------------------------------
-// Checkout types
-// ---------------------------------------------------------------------------
-
-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
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Payment method types
-// ---------------------------------------------------------------------------
-
-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
-}
-
-// ---------------------------------------------------------------------------
-// Referral / Affiliate types
-// ---------------------------------------------------------------------------
-
-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
-}
-
-// ---------------------------------------------------------------------------
-// Credit grant
-// ---------------------------------------------------------------------------
-
-export type CreditGrant = {
-  id?: string
-  userId?: string
-  amount: number
-  currency: string
-  expiresAt?: string
-  tags?: string[]
-}
-
-// ---------------------------------------------------------------------------
-// Client
-// ---------------------------------------------------------------------------
-
-const DEFAULT_BASE_URL = 'https://api.hanzo.ai'
-const DEFAULT_TIMEOUT_MS = 15_000
-
-export class Commerce {
-  private readonly baseUrl: string
-  private token: string | undefined
-  private readonly timeoutMs: number
-
-  constructor(config: CommerceClientConfig = {}) {
-    this.baseUrl = (config.baseUrl ?? config.commerceUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '')
-    this.token = config.token
-    this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS
-  }
-
-  /** Update the auth token (e.g. after IAM token refresh). */
-  setToken(token: string): void {
-    this.token = token
-  }
-
-  private async request<T>(
-    path: string,
-    opts?: {
-      method?: string
-      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)
-    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(), this.timeoutMs)
-
-    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'
-    if (opts?.headers) Object.assign(headers, opts.headers)
-
-    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
-  // -----------------------------------------------------------------------
-
-  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, headers,
-    })
-  }
-
-  async getAllBalances(user: string, token?: string): Promise<Record<string, Balance>> {
-    return this.request<Record<string, Balance>>('/v1/billing/balance/all', {
-      params: { user }, token,
-    })
-  }
-
-  /**
-   * 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, headers?: Record<string, string>): Promise<Transaction> {
-    return this.request<Transaction>('/v1/billing/usage', {
-      method: 'POST', body: record, token, headers,
-    })
-  }
-
-  async getUsageRecords(user: string, currency = 'usd', token?: string): Promise<Transaction[]> {
-    return this.request<Transaction[]>('/v1/billing/usage', {
-      params: { user, currency }, token,
-    })
-  }
-
-  // -----------------------------------------------------------------------
-  // Deposits / Credits
-  // -----------------------------------------------------------------------
-
-  async addDeposit(
-    params: { user: string; currency?: string; amount: number; notes?: string; tags?: string[]; expiresIn?: string },
-    token?: string,
-  ): Promise<Transaction> {
-    return this.request<Transaction>('/v1/billing/deposit', {
-      method: 'POST', body: params, token,
-    })
-  }
-
-  async grantStarterCredit(user: string, token?: string): Promise<Transaction> {
-    return this.request<Transaction>('/v1/billing/credit', {
-      method: 'POST', body: { user }, token,
-    })
-  }
-
-  // -----------------------------------------------------------------------
-  // Plans
-  // -----------------------------------------------------------------------
-
-  async getPlans(token?: string): Promise<Plan[]> {
-    return this.request<Plan[]>('/v1/billing/plans', { token })
-  }
-
-  async getPlan(planId: string, token?: string): Promise<Plan | null> {
-    try {
-      return await this.request<Plan>(`/v1/billing/plans/${planId}`, { token })
-    } catch { return null }
-  }
-
-  // -----------------------------------------------------------------------
-  // Subscriptions
-  // -----------------------------------------------------------------------
-
-  async subscribe(
-    params: { planId: string; userId?: string; customerId?: string; paymentMethodId?: string; couponCode?: string; trialDays?: number },
-    token?: string,
-  ): Promise<Subscription> {
-    return this.request<Subscription>('/v1/billing/subscriptions', {
-      method: 'POST', body: params, token,
-    })
-  }
-
-  async getSubscription(subscriptionId: string, token?: string): Promise<Subscription | null> {
-    try {
-      return await this.request<Subscription>(`/v1/billing/subscriptions/${subscriptionId}`, { token })
-    } catch { return null }
-  }
-
-  async listSubscriptions(params?: { customerId?: string }, token?: string): Promise<Subscription[]> {
-    return this.request<Subscription[]>('/v1/billing/subscriptions', {
-      params: params as Record<string, string> | undefined, token,
-    })
-  }
-
-  async updateSubscription(subscriptionId: string, update: Partial<Subscription>, token?: string): Promise<Subscription> {
-    return this.request<Subscription>(`/v1/billing/subscriptions/${subscriptionId}`, {
-      method: 'PATCH', body: update, token,
-    })
-  }
-
-  async cancelSubscription(subscriptionId: string, immediately = false, token?: string): Promise<Subscription> {
-    return this.request<Subscription>(`/v1/billing/subscriptions/${subscriptionId}/cancel`, {
-      method: 'POST', body: { immediately }, token,
-    })
-  }
-
-  async reactivateSubscription(subscriptionId: string, token?: string): Promise<Subscription> {
-    return this.request<Subscription>(`/v1/billing/subscriptions/${subscriptionId}/reactivate`, {
-      method: 'POST', token,
-    })
-  }
-
-  // -----------------------------------------------------------------------
-  // Checkout sessions
-  // -----------------------------------------------------------------------
-
-  /**
-   * Create a hosted checkout session.
-   * Returns a URL to redirect the customer to for payment.
-   * Supports coupons, referral tracking, and multiple currencies.
-   */
-  async createCheckoutSession(
-    params: CheckoutSessionRequest,
-    token?: string,
-  ): Promise<CheckoutSessionResponse> {
-    return this.request<CheckoutSessionResponse>('/v1/checkout/sessions', {
-      method: 'POST', body: params, token,
-    })
-  }
-
-  // -----------------------------------------------------------------------
-  // Payment methods
-  // -----------------------------------------------------------------------
-
-  async addPaymentMethod(
-    params: {
-      customerId: string
-      type: PaymentMethodType
-      token?: string          // provider nonce (Square Web Payments SDK)
-      providerRef?: string
-      providerType?: string
-    },
-    token?: string,
-  ): Promise<PaymentMethod> {
-    return this.request<PaymentMethod>('/v1/billing/methods', {
-      method: 'POST', body: params, token,
-    })
-  }
-
-  async listPaymentMethods(customerId: string, token?: string): Promise<PaymentMethod[]> {
-    return this.request<PaymentMethod[]>('/v1/billing/methods', {
-      params: { customerId }, token,
-    })
-  }
-
-  async removePaymentMethod(paymentMethodId: string, token?: string): Promise<void> {
-    await this.request<void>(`/v1/billing/methods/${paymentMethodId}`, {
-      method: 'DELETE', token,
-    })
-  }
-
-  async setDefaultPaymentMethod(customerId: string, paymentMethodId: string, token?: string): Promise<PaymentMethod> {
-    return this.request<PaymentMethod>(`/v1/billing/customers/${customerId}/default-payment-method`, {
-      method: 'POST', body: { paymentMethodId }, token,
-    })
-  }
-
-  // -----------------------------------------------------------------------
-  // Coupons / Promo codes
-  // -----------------------------------------------------------------------
-
-  /**
-   * Validate a coupon code.
-   * Optionally pass a subtotalCents to get the calculated discount amount.
-   */
-  async validateCoupon(code: string, subtotalCents?: number, token?: string): Promise<CouponValidateResult> {
-    try {
-      const result = await this.request<Coupon>('/v1/coupon/validate', {
-        method: 'POST',
-        body: { code: code.toUpperCase().trim(), subtotalCents },
-        token,
-      })
-      return { valid: true, coupon: result }
-    } catch (err) {
-      const msg = err instanceof CommerceApiError ? err.message : 'Invalid coupon'
-      return { valid: false, error: msg }
-    }
-  }
-
-  /**
-   * Redeem a coupon for a user. Creates credit grant records.
-   */
-  async redeemCoupon(code: string, userId: string, token?: string): Promise<CreditGrant[]> {
-    return this.request<CreditGrant[]>('/v1/coupon/redeem', {
-      method: 'POST',
-      body: { code: code.toUpperCase().trim(), userId },
-      token,
-    })
-  }
-
-  // -----------------------------------------------------------------------
-  // Referrals & Affiliates
-  // -----------------------------------------------------------------------
-
-  /**
-   * Get or create a referrer record for a user.
-   * Returns the referral code/link the user can share.
-   */
-  async getOrCreateReferrer(userId: string, token?: string): Promise<Referrer> {
-    return this.request<Referrer>('/v1/referrer', {
-      method: 'POST', body: { userId }, token,
-    })
-  }
-
-  async getReferrals(userId: string, token?: string): Promise<Referral[]> {
-    return this.request<Referral[]>(`/v1/user/${userId}/referrals`, { token })
-  }
-
-  async getReferrers(userId: string, token?: string): Promise<Referrer[]> {
-    return this.request<Referrer[]>(`/v1/user/${userId}/referrers`, { token })
-  }
-
-  /**
-   * Get affiliate details for a user.
-   */
-  async getAffiliate(userId: string, token?: string): Promise<Affiliate | null> {
-    try {
-      return await this.request<Affiliate>(`/v1/user/${userId}/affiliate`, { token })
-    } catch { return null }
-  }
-
-  /**
-   * Create an affiliate account for a user.
-   * After creation, user can connect their bank via the returnedconnectUrl.
-   */
-  async createAffiliate(userId: string, token?: string): Promise<Affiliate> {
-    return this.request<Affiliate>('/v1/affiliate', {
-      method: 'POST', body: { userId }, token,
-    })
-  }
-
-  async getAffiliateReferrals(affiliateId: string, token?: string): Promise<Referral[]> {
-    return this.request<Referral[]>(`/v1/affiliate/${affiliateId}/referrals`, { token })
-  }
-
-  async getAffiliateOrders(affiliateId: string, token?: string): Promise<unknown[]> {
-    return this.request<unknown[]>(`/v1/affiliate/${affiliateId}/orders`, { token })
-  }
-
-  async getAffiliateTransactions(affiliateId: string, token?: string): Promise<Transaction[]> {
-    return this.request<Transaction[]>(`/v1/affiliate/${affiliateId}/transactions`, { token })
-  }
-
-  // -----------------------------------------------------------------------
-  // Legacy checkout (order-based)
-  // -----------------------------------------------------------------------
-
-  async authorize(orderId: string, token?: string): Promise<Payment> {
-    return this.request<Payment>(`/v1/authorize/${orderId}`, { method: 'POST', token })
-  }
-
-  async capture(orderId: string, token?: string): Promise<Payment> {
-    return this.request<Payment>(`/v1/capture/${orderId}`, { method: 'POST', token })
-  }
-
-  async charge(orderId: string, token?: string): Promise<Payment> {
-    return this.request<Payment>(`/v1/charge/${orderId}`, { method: 'POST', token })
-  }
-
-  async refund(paymentId: string, token?: string): Promise<Payment> {
-    return this.request<Payment>(`/v1/refund/${paymentId}`, { method: 'POST', token })
-  }
-
-  async billingRefund(
-    params: { user: string; amount: number; originalTransactionId: string; currency?: string; notes?: string },
-    token?: string,
-  ): Promise<Transaction> {
-    return this.request<Transaction>('/v1/billing/refund', {
-      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/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/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,
-    })
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Standalone factory helpers — import these for quick setup
-// ---------------------------------------------------------------------------
-
-/**
- * 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 function hanzoCommerce(token?: string): Commerce {
-  return new Commerce({ token })
-}
-
-// ---------------------------------------------------------------------------
-// Error
-// ---------------------------------------------------------------------------
-
-export class CommerceApiError extends Error {
-  readonly status: number
-
-  constructor(status: number, message: string) {
-    super(message)
-    this.name = 'CommerceApiError'
-    this.status = status
-  }
-}