@hanzo/commerce 7.6.0 → 7.6.3

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);
+}