@hanzo/commerce 7.6.0 → 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,30 +426,42 @@ export class Commerce {
   // Balance
   // -----------------------------------------------------------------------
 
-  async getBalance(user: string, currency = 'usd', token?: string): Promise<Balance> {
-    return this.request<Balance>('/api/v1/billing/balance', {
-      params: { user, currency }, token,
+  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>>('/api/v1/billing/balance/all', {
+    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): Promise<Transaction> {
-    return this.request<Transaction>('/api/v1/billing/usage', {
-      method: 'POST', body: record, token,
+  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[]>('/api/v1/billing/usage', {
+    return this.request<Transaction[]>('/v1/billing/usage', {
       params: { user, currency }, token,
     })
   }
@@ -425,13 +474,13 @@ export class Commerce {
     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', {
+    return this.request<Transaction>('/v1/billing/deposit', {
       method: 'POST', body: params, token,
     })
   }
 
   async grantStarterCredit(user: string, token?: string): Promise<Transaction> {
-    return this.request<Transaction>('/api/v1/billing/credit', {
+    return this.request<Transaction>('/v1/billing/credit', {
       method: 'POST', body: { user }, token,
     })
   }
@@ -441,12 +490,12 @@ export class Commerce {
   // -----------------------------------------------------------------------
 
   async getPlans(token?: string): Promise<Plan[]> {
-    return this.request<Plan[]>('/api/v1/billing/plans', { token })
+    return this.request<Plan[]>('/v1/billing/plans', { token })
   }
 
   async getPlan(planId: string, token?: string): Promise<Plan | null> {
     try {
-      return await this.request<Plan>(`/api/v1/billing/plans/${planId}`, { token })
+      return await this.request<Plan>(`/v1/billing/plans/${planId}`, { token })
     } catch { return null }
   }
 
@@ -458,37 +507,37 @@ export class Commerce {
     params: { planId: string; userId?: string; customerId?: string; paymentMethodId?: string; couponCode?: string; trialDays?: number },
     token?: string,
   ): Promise<Subscription> {
-    return this.request<Subscription>('/api/v1/billing/subscriptions', {
+    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>(`/api/v1/billing/subscriptions/${subscriptionId}`, { token })
+      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[]>('/api/v1/billing/subscriptions', {
+    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>(`/api/v1/billing/subscriptions/${subscriptionId}`, {
+    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>(`/api/v1/billing/subscriptions/${subscriptionId}/cancel`, {
+    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>(`/api/v1/billing/subscriptions/${subscriptionId}/reactivate`, {
+    return this.request<Subscription>(`/v1/billing/subscriptions/${subscriptionId}/reactivate`, {
       method: 'POST', token,
     })
   }
@@ -506,7 +555,7 @@ export class Commerce {
     params: CheckoutSessionRequest,
     token?: string,
   ): Promise<CheckoutSessionResponse> {
-    return this.request<CheckoutSessionResponse>('/api/v1/checkout/sessions', {
+    return this.request<CheckoutSessionResponse>('/v1/checkout/sessions', {
       method: 'POST', body: params, token,
     })
   }
@@ -522,7 +571,7 @@ export class Commerce {
    * tokenizes via the configured payment provider (Stripe).
    */
   async tokenizeCard(card: CardTokenizeRequest, token?: string): Promise<CardTokenizeResult> {
-    return this.request<CardTokenizeResult>('/api/v1/billing/card/tokenize', {
+    return this.request<CardTokenizeResult>('/v1/billing/card/tokenize', {
       method: 'POST',
       body: {
         number: card.number.replace(/\s/g, ''),
@@ -550,25 +599,25 @@ export class Commerce {
     },
     token?: string,
   ): Promise<PaymentMethod> {
-    return this.request<PaymentMethod>('/api/v1/billing/payment-methods', {
+    return this.request<PaymentMethod>('/v1/billing/payment-methods', {
       method: 'POST', body: params, token,
     })
   }
 
   async listPaymentMethods(customerId: string, token?: string): Promise<PaymentMethod[]> {
-    return this.request<PaymentMethod[]>('/api/v1/billing/payment-methods', {
+    return this.request<PaymentMethod[]>('/v1/billing/payment-methods', {
       params: { customerId }, token,
     })
   }
 
   async removePaymentMethod(paymentMethodId: string, token?: string): Promise<void> {
-    await this.request<void>(`/api/v1/billing/payment-methods/${paymentMethodId}`, {
+    await this.request<void>(`/v1/billing/payment-methods/${paymentMethodId}`, {
       method: 'DELETE', token,
     })
   }
 
   async setDefaultPaymentMethod(customerId: string, paymentMethodId: string, token?: string): Promise<PaymentMethod> {
-    return this.request<PaymentMethod>(`/api/v1/billing/customers/${customerId}/default-payment-method`, {
+    return this.request<PaymentMethod>(`/v1/billing/customers/${customerId}/default-payment-method`, {
       method: 'POST', body: { paymentMethodId }, token,
     })
   }
@@ -583,7 +632,7 @@ export class Commerce {
    */
   async validateCoupon(code: string, subtotalCents?: number, token?: string): Promise<CouponValidateResult> {
     try {
-      const result = await this.request<Coupon>('/api/v1/coupon/validate', {
+      const result = await this.request<Coupon>('/v1/coupon/validate', {
         method: 'POST',
         body: { code: code.toUpperCase().trim(), subtotalCents },
         token,
@@ -599,7 +648,7 @@ export class Commerce {
    * Redeem a coupon for a user. Creates credit grant records.
    */
   async redeemCoupon(code: string, userId: string, token?: string): Promise<CreditGrant[]> {
-    return this.request<CreditGrant[]>('/api/v1/coupon/redeem', {
+    return this.request<CreditGrant[]>('/v1/coupon/redeem', {
       method: 'POST',
       body: { code: code.toUpperCase().trim(), userId },
       token,
@@ -615,17 +664,17 @@ export class Commerce {
    * Returns the referral code/link the user can share.
    */
   async getOrCreateReferrer(userId: string, token?: string): Promise<Referrer> {
-    return this.request<Referrer>('/api/v1/referrer', {
+    return this.request<Referrer>('/v1/referrer', {
       method: 'POST', body: { userId }, token,
     })
   }
 
   async getReferrals(userId: string, token?: string): Promise<Referral[]> {
-    return this.request<Referral[]>(`/api/v1/user/${userId}/referrals`, { token })
+    return this.request<Referral[]>(`/v1/user/${userId}/referrals`, { token })
   }
 
   async getReferrers(userId: string, token?: string): Promise<Referrer[]> {
-    return this.request<Referrer[]>(`/api/v1/user/${userId}/referrers`, { token })
+    return this.request<Referrer[]>(`/v1/user/${userId}/referrers`, { token })
   }
 
   /**
@@ -633,7 +682,7 @@ export class Commerce {
    */
   async getAffiliate(userId: string, token?: string): Promise<Affiliate | null> {
     try {
-      return await this.request<Affiliate>(`/api/v1/user/${userId}/affiliate`, { token })
+      return await this.request<Affiliate>(`/v1/user/${userId}/affiliate`, { token })
     } catch { return null }
   }
 
@@ -642,21 +691,21 @@ export class Commerce {
    * After creation, user can connect their bank via the returnedconnectUrl.
    */
   async createAffiliate(userId: string, token?: string): Promise<Affiliate> {
-    return this.request<Affiliate>('/api/v1/affiliate', {
+    return this.request<Affiliate>('/v1/affiliate', {
       method: 'POST', body: { userId }, token,
     })
   }
 
   async getAffiliateReferrals(affiliateId: string, token?: string): Promise<Referral[]> {
-    return this.request<Referral[]>(`/api/v1/affiliate/${affiliateId}/referrals`, { token })
+    return this.request<Referral[]>(`/v1/affiliate/${affiliateId}/referrals`, { token })
   }
 
   async getAffiliateOrders(affiliateId: string, token?: string): Promise<unknown[]> {
-    return this.request<unknown[]>(`/api/v1/affiliate/${affiliateId}/orders`, { token })
+    return this.request<unknown[]>(`/v1/affiliate/${affiliateId}/orders`, { token })
   }
 
   async getAffiliateTransactions(affiliateId: string, token?: string): Promise<Transaction[]> {
-    return this.request<Transaction[]>(`/api/v1/affiliate/${affiliateId}/transactions`, { token })
+    return this.request<Transaction[]>(`/v1/affiliate/${affiliateId}/transactions`, { token })
   }
 
   // -----------------------------------------------------------------------
@@ -664,29 +713,96 @@ export class Commerce {
   // -----------------------------------------------------------------------
 
   async authorize(orderId: string, token?: string): Promise<Payment> {
-    return this.request<Payment>(`/api/v1/authorize/${orderId}`, { method: 'POST', token })
+    return this.request<Payment>(`/v1/authorize/${orderId}`, { method: 'POST', token })
   }
 
   async capture(orderId: string, token?: string): Promise<Payment> {
-    return this.request<Payment>(`/api/v1/capture/${orderId}`, { method: 'POST', token })
+    return this.request<Payment>(`/v1/capture/${orderId}`, { method: 'POST', token })
   }
 
   async charge(orderId: string, token?: string): Promise<Payment> {
-    return this.request<Payment>(`/api/v1/charge/${orderId}`, { method: 'POST', token })
+    return this.request<Payment>(`/v1/charge/${orderId}`, { method: 'POST', token })
   }
 
   async refund(paymentId: string, token?: string): Promise<Payment> {
-    return this.request<Payment>(`/api/v1/refund/${paymentId}`, { method: 'POST', token })
+    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>('/api/v1/billing/refund', {
+    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/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"}