@gpt-platform/client 0.10.4 → 0.11.0

package/dist/namespaces/billing.d.ts

@@ -0,0 +1,854 @@
+import type { CreditPackage, FeatureDefinition, FeatureUsage, Invoice, PaymentMethod, Plan, PlanFeatureAllocation, SeatInfo, Transaction, Wallet, FeatureSummary } from "../_internal/types.gen";
+import type { RequestOptions } from "../base-client";
+import { RequestBuilder } from "../request-builder";
+/**
+ * A saved payment method as returned in wallet.payment_methods sideload.
+ * Use `billing.paymentMethods.list()` for full CRUD access.
+ */
+export interface WalletPaymentMethod {
+    id: string;
+    type: "card" | "bank_account";
+    last4?: string;
+    brand?: string;
+    exp_month?: number;
+    exp_year?: number;
+    nickname?: string;
+    is_default: boolean;
+    created_at: string;
+}
+/**
+ * A single day's credit usage entry, as returned in wallet.usage_history.
+ */
+export interface UsageHistoryEntry {
+    date: string;
+    credits_used: number;
+    operation_type: string;
+}
+/**
+ * A credit account within a wallet (subscription, purchased, promotional buckets).
+ */
+export interface BillingAccount {
+    id: string;
+    kind: string;
+    balance_credits: number;
+}
+/** Mutable fields on a saved payment method. */
+export type PaymentMethodUpdateAttributes = {
+    /** Human-readable label for this card (e.g. "Business Visa"). */
+    nickname?: string;
+    /** When true, marks this card as the default for automatic charges. */
+    is_default?: boolean;
+};
+/** Attributes for saving a pre-tokenized payment method. */
+export type PaymentMethodCreateAttributes = {
+    /** Provider token from a hosted fields flow (e.g. a payment provider's hosted iframe). Never pass raw card numbers here. */
+    provider_token: string;
+    type?: "card" | "bank_account";
+    last4?: string;
+    exp_month?: number;
+    exp_year?: number;
+    brand?: string;
+    nickname?: string;
+};
+/**
+ * Attributes for S2S card tokenization (raw card details). The platform tokenizes
+ * these server-side using the configured payment provider.
+ *
+ * @remarks **PCI-DSS: All fields in this type are PCI-sensitive.**
+ * Never log, serialize, or persist any field from this type. The platform
+ * transmits these fields to the payment gateway over TLS and does not store them.
+ */
+export type PaymentMethodTokenizeAttributes = {
+    /**
+     * 13–19 digit Primary Account Number (PAN).
+     * @remarks **PCI-sensitive — do not log or store.**
+     */
+    card_number: string;
+    exp_month: number;
+    exp_year: number;
+    /**
+     * 3–4 digit Card Verification Value.
+     * @remarks **PCI-sensitive — do not log or store.** PCI-DSS prohibits storing CVC post-authorization.
+     */
+    cvc: string;
+    holder_name: string;
+    billing_address: string;
+    billing_city: string;
+    billing_state: string;
+    zip_code: string;
+    phone?: string;
+    nickname?: string;
+    customer_id?: string;
+};
+/** Attributes for updating a feature definition. */
+export type UpdateFeatureDefinitionAttributes = {
+    name?: string;
+    metering_mode?: "unlimited" | "counted" | "credit_cost";
+    default_limit?: number;
+    credit_cost?: number;
+    platform_capability?: string;
+    metadata?: Record<string, unknown>;
+};
+/** Attributes for purchasing an addon plan. */
+export type BuyAddonAttributes = {
+    addon_slug: string;
+    payment_method_id?: string;
+};
+/**
+ * Creates the billing namespace, providing access to wallet balances, subscription
+ * plans, transaction history, credit packages, and payment methods for the
+ * authenticated workspace.
+ *
+ * Accessed via `client.billing.*`.
+ *
+ * @param rb - The internal `RequestBuilder` instance used to execute API calls.
+ * @returns An object containing sub-namespaces: `wallet`, `plans`, `transactions`,
+ *   `creditPackages`, and `paymentMethods`.
+ */
+export declare function createBillingNamespace(rb: RequestBuilder): {
+    /**
+     * Sub-namespace for workspace wallet operations.
+     *
+     * The wallet holds the workspace's available credit balance. Credits are
+     * consumed by AI operations (LLM calls, embeddings, agent executions) and
+     * replenished via subscription plans or purchased credit packages. Use
+     * `wallet.get()` to check the current balance before submitting expensive
+     * operations.
+     */
+    wallet: {
+        /**
+         * Retrieves the current workspace wallet, including the available credit
+         * balance, usage totals, and any pending charges.
+         */
+        get: (options?: RequestOptions) => Promise<Wallet>;
+        /**
+         * Preview the cost and effective date of a plan change before committing.
+         *
+         * @param planSlug - The slug of the target plan (e.g. `"pro-monthly"`).
+         * @returns A projected `Wallet` representing the hypothetical post-change
+         *   state — **not** the caller's current wallet. Do not cache or use this
+         *   as live balance data. Call `wallet.get()` for authoritative state.
+         */
+        previewPlanChange: (planSlug: string, options?: RequestOptions) => Promise<Wallet>;
+        /**
+         * Change the workspace's subscription plan.
+         *
+         * Two call signatures:
+         * - `changePlan(planSlug)` — fetches the wallet automatically (recommended)
+         * - `changePlan(walletId, planSlug)` — use when you already have the wallet ID
+         *
+         * Upgrades charge a prorated amount immediately against the default payment
+         * method. Downgrades are deferred to the end of the current billing period.
+         * Use `previewPlanChange` first to show the user a cost estimate.
+         *
+         * @example
+         * ```typescript
+         * // Simple form — no wallet ID needed
+         * await client.billing.wallet.changePlan("pro-monthly");
+         *
+         * // Explicit form — when walletId is already known
+         * await client.billing.wallet.changePlan(wallet.id, "pro-monthly");
+         * ```
+         */
+        changePlan: (walletIdOrSlug: string, planSlugOrOptions?: string | RequestOptions, options?: RequestOptions) => Promise<Wallet>;
+        /**
+         * Purchase a credit package to top up the workspace wallet immediately.
+         *
+         * Charges the specified (or default) payment method. Credits are added to
+         * the `purchased` bucket and never expire.
+         *
+         * @param walletId - The wallet UUID from `wallet.get()`.
+         * @param packageSlug - The slug of the credit package to purchase.
+         * @param paymentMethodId - Optional payment method UUID. Uses the default if omitted.
+         */
+        buyCredits: (walletId: string, packageSlug: string, paymentMethodId?: string, options?: RequestOptions) => Promise<Wallet>;
+        /**
+         * Update the workspace's auto top-up settings.
+         *
+         * When enabled, the platform automatically purchases the specified credit
+         * package whenever the balance drops below `threshold`.
+         *
+         * @param walletId - The wallet UUID from `wallet.get()`.
+         * @param opts.enabled - Enable or disable auto top-up.
+         * @param opts.threshold - Credit balance floor that triggers a purchase.
+         * @param opts.amount - Credits to purchase per top-up event.
+         * @param opts.packageId - Credit package UUID to auto-purchase.
+         */
+        updateAutoTopUp: (walletId: string, opts: {
+            enabled: boolean;
+            threshold?: number;
+            amount?: number;
+            packageId?: string;
+        }, options?: RequestOptions) => Promise<Wallet>;
+        /**
+         * Sub-namespace for invoice operations.
+         *
+         * Invoices are generated per billing period and carry a `pdf_url` for
+         * receipt download. Use `invoices.list()` for the transaction history page.
+         */
+        invoices: {
+            /**
+             * Returns a single page of invoices for the current workspace.
+             *
+             * Each invoice includes `pdf_url` for receipt download.
+             *
+             * @example
+             * ```typescript
+             * const invoices = await client.billing.wallet.invoices.list();
+             * const paidInvoices = invoices.filter(inv => inv.attributes?.status === "paid");
+             * ```
+             */
+            list: (options?: {
+                page?: number;
+                pageSize?: number;
+            } & RequestOptions) => Promise<Invoice[]>;
+            /**
+             * Fetches all invoices by automatically paginating through every page.
+             *
+             * @example
+             * ```typescript
+             * const all = await client.billing.wallet.invoices.listAll();
+             * const downloadUrl = all[0].attributes?.pdf_url;
+             * ```
+             */
+            listAll: (options?: RequestOptions) => Promise<Invoice[]>;
+        };
+        /**
+         * Purchase an addon plan for the workspace.
+         *
+         * Addon plans provide additional capabilities or quota on top of the base
+         * subscription plan. Charges the specified (or default) payment method immediately.
+         *
+         * @param addonSlug - The slug of the addon plan to purchase (e.g. `"extra-seats-10"`).
+         * @param paymentMethodId - Optional payment method UUID. Uses the default if omitted.
+         */
+        buyAddon: (addonSlug: string, paymentMethodId?: string, options?: RequestOptions) => Promise<Wallet>;
+        /**
+         * Cancel an active addon plan on the workspace.
+         *
+         * Cancellation takes effect at the end of the current billing period.
+         * The addon remains active until then.
+         *
+         * @param addonSlug - The slug of the addon plan to cancel.
+         */
+        cancelAddon: (addonSlug: string, options?: RequestOptions) => Promise<Wallet>;
+        /**
+         * Cancel the current subscription plan.
+         *
+         * @param immediate - If true (default), cancel immediately. If false, cancel at end of billing period.
+         * @param options - Request options
+         * @returns Updated wallet with new subscription_status
+         *
+         * @example
+         * ```typescript
+         * // Cancel immediately
+         * const wallet = await client.billing.wallet.cancelPlan();
+         *
+         * // Cancel at end of period
+         * const wallet = await client.billing.wallet.cancelPlan(false);
+         * ```
+         */
+        cancelPlan: (immediateOrOptions?: boolean | RequestOptions, options?: RequestOptions) => Promise<Wallet>;
+        /**
+         * Retry a failed subscription payment.
+         *
+         * Only works when the subscription is in `past_due` status. Uses the
+         * default payment method on file. On success, restores the subscription
+         * to `active` status and clears the dunning state.
+         *
+         * @param options - Request options
+         * @returns Updated wallet with restored subscription status
+         *
+         * @example
+         * ```typescript
+         * const wallet = await client.billing.wallet.retryPayment();
+         * console.log(wallet.attributes?.subscription_status); // "active"
+         * ```
+         */
+        retryPayment: (options?: RequestOptions) => Promise<Wallet>;
+    };
+    /**
+     * Sub-namespace for seat billing info.
+     *
+     * Provides read access to seat-based billing information for tenants using
+     * seat billing mode. Returns seat counts, limits, and overage details.
+     */
+    seats: {
+        /**
+         * Get seat billing info for the current tenant.
+         *
+         * Returns seat usage, limits, and availability for tenants on seat-based
+         * billing plans.
+         *
+         * @example
+         * ```typescript
+         * const seatInfo = await client.billing.seats.get();
+         * console.log(`Using ${seatInfo.attributes?.seats_used} of ${seatInfo.attributes?.seats_limit} seats`);
+         * ```
+         */
+        get: (options?: RequestOptions) => Promise<SeatInfo>;
+    };
+    /**
+     * Sub-namespace for subscription plan operations.
+     *
+     * Plans represent the recurring subscription tiers available to tenants.
+     * Each plan defines its included credit allowance, feature entitlements,
+     * and pricing. Use `plans.list()` or `plans.listAll()` to display plan
+     * options to end users during onboarding or upgrade flows.
+     */
+    plans: {
+        /**
+         * Returns a single page of available subscription plans.
+         *
+         * @param options - Optional pagination and request options.
+         * @param options.page - The 1-based page number to retrieve (default: 1).
+         * @param options.pageSize - The number of plans to return per page.
+         * @returns A promise resolving to an array of `Plan` objects for the
+         *   requested page.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const plans = await client.billing.plans.list({ page: 1, pageSize: 10 });
+         * plans.forEach(plan => console.log(plan.name, plan.price));
+         * ```
+         */
+        list: (options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<Plan[]>;
+        /**
+         * Fetches all available subscription plans by automatically iterating
+         * through every page until no more results remain.
+         *
+         * Use this method when you need the complete plan catalogue without
+         * manually managing pagination cursors.
+         *
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to a flat array of all `Plan` objects
+         *   across all pages.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const allPlans = await client.billing.plans.listAll();
+         * console.log(`Total plans available: ${allPlans.length}`);
+         * ```
+         */
+        listAll: (options?: RequestOptions) => Promise<Plan[]>;
+        /**
+         * Retrieves a single subscription plan by its unique identifier.
+         *
+         * @param id - The UUID of the plan to retrieve.
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to the matching `Plan` object.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const plan = await client.billing.plans.get('plan_01HXYZ...');
+         * console.log(`Plan: ${plan.name}, Credits: ${plan.credits_per_month}`);
+         * ```
+         */
+        get: (id: string, options?: RequestOptions) => Promise<Plan>;
+    };
+    /**
+     * Sub-namespace for credit transaction history operations.
+     *
+     * Each transaction records a credit debit or credit event on the workspace
+     * wallet — for example, an LLM inference charge, a credit package purchase,
+     * or a subscription renewal. Transactions are immutable audit records.
+     * Use `transactions.list()` for paginated history or `transactions.listAll()`
+     * to export the complete ledger.
+     */
+    transactions: {
+        /**
+         * Returns a single page of credit transactions for the current workspace,
+         * ordered by most recent first.
+         *
+         * @param options - Optional pagination and request options.
+         * @param options.page - The 1-based page number to retrieve (default: 1).
+         * @param options.pageSize - The number of transactions to return per page.
+         * @returns A promise resolving to an array of `Transaction` objects for the
+         *   requested page.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const transactions = await client.billing.transactions.list({ pageSize: 25 });
+         * transactions.forEach(tx => console.log(tx.description, tx.amount));
+         * ```
+         */
+        list: (options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<Transaction[]>;
+        /**
+         * Fetches the complete transaction history for the current workspace by
+         * automatically paginating through all result pages.
+         *
+         * Use this method when you need to export the full ledger or compute
+         * aggregate usage totals without manual pagination.
+         *
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to a flat array of all `Transaction` objects
+         *   across every page.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const allTransactions = await client.billing.transactions.listAll();
+         * const totalSpent = allTransactions.reduce((sum, tx) => sum + tx.amount, 0);
+         * console.log(`Total credits consumed: ${totalSpent}`);
+         * ```
+         */
+        listAll: (options?: RequestOptions) => Promise<Transaction[]>;
+        /**
+         * Retrieves a single transaction record by its unique identifier.
+         *
+         * @param id - The UUID of the transaction to retrieve.
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to the matching `Transaction` object.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const tx = await client.billing.transactions.get('txn_01HXYZ...');
+         * console.log(`Transaction: ${tx.description}, Amount: ${tx.amount}`);
+         * ```
+         */
+        get: (id: string, options?: RequestOptions) => Promise<Transaction>;
+    };
+    /**
+     * Sub-namespace for credit package operations.
+     *
+     * Credit packages are one-time purchasable bundles of credits that top up
+     * the workspace wallet outside of the subscription cycle. They are consumed
+     * after subscription credits are exhausted (waterfall charging order:
+     * subscription credits → prepaid credits → failure). Use this namespace to
+     * display available packages or look up a specific package before initiating
+     * a purchase.
+     */
+    creditPackages: {
+        /**
+         * Returns a single page of purchasable credit packages.
+         *
+         * @param options - Optional pagination and request options.
+         * @param options.page - The 1-based page number to retrieve (default: 1).
+         * @param options.pageSize - The number of packages to return per page.
+         * @returns A promise resolving to an array of `CreditPackage` objects for
+         *   the requested page.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const packages = await client.billing.creditPackages.list({ pageSize: 10 });
+         * packages.forEach(pkg => console.log(pkg.name, pkg.credits, pkg.price));
+         * ```
+         */
+        list: (options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<CreditPackage[]>;
+        /**
+         * Fetches all available credit packages by automatically paginating through
+         * every result page.
+         *
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to a flat array of all `CreditPackage`
+         *   objects.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const allPackages = await client.billing.creditPackages.listAll();
+         * const cheapest = allPackages.sort((a, b) => a.price - b.price)[0];
+         * console.log(`Most affordable package: ${cheapest.name}`);
+         * ```
+         */
+        listAll: (options?: RequestOptions) => Promise<CreditPackage[]>;
+        /**
+         * Retrieves a single credit package by its unique identifier.
+         *
+         * @param id - The UUID of the credit package to retrieve.
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to the matching `CreditPackage` object.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const pkg = await client.billing.creditPackages.get('pkg_01HXYZ...');
+         * console.log(`Package: ${pkg.name}, Credits: ${pkg.credits}`);
+         * ```
+         */
+        get: (id: string, options?: RequestOptions) => Promise<CreditPackage>;
+    };
+    /**
+     * Sub-namespace for payment method operations.
+     *
+     * Payment methods represent the saved cards or bank accounts attached to
+     * a workspace for subscription renewals and credit package purchases. One
+     * method is designated as the default and will be charged automatically.
+     * Use `paymentMethods.setDefault()` to change which card is charged on
+     * the next billing cycle.
+     */
+    paymentMethods: {
+        /**
+         * Permanently removes a payment method from the workspace.
+         *
+         * If the deleted method is currently the default, you must call
+         * `setDefault()` on another method before the next billing cycle or
+         * charges will fail.
+         *
+         * @param id - The UUID of the payment method to delete.
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to `true` when the deletion succeeds.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * await client.billing.paymentMethods.delete('pm_01HXYZ...');
+         * console.log('Payment method removed.');
+         * ```
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<true>;
+        /**
+         * Returns a single page of payment methods attached to the current
+         * workspace.
+         *
+         * @param options - Optional pagination and request options.
+         * @param options.page - The 1-based page number to retrieve (default: 1).
+         * @param options.pageSize - The number of payment methods to return per
+         *   page.
+         * @returns A promise resolving to an array of `PaymentMethod` objects for
+         *   the requested page.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const methods = await client.billing.paymentMethods.list();
+         * methods.forEach(pm => console.log(pm.last4, pm.is_default));
+         * ```
+         */
+        list: (options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<PaymentMethod[]>;
+        /**
+         * Fetches all payment methods attached to the current workspace by
+         * automatically paginating through every result page.
+         *
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to a flat array of all `PaymentMethod`
+         *   objects.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const allMethods = await client.billing.paymentMethods.listAll();
+         * const defaultMethod = allMethods.find(pm => pm.is_default);
+         * ```
+         */
+        listAll: (options?: RequestOptions) => Promise<PaymentMethod[]>;
+        /**
+         * Adds a new payment method to the workspace.
+         *
+         * The `attributes` object should include tokenized card details as returned
+         * by the platform's client-side payment tokenization flow (e.g., a Stripe
+         * payment method token). Never pass raw card numbers through this method.
+         *
+         * @param attributes - A record of payment method attributes, typically
+         *   containing a tokenized payment reference and optional billing address.
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to the newly created `PaymentMethod` object.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const method = await client.billing.paymentMethods.create({
+         *   provider_token: 'tok_visa_4242',
+         *   type: 'card',
+         *   last4: '4242',
+         *   exp_month: 12,
+         *   exp_year: 2027,
+         *   brand: 'Visa',
+         * });
+         * console.log(`Added card ending in ${method.last4}`);
+         * ```
+         */
+        create: (attributes: PaymentMethodCreateAttributes, options?: RequestOptions) => Promise<PaymentMethod>;
+        /**
+         * Tokenizes a raw card server-side and saves the resulting payment method.
+         *
+         * @remarks **SERVER-SIDE ONLY — PCI-DSS.**
+         * This method transmits raw card numbers (`card_number`, `cvc`) over the
+         * network. It **must only be called from a trusted server context** (Node.js,
+         * server-side rendering). Calling this method from browser/client-side code
+         * (React, Vue, browser fetch) is a **PCI-DSS violation** — raw card numbers
+         * must never pass through browser memory or JavaScript bundles.
+         *
+         * For browser flows, use the payment provider's hosted fields iframe to tokenize
+         * on the client side, then call `paymentMethods.create({ provider_token })` instead.
+         *
+         * The platform forwards `cardDetails` to the payment gateway over TLS and stores
+         * only the resulting token — raw card data is never persisted.
+         *
+         * @param cardDetails - Raw PCI-sensitive card fields. All fields must be treated
+         *   as sensitive: do not log, serialize, or pass through error reporters.
+         */
+        tokenize: (cardDetails: PaymentMethodTokenizeAttributes, options?: RequestOptions) => Promise<PaymentMethod>;
+        /**
+         * Updates the mutable attributes of an existing payment method.
+         *
+         * @param id - The UUID of the payment method to update.
+         * @param attributes - Fields to update. Only provided keys are changed.
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to the updated `PaymentMethod` object.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const updated = await client.billing.paymentMethods.update(
+         *   'pm_01HXYZ...',
+         *   { nickname: 'Business Visa', is_default: true },
+         * );
+         * console.log(`Updated: ${updated.nickname}`);
+         * ```
+         */
+        update: (id: string, attributes: PaymentMethodUpdateAttributes, options?: RequestOptions) => Promise<PaymentMethod>;
+        /**
+         * Retrieves a single payment method by its unique identifier.
+         *
+         * @param id - The UUID of the payment method to retrieve.
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to the matching `PaymentMethod` object.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const method = await client.billing.paymentMethods.get('pm_01HXYZ...');
+         * console.log(`Card ending in: ${method.last4}, Default: ${method.is_default}`);
+         * ```
+         */
+        get: (id: string, options?: RequestOptions) => Promise<PaymentMethod>;
+        /**
+         * Permanently marks the specified payment method as the default for the
+         * current workspace.
+         *
+         * The default payment method is charged automatically for subscription
+         * renewals and any credit package purchases initiated without an explicit
+         * payment method ID. Only one method can be the default at a time; calling
+         * this method clears the default flag from all other methods in the
+         * workspace.
+         *
+         * @param id - The UUID of the payment method to set as default.
+         * @param options - Optional request options such as custom headers or an
+         *   abort signal.
+         * @returns A promise resolving to the updated `PaymentMethod` object with
+         *   `is_default` set to `true`.
+         *
+         * @example
+         * ```typescript
+         * const client = new GptClient({ apiKey: 'sk_app_...' });
+         *
+         * const method = await client.billing.paymentMethods.setDefault('pm_01HXYZ...');
+         * console.log(`Default card is now: **** ${method.last4}`);
+         * ```
+         */
+        setDefault: (id: string, options?: RequestOptions) => Promise<PaymentMethod>;
+    };
+    /**
+     * Feature definitions — ISV-defined features with metering modes.
+     *
+     * Feature definitions describe application-specific capabilities (e.g. "meal_plans",
+     * "report_generation") and how they are metered (unlimited, counted, or credit-cost).
+     */
+    featureDefinitions: {
+        /** List all feature definitions for the application. */
+        list: (options?: RequestOptions) => Promise<FeatureDefinition[]>;
+        /** Get a feature definition by ID. */
+        get: (id: string, options?: RequestOptions) => Promise<FeatureDefinition>;
+        /** List feature definitions for a specific application. */
+        listByApplication: (applicationId: string, options?: RequestOptions) => Promise<FeatureDefinition[]>;
+        /** Create a new feature definition. */
+        create: (attrs: {
+            key: string;
+            name: string;
+            metering_mode: "unlimited" | "counted" | "credit_cost";
+            default_limit?: number;
+            credit_cost?: number;
+            platform_capability?: string;
+            metadata?: Record<string, unknown>;
+        }, options?: RequestOptions) => Promise<FeatureDefinition>;
+        /** Update a feature definition. */
+        update: (id: string, attrs: UpdateFeatureDefinitionAttributes, options?: RequestOptions) => Promise<FeatureDefinition>;
+        /** Delete a feature definition. */
+        delete: (id: string, options?: RequestOptions) => Promise<void>;
+    };
+    /**
+     * Feature usage records — per-tenant usage tracking for metered features.
+     *
+     * Access usage records that track how many times each tenant
+     * has used a feature in the current billing cycle, and increment usage.
+     */
+    featureUsages: {
+        /** List all feature usage records. */
+        list: (options?: RequestOptions) => Promise<FeatureUsage[]>;
+        /** Get a feature usage record by ID. */
+        get: (id: string, options?: RequestOptions) => Promise<FeatureUsage>;
+        /** List usage records for a specific tenant. */
+        listByTenant: (tenantId: string, options?: RequestOptions) => Promise<FeatureUsage[]>;
+        /**
+         * Increment usage for a feature by key.
+         *
+         * Checks feature gate, enforces limits, charges credits for credit_cost
+         * features, and atomically increments the usage counter. Returns the
+         * updated usage count and remaining allowance.
+         *
+         * @param featureKey - The feature definition key (e.g., "meal_plans", "clients")
+         * @returns Object with `used` (current cycle count) and `remaining` (null if unlimited)
+         *
+         * @example
+         * ```typescript
+         * const result = await client.billing.featureUsages.increment("meal_plans");
+         * console.log(`Used: ${result.used}, Remaining: ${result.remaining}`);
+         * ```
+         */
+        increment: (featureKey: string, options?: RequestOptions) => Promise<{
+            used: number;
+            remaining: number | null;
+        }>;
+    };
+    /**
+     * Plan-feature allocations — per-plan overrides for feature definitions (read-only).
+     *
+     * Allocations link feature definitions to plans, specifying which features are
+     * enabled on each plan and any per-plan overrides for limits, credit costs,
+     * and activation costs. Use `listByPlan` to build plan comparison tables.
+     */
+    planFeatureAllocations: {
+        /** List all plan-feature allocations for the current application. */
+        list: (options?: {
+            page?: number;
+            pageSize?: number;
+        } & RequestOptions) => Promise<PlanFeatureAllocation[]>;
+        /** Fetch all plan-feature allocations by paginating through every page. */
+        listAll: (options?: RequestOptions) => Promise<PlanFeatureAllocation[]>;
+        /** Get a plan-feature allocation by ID. */
+        get: (id: string, options?: RequestOptions) => Promise<PlanFeatureAllocation>;
+        /**
+         * List allocations for a specific plan.
+         *
+         * Use this to build a plan comparison table — returns all feature
+         * allocations (enabled/disabled, limits, costs) for one plan.
+         *
+         * @param planId - UUID of the plan to query.
+         *
+         * @example
+         * ```typescript
+         * const allocations = await client.billing.planFeatureAllocations.listByPlan(planId);
+         * const enabledFeatures = allocations.filter(a => a.attributes?.enabled);
+         * ```
+         */
+        listByPlan: (planId: string, options?: RequestOptions) => Promise<PlanFeatureAllocation[]>;
+    };
+    /**
+     * Composite feature summary — definitions, allocations, and usage in one call.
+     *
+     * Eliminates the need to call featureDefinitions, planFeatureAllocations,
+     * and featureUsages separately. Returns everything the frontend needs for
+     * feature gating UI.
+     */
+    featureSummary: {
+        /**
+         * Get all features with plan allocations and current usage for the tenant.
+         *
+         * Each item includes: key, name, enabled, metering_mode, limit,
+         * used_this_cycle, remaining, credit_cost, activation_cost, activated.
+         *
+         * @param options - Request options
+         * @returns Array of feature summaries with usage data
+         *
+         * @example
+         * ```typescript
+         * const features = await client.billing.featureSummary.list();
+         * features.forEach(f => {
+         *   console.log(`${f.attributes?.key}: ${f.attributes?.used_this_cycle}/${f.attributes?.limit}`);
+         * });
+         * ```
+         */
+        list: (options?: RequestOptions) => Promise<FeatureSummary[]>;
+    };
+    /**
+     * Get capacity estimates for a plan's monthly credits.
+     *
+     * Returns how many of each ISV-defined feature the plan supports per month.
+     * No Bearer token required — uses application key only.
+     *
+     * @param planSlug - The plan slug to calculate capacity for.
+     * @param options - Optional request-level overrides.
+     * @returns Plan details and capacity breakdown per composite operation.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.billing.capacityCalculator("pro-plan");
+     * console.log(`Plan: ${result.plan.name}`);
+     * for (const item of result.capacity) {
+     *   console.log(`${item.display_name}: ~${item.estimated_monthly_count}/month`);
+     * }
+     * ```
+     */
+    capacityCalculator: (planSlug: string, options?: RequestOptions) => Promise<CapacityCalculatorResponse>;
+};
+/** Response from the capacity-calculator endpoint. */
+export interface CapacityCalculatorResponse {
+    plan: {
+        slug: string;
+        name: string;
+        monthly_credits: number;
+    };
+    capacity: Array<{
+        key: string;
+        display_name: string;
+        description: string | null;
+        credits_per_use: number;
+        estimated_monthly_count: number;
+        is_estimate: boolean;
+        components: Array<{
+            operation_key: string;
+            quantity: number;
+            unit: string;
+            credits_per_unit: number | null;
+            total_credits: number;
+            is_estimate: boolean;
+        }>;
+    }>;
+    is_estimate: boolean;
+}
+//# sourceMappingURL=billing.d.ts.map