mirror of
https://github.com/hanzoai/ui.git
synced 2026-11-20 22:36:27 +00:00
@hanzo/commerce defaults its base URL to api.hanzo.ai, and every saved-card call it makes has been answering 404 there: the billing surface dropped compound words from its route names, both server repos converged, and this client did not. Verified on the live edge — /v1/billing/payment-methods 404s, /v1/billing/methods answers 401, which is what an address that exists says to a request carrying no token. This is a published package, so the dead name was not one product's bug: every consumer that installed it inherited a client that cannot save or list a card. Co-authored-by: Hanzo Dev <[email protected]>
784 lines
24 KiB
TypeScript
784 lines
24 KiB
TypeScript
/**
|
|
* @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
|
|
}
|
|
}
|