@stackbe/sdk 0.13.0 → 0.14.0

package/dist/index.d.mts

@@ -565,6 +565,56 @@ interface PaymentWebhookPayload {
     status: 'succeeded' | 'failed';
     failureReason?: string;
 }
+/** Payment method details */
+interface PaymentMethod {
+    id: string;
+    customerId: string;
+    gateway: 'stripe' | 'paypal' | 'authorize_net';
+    type: string;
+    last4?: string;
+    brand?: string;
+    expiryMonth?: number;
+    expiryYear?: number;
+    isDefault: boolean;
+    status: 'active' | 'expired' | 'failed';
+    createdAt: string;
+}
+/** Create setup session options */
+interface CreateSetupSessionOptions {
+    successUrl: string;
+    cancelUrl: string;
+}
+/** Setup session response */
+interface SetupSessionResponse {
+    sessionId: string;
+    url: string;
+    clientSecret?: string;
+}
+/** Attach payment method options */
+interface AttachPaymentMethodOptions {
+    gatewayPaymentMethodId: string;
+    setAsDefault?: boolean;
+}
+/** Charge subscription result */
+interface ChargeResult {
+    chargeId: string;
+    success: boolean;
+    status: 'succeeded' | 'failed' | 'pending' | 'requires_action';
+    gatewayChargeId?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    requiresAction?: boolean;
+    actionUrl?: string;
+    actionExpiresAt?: string;
+}
+/** Migration to StackBE-managed result */
+interface MigrateToStackbeManagedResult {
+    subscriptionId: string;
+    billingMode: 'stackbe_managed';
+    paymentMethodId: string;
+    nextBillingDate: string;
+    message: string;
+}
 type SubscriptionCreatedEvent = WebhookEvent<'subscription_created', SubscriptionWebhookPayload>;
 type SubscriptionUpdatedEvent = WebhookEvent<'subscription_updated', SubscriptionWebhookPayload>;
 type SubscriptionCancelledEvent = WebhookEvent<'subscription_cancelled', SubscriptionWebhookPayload>;
@@ -1348,6 +1398,160 @@ declare class SubscriptionsClient {
     checkAccess(subscriptionId: string): Promise<{
         hasAccess: boolean;
     }>;
+    /**
+     * Manually charge a StackBE-managed subscription.
+     *
+     * This is useful for:
+     * - Testing billing in development
+     * - Recovering from failed automatic charges
+     * - Charging ahead of schedule
+     *
+     * The subscription must be in `stackbe_managed` billing mode.
+     *
+     * @example
+     * ```typescript
+     * const result = await stackbe.subscriptions.charge('sub_123');
+     *
+     * if (result.success) {
+     *   console.log('Charge successful:', result.chargeId);
+     * } else if (result.requiresAction) {
+     *   // Redirect customer to 3DS authentication
+     *   window.location.href = result.actionUrl;
+     * } else {
+     *   console.log('Charge failed:', result.errorMessage);
+     * }
+     * ```
+     */
+    charge(subscriptionId: string): Promise<ChargeResult>;
+    /**
+     * Migrate a subscription from gateway-managed to StackBE-managed billing.
+     *
+     * This will:
+     * 1. Extract the payment method from the gateway subscription
+     * 2. Store it in StackBE's PaymentMethod table
+     * 3. Set the subscription to `stackbe_managed` billing mode
+     * 4. Cancel the gateway subscription at period end
+     * 5. StackBE will handle renewals going forward
+     *
+     * Use cases:
+     * - Migrate existing Stripe subscriptions to unified StackBE billing
+     * - Prepare for multi-gateway support
+     * - Gain more control over billing timing and retry logic
+     *
+     * @example
+     * ```typescript
+     * const result = await stackbe.subscriptions.migrateToStackbeManaged('sub_123');
+     *
+     * console.log('Migration complete');
+     * console.log('Payment method:', result.paymentMethodId);
+     * console.log('Next billing date:', result.nextBillingDate);
+     * ```
+     */
+    migrateToStackbeManaged(subscriptionId: string): Promise<MigrateToStackbeManagedResult>;
+}
+
+declare class PaymentMethodsClient {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Create a setup session for collecting a payment method.
+     *
+     * Returns a URL to redirect the customer to for secure payment method collection.
+     * This is similar to Stripe Checkout but in setup mode - no charge is made.
+     *
+     * @example
+     * ```typescript
+     * const session = await stackbe.paymentMethods.createSetupSession('cust_123', {
+     *   successUrl: 'https://yourapp.com/payment-methods/success',
+     *   cancelUrl: 'https://yourapp.com/payment-methods/cancel',
+     * });
+     *
+     * // Redirect customer to payment method collection
+     * window.location.href = session.url;
+     * ```
+     */
+    createSetupSession(customerId: string, options: CreateSetupSessionOptions): Promise<SetupSessionResponse>;
+    /**
+     * Attach a payment method to a customer.
+     *
+     * After the customer completes the setup session, call this to store
+     * the payment method in StackBE for future charges.
+     *
+     * @example
+     * ```typescript
+     * // After redirect from setup session
+     * const paymentMethod = await stackbe.paymentMethods.attach('cust_123', {
+     *   gatewayPaymentMethodId: 'pm_1234...', // From setup session completion
+     *   setAsDefault: true,
+     * });
+     *
+     * console.log(`Added ${paymentMethod.brand} ending in ${paymentMethod.last4}`);
+     * ```
+     */
+    attach(customerId: string, options: AttachPaymentMethodOptions): Promise<PaymentMethod>;
+    /**
+     * List all payment methods for a customer.
+     *
+     * @example
+     * ```typescript
+     * const paymentMethods = await stackbe.paymentMethods.list('cust_123');
+     *
+     * for (const pm of paymentMethods) {
+     *   console.log(`${pm.brand} **** ${pm.last4} ${pm.isDefault ? '(default)' : ''}`);
+     * }
+     * ```
+     */
+    list(customerId: string, options?: {
+        status?: string;
+    }): Promise<PaymentMethod[]>;
+    /**
+     * Get a specific payment method.
+     *
+     * @example
+     * ```typescript
+     * const pm = await stackbe.paymentMethods.get('cust_123', 'pm_123');
+     * console.log(`Expires: ${pm.expiryMonth}/${pm.expiryYear}`);
+     * ```
+     */
+    get(customerId: string, paymentMethodId: string): Promise<PaymentMethod>;
+    /**
+     * Set a payment method as the default for a customer.
+     *
+     * The default payment method is used for subscription renewals.
+     *
+     * @example
+     * ```typescript
+     * await stackbe.paymentMethods.setDefault('cust_123', 'pm_456');
+     * console.log('Default payment method updated');
+     * ```
+     */
+    setDefault(customerId: string, paymentMethodId: string): Promise<PaymentMethod>;
+    /**
+     * Remove a payment method.
+     *
+     * Cannot remove a payment method that is being used by an active subscription.
+     *
+     * @example
+     * ```typescript
+     * await stackbe.paymentMethods.remove('cust_123', 'pm_old');
+     * console.log('Payment method removed');
+     * ```
+     */
+    remove(customerId: string, paymentMethodId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get the default payment method for a customer.
+     *
+     * @example
+     * ```typescript
+     * const defaultPM = await stackbe.paymentMethods.getDefault('cust_123');
+     * if (defaultPM) {
+     *   console.log(`Default: ${defaultPM.brand} **** ${defaultPM.last4}`);
+     * }
+     * ```
+     */
+    getDefault(customerId: string): Promise<PaymentMethod | null>;
 }
 
 interface AuthClientOptions {
@@ -2665,6 +2869,8 @@ declare class StackBE {
     readonly checkout: CheckoutClient;
     /** Subscription management */
     readonly subscriptions: SubscriptionsClient;
+    /** Payment method management (StackBE-managed billing) */
+    readonly paymentMethods: PaymentMethodsClient;
     /** Customer authentication (magic links) */
     readonly auth: AuthClient;
     /** Organization management (B2B multi-user) */
@@ -2783,4 +2989,4 @@ declare class StackBE {
     }): (req: any, res: any, next: any) => Promise<any>;
 }
 
-export { type AddMemberOptions, type AffiliateCommission, type AffiliateCommissionsResponse, type AffiliateEnrollment, type AffiliateInfo, type AffiliateStats, AffiliatesClient, AnalyticsClient, type AnalyticsFilterOptions, type AnyWebhookEvent, AuthClient, type BillingPortalSession, type CancelSubscriptionOptions, type CancelSubscriptionResponse, type CheckEntitlementResponse, type CheckUsageResponse, CheckoutClient, type CheckoutSessionResponse, type Coupon, type CouponDiscountType, type CouponDuration, CouponsClient, type CreateCheckoutOptions, type CreateCouponOptions, type CreateCustomerOptions, type CreateEarlyAccessSignupOptions, type CreateFeatureRequestOptions, type CreateOrganizationOptions, type Customer, type CustomerCreatedEvent, type CustomerFeatureActivity, type CustomerInvoice, type CustomerInvoicesResponse, type CustomerPaymentMethod, type CustomerSubscriptionHistory, type CustomerSubscriptionHistoryResponse, type CustomerUpdatedEvent, type CustomerUsageResponse, type CustomerWebhookPayload, type CustomerWithSubscription, CustomersClient, type DashboardMetrics, type DunningStatus, EarlyAccessClient, type EarlyAccessSignup, type EarlyAccessSignupListResponse, type EnrollOptions, EntitlementsClient, type EntitlementsResponse, type FeatureRequest, type FeatureRequestComment, type FeatureRequestImage, type FeatureRequestListResponse, FeatureRequestsClient, type FeatureUsagePoint, type GetSubscriptionOptions, type GrowthChartPoint, type GrowthMetrics, type InterestedCustomer, type InterestedCustomersResponse, type InviteMemberOptions, type ListEarlyAccessOptions, type ListFeatureRequestsOptions, type ListPlansOptions, type ListProductsOptions, type MRRHistoryPoint, type MagicLinkOptions, type MagicLinkResponse, type Organization, type OrganizationInvite, type OrganizationMember, OrganizationsClient, type PaymentFailedEvent, type PaymentSucceededEvent, type PaymentWebhookPayload, type PerformanceMetrics, type Plan, type PlanMetrics, PlansClient, type PopularEndpoint, type Product, ProductsClient, type RequestCountPoint, type RevenueByPlan, type SessionResponse, StackBE, type StackBEConfig, StackBEError, type StackBEErrorCode, type StackBEErrorResponse, type Subscription, type SubscriptionCancelledEvent, type SubscriptionCreatedEvent, type SubscriptionPlan, type SubscriptionRenewedEvent, type SubscriptionUpdatedEvent, type SubscriptionWebhookPayload, type SubscriptionWithPlan, SubscriptionsClient, type SwitchOrganizationResponse, type TimeRangeOptions, type TrackReferralResponse, type TrackUsageOptions, type TrackUsageResponse, type TrialEndedEvent, type TrialMetrics, type TrialStartedEvent, type TrialStatus, type UpcomingInvoice, type UpdateCouponOptions, type UpdateCustomerOptions, type UpdateOrganizationOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type ValidateCouponResult, type VerifyTokenResponse, type WebhookEvent, type WebhookEventType };
+export { type AddMemberOptions, type AffiliateCommission, type AffiliateCommissionsResponse, type AffiliateEnrollment, type AffiliateInfo, type AffiliateStats, AffiliatesClient, AnalyticsClient, type AnalyticsFilterOptions, type AnyWebhookEvent, type AttachPaymentMethodOptions, AuthClient, type BillingPortalSession, type CancelSubscriptionOptions, type CancelSubscriptionResponse, type ChargeResult, type CheckEntitlementResponse, type CheckUsageResponse, CheckoutClient, type CheckoutSessionResponse, type Coupon, type CouponDiscountType, type CouponDuration, CouponsClient, type CreateCheckoutOptions, type CreateCouponOptions, type CreateCustomerOptions, type CreateEarlyAccessSignupOptions, type CreateFeatureRequestOptions, type CreateOrganizationOptions, type CreateSetupSessionOptions, type Customer, type CustomerCreatedEvent, type CustomerFeatureActivity, type CustomerInvoice, type CustomerInvoicesResponse, type CustomerPaymentMethod, type CustomerSubscriptionHistory, type CustomerSubscriptionHistoryResponse, type CustomerUpdatedEvent, type CustomerUsageResponse, type CustomerWebhookPayload, type CustomerWithSubscription, CustomersClient, type DashboardMetrics, type DunningStatus, EarlyAccessClient, type EarlyAccessSignup, type EarlyAccessSignupListResponse, type EnrollOptions, EntitlementsClient, type EntitlementsResponse, type FeatureRequest, type FeatureRequestComment, type FeatureRequestImage, type FeatureRequestListResponse, FeatureRequestsClient, type FeatureUsagePoint, type GetSubscriptionOptions, type GrowthChartPoint, type GrowthMetrics, type InterestedCustomer, type InterestedCustomersResponse, type InviteMemberOptions, type ListEarlyAccessOptions, type ListFeatureRequestsOptions, type ListPlansOptions, type ListProductsOptions, type MRRHistoryPoint, type MagicLinkOptions, type MagicLinkResponse, type MigrateToStackbeManagedResult, type Organization, type OrganizationInvite, type OrganizationMember, OrganizationsClient, type PaymentFailedEvent, type PaymentMethod, PaymentMethodsClient, type PaymentSucceededEvent, type PaymentWebhookPayload, type PerformanceMetrics, type Plan, type PlanMetrics, PlansClient, type PopularEndpoint, type Product, ProductsClient, type RequestCountPoint, type RevenueByPlan, type SessionResponse, type SetupSessionResponse, StackBE, type StackBEConfig, StackBEError, type StackBEErrorCode, type StackBEErrorResponse, type Subscription, type SubscriptionCancelledEvent, type SubscriptionCreatedEvent, type SubscriptionPlan, type SubscriptionRenewedEvent, type SubscriptionUpdatedEvent, type SubscriptionWebhookPayload, type SubscriptionWithPlan, SubscriptionsClient, type SwitchOrganizationResponse, type TimeRangeOptions, type TrackReferralResponse, type TrackUsageOptions, type TrackUsageResponse, type TrialEndedEvent, type TrialMetrics, type TrialStartedEvent, type TrialStatus, type UpcomingInvoice, type UpdateCouponOptions, type UpdateCustomerOptions, type UpdateOrganizationOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type ValidateCouponResult, type VerifyTokenResponse, type WebhookEvent, type WebhookEventType };

package/dist/index.d.ts

@@ -565,6 +565,56 @@ interface PaymentWebhookPayload {
     status: 'succeeded' | 'failed';
     failureReason?: string;
 }
+/** Payment method details */
+interface PaymentMethod {
+    id: string;
+    customerId: string;
+    gateway: 'stripe' | 'paypal' | 'authorize_net';
+    type: string;
+    last4?: string;
+    brand?: string;
+    expiryMonth?: number;
+    expiryYear?: number;
+    isDefault: boolean;
+    status: 'active' | 'expired' | 'failed';
+    createdAt: string;
+}
+/** Create setup session options */
+interface CreateSetupSessionOptions {
+    successUrl: string;
+    cancelUrl: string;
+}
+/** Setup session response */
+interface SetupSessionResponse {
+    sessionId: string;
+    url: string;
+    clientSecret?: string;
+}
+/** Attach payment method options */
+interface AttachPaymentMethodOptions {
+    gatewayPaymentMethodId: string;
+    setAsDefault?: boolean;
+}
+/** Charge subscription result */
+interface ChargeResult {
+    chargeId: string;
+    success: boolean;
+    status: 'succeeded' | 'failed' | 'pending' | 'requires_action';
+    gatewayChargeId?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    requiresAction?: boolean;
+    actionUrl?: string;
+    actionExpiresAt?: string;
+}
+/** Migration to StackBE-managed result */
+interface MigrateToStackbeManagedResult {
+    subscriptionId: string;
+    billingMode: 'stackbe_managed';
+    paymentMethodId: string;
+    nextBillingDate: string;
+    message: string;
+}
 type SubscriptionCreatedEvent = WebhookEvent<'subscription_created', SubscriptionWebhookPayload>;
 type SubscriptionUpdatedEvent = WebhookEvent<'subscription_updated', SubscriptionWebhookPayload>;
 type SubscriptionCancelledEvent = WebhookEvent<'subscription_cancelled', SubscriptionWebhookPayload>;
@@ -1348,6 +1398,160 @@ declare class SubscriptionsClient {
     checkAccess(subscriptionId: string): Promise<{
         hasAccess: boolean;
     }>;
+    /**
+     * Manually charge a StackBE-managed subscription.
+     *
+     * This is useful for:
+     * - Testing billing in development
+     * - Recovering from failed automatic charges
+     * - Charging ahead of schedule
+     *
+     * The subscription must be in `stackbe_managed` billing mode.
+     *
+     * @example
+     * ```typescript
+     * const result = await stackbe.subscriptions.charge('sub_123');
+     *
+     * if (result.success) {
+     *   console.log('Charge successful:', result.chargeId);
+     * } else if (result.requiresAction) {
+     *   // Redirect customer to 3DS authentication
+     *   window.location.href = result.actionUrl;
+     * } else {
+     *   console.log('Charge failed:', result.errorMessage);
+     * }
+     * ```
+     */
+    charge(subscriptionId: string): Promise<ChargeResult>;
+    /**
+     * Migrate a subscription from gateway-managed to StackBE-managed billing.
+     *
+     * This will:
+     * 1. Extract the payment method from the gateway subscription
+     * 2. Store it in StackBE's PaymentMethod table
+     * 3. Set the subscription to `stackbe_managed` billing mode
+     * 4. Cancel the gateway subscription at period end
+     * 5. StackBE will handle renewals going forward
+     *
+     * Use cases:
+     * - Migrate existing Stripe subscriptions to unified StackBE billing
+     * - Prepare for multi-gateway support
+     * - Gain more control over billing timing and retry logic
+     *
+     * @example
+     * ```typescript
+     * const result = await stackbe.subscriptions.migrateToStackbeManaged('sub_123');
+     *
+     * console.log('Migration complete');
+     * console.log('Payment method:', result.paymentMethodId);
+     * console.log('Next billing date:', result.nextBillingDate);
+     * ```
+     */
+    migrateToStackbeManaged(subscriptionId: string): Promise<MigrateToStackbeManagedResult>;
+}
+
+declare class PaymentMethodsClient {
+    private http;
+    constructor(http: HttpClient);
+    /**
+     * Create a setup session for collecting a payment method.
+     *
+     * Returns a URL to redirect the customer to for secure payment method collection.
+     * This is similar to Stripe Checkout but in setup mode - no charge is made.
+     *
+     * @example
+     * ```typescript
+     * const session = await stackbe.paymentMethods.createSetupSession('cust_123', {
+     *   successUrl: 'https://yourapp.com/payment-methods/success',
+     *   cancelUrl: 'https://yourapp.com/payment-methods/cancel',
+     * });
+     *
+     * // Redirect customer to payment method collection
+     * window.location.href = session.url;
+     * ```
+     */
+    createSetupSession(customerId: string, options: CreateSetupSessionOptions): Promise<SetupSessionResponse>;
+    /**
+     * Attach a payment method to a customer.
+     *
+     * After the customer completes the setup session, call this to store
+     * the payment method in StackBE for future charges.
+     *
+     * @example
+     * ```typescript
+     * // After redirect from setup session
+     * const paymentMethod = await stackbe.paymentMethods.attach('cust_123', {
+     *   gatewayPaymentMethodId: 'pm_1234...', // From setup session completion
+     *   setAsDefault: true,
+     * });
+     *
+     * console.log(`Added ${paymentMethod.brand} ending in ${paymentMethod.last4}`);
+     * ```
+     */
+    attach(customerId: string, options: AttachPaymentMethodOptions): Promise<PaymentMethod>;
+    /**
+     * List all payment methods for a customer.
+     *
+     * @example
+     * ```typescript
+     * const paymentMethods = await stackbe.paymentMethods.list('cust_123');
+     *
+     * for (const pm of paymentMethods) {
+     *   console.log(`${pm.brand} **** ${pm.last4} ${pm.isDefault ? '(default)' : ''}`);
+     * }
+     * ```
+     */
+    list(customerId: string, options?: {
+        status?: string;
+    }): Promise<PaymentMethod[]>;
+    /**
+     * Get a specific payment method.
+     *
+     * @example
+     * ```typescript
+     * const pm = await stackbe.paymentMethods.get('cust_123', 'pm_123');
+     * console.log(`Expires: ${pm.expiryMonth}/${pm.expiryYear}`);
+     * ```
+     */
+    get(customerId: string, paymentMethodId: string): Promise<PaymentMethod>;
+    /**
+     * Set a payment method as the default for a customer.
+     *
+     * The default payment method is used for subscription renewals.
+     *
+     * @example
+     * ```typescript
+     * await stackbe.paymentMethods.setDefault('cust_123', 'pm_456');
+     * console.log('Default payment method updated');
+     * ```
+     */
+    setDefault(customerId: string, paymentMethodId: string): Promise<PaymentMethod>;
+    /**
+     * Remove a payment method.
+     *
+     * Cannot remove a payment method that is being used by an active subscription.
+     *
+     * @example
+     * ```typescript
+     * await stackbe.paymentMethods.remove('cust_123', 'pm_old');
+     * console.log('Payment method removed');
+     * ```
+     */
+    remove(customerId: string, paymentMethodId: string): Promise<{
+        success: boolean;
+    }>;
+    /**
+     * Get the default payment method for a customer.
+     *
+     * @example
+     * ```typescript
+     * const defaultPM = await stackbe.paymentMethods.getDefault('cust_123');
+     * if (defaultPM) {
+     *   console.log(`Default: ${defaultPM.brand} **** ${defaultPM.last4}`);
+     * }
+     * ```
+     */
+    getDefault(customerId: string): Promise<PaymentMethod | null>;
 }
 
 interface AuthClientOptions {
@@ -2665,6 +2869,8 @@ declare class StackBE {
     readonly checkout: CheckoutClient;
     /** Subscription management */
     readonly subscriptions: SubscriptionsClient;
+    /** Payment method management (StackBE-managed billing) */
+    readonly paymentMethods: PaymentMethodsClient;
     /** Customer authentication (magic links) */
     readonly auth: AuthClient;
     /** Organization management (B2B multi-user) */
@@ -2783,4 +2989,4 @@ declare class StackBE {
     }): (req: any, res: any, next: any) => Promise<any>;
 }
 
-export { type AddMemberOptions, type AffiliateCommission, type AffiliateCommissionsResponse, type AffiliateEnrollment, type AffiliateInfo, type AffiliateStats, AffiliatesClient, AnalyticsClient, type AnalyticsFilterOptions, type AnyWebhookEvent, AuthClient, type BillingPortalSession, type CancelSubscriptionOptions, type CancelSubscriptionResponse, type CheckEntitlementResponse, type CheckUsageResponse, CheckoutClient, type CheckoutSessionResponse, type Coupon, type CouponDiscountType, type CouponDuration, CouponsClient, type CreateCheckoutOptions, type CreateCouponOptions, type CreateCustomerOptions, type CreateEarlyAccessSignupOptions, type CreateFeatureRequestOptions, type CreateOrganizationOptions, type Customer, type CustomerCreatedEvent, type CustomerFeatureActivity, type CustomerInvoice, type CustomerInvoicesResponse, type CustomerPaymentMethod, type CustomerSubscriptionHistory, type CustomerSubscriptionHistoryResponse, type CustomerUpdatedEvent, type CustomerUsageResponse, type CustomerWebhookPayload, type CustomerWithSubscription, CustomersClient, type DashboardMetrics, type DunningStatus, EarlyAccessClient, type EarlyAccessSignup, type EarlyAccessSignupListResponse, type EnrollOptions, EntitlementsClient, type EntitlementsResponse, type FeatureRequest, type FeatureRequestComment, type FeatureRequestImage, type FeatureRequestListResponse, FeatureRequestsClient, type FeatureUsagePoint, type GetSubscriptionOptions, type GrowthChartPoint, type GrowthMetrics, type InterestedCustomer, type InterestedCustomersResponse, type InviteMemberOptions, type ListEarlyAccessOptions, type ListFeatureRequestsOptions, type ListPlansOptions, type ListProductsOptions, type MRRHistoryPoint, type MagicLinkOptions, type MagicLinkResponse, type Organization, type OrganizationInvite, type OrganizationMember, OrganizationsClient, type PaymentFailedEvent, type PaymentSucceededEvent, type PaymentWebhookPayload, type PerformanceMetrics, type Plan, type PlanMetrics, PlansClient, type PopularEndpoint, type Product, ProductsClient, type RequestCountPoint, type RevenueByPlan, type SessionResponse, StackBE, type StackBEConfig, StackBEError, type StackBEErrorCode, type StackBEErrorResponse, type Subscription, type SubscriptionCancelledEvent, type SubscriptionCreatedEvent, type SubscriptionPlan, type SubscriptionRenewedEvent, type SubscriptionUpdatedEvent, type SubscriptionWebhookPayload, type SubscriptionWithPlan, SubscriptionsClient, type SwitchOrganizationResponse, type TimeRangeOptions, type TrackReferralResponse, type TrackUsageOptions, type TrackUsageResponse, type TrialEndedEvent, type TrialMetrics, type TrialStartedEvent, type TrialStatus, type UpcomingInvoice, type UpdateCouponOptions, type UpdateCustomerOptions, type UpdateOrganizationOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type ValidateCouponResult, type VerifyTokenResponse, type WebhookEvent, type WebhookEventType };
+export { type AddMemberOptions, type AffiliateCommission, type AffiliateCommissionsResponse, type AffiliateEnrollment, type AffiliateInfo, type AffiliateStats, AffiliatesClient, AnalyticsClient, type AnalyticsFilterOptions, type AnyWebhookEvent, type AttachPaymentMethodOptions, AuthClient, type BillingPortalSession, type CancelSubscriptionOptions, type CancelSubscriptionResponse, type ChargeResult, type CheckEntitlementResponse, type CheckUsageResponse, CheckoutClient, type CheckoutSessionResponse, type Coupon, type CouponDiscountType, type CouponDuration, CouponsClient, type CreateCheckoutOptions, type CreateCouponOptions, type CreateCustomerOptions, type CreateEarlyAccessSignupOptions, type CreateFeatureRequestOptions, type CreateOrganizationOptions, type CreateSetupSessionOptions, type Customer, type CustomerCreatedEvent, type CustomerFeatureActivity, type CustomerInvoice, type CustomerInvoicesResponse, type CustomerPaymentMethod, type CustomerSubscriptionHistory, type CustomerSubscriptionHistoryResponse, type CustomerUpdatedEvent, type CustomerUsageResponse, type CustomerWebhookPayload, type CustomerWithSubscription, CustomersClient, type DashboardMetrics, type DunningStatus, EarlyAccessClient, type EarlyAccessSignup, type EarlyAccessSignupListResponse, type EnrollOptions, EntitlementsClient, type EntitlementsResponse, type FeatureRequest, type FeatureRequestComment, type FeatureRequestImage, type FeatureRequestListResponse, FeatureRequestsClient, type FeatureUsagePoint, type GetSubscriptionOptions, type GrowthChartPoint, type GrowthMetrics, type InterestedCustomer, type InterestedCustomersResponse, type InviteMemberOptions, type ListEarlyAccessOptions, type ListFeatureRequestsOptions, type ListPlansOptions, type ListProductsOptions, type MRRHistoryPoint, type MagicLinkOptions, type MagicLinkResponse, type MigrateToStackbeManagedResult, type Organization, type OrganizationInvite, type OrganizationMember, OrganizationsClient, type PaymentFailedEvent, type PaymentMethod, PaymentMethodsClient, type PaymentSucceededEvent, type PaymentWebhookPayload, type PerformanceMetrics, type Plan, type PlanMetrics, PlansClient, type PopularEndpoint, type Product, ProductsClient, type RequestCountPoint, type RevenueByPlan, type SessionResponse, type SetupSessionResponse, StackBE, type StackBEConfig, StackBEError, type StackBEErrorCode, type StackBEErrorResponse, type Subscription, type SubscriptionCancelledEvent, type SubscriptionCreatedEvent, type SubscriptionPlan, type SubscriptionRenewedEvent, type SubscriptionUpdatedEvent, type SubscriptionWebhookPayload, type SubscriptionWithPlan, SubscriptionsClient, type SwitchOrganizationResponse, type TimeRangeOptions, type TrackReferralResponse, type TrackUsageOptions, type TrackUsageResponse, type TrialEndedEvent, type TrialMetrics, type TrialStartedEvent, type TrialStatus, type UpcomingInvoice, type UpdateCouponOptions, type UpdateCustomerOptions, type UpdateOrganizationOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type ValidateCouponResult, type VerifyTokenResponse, type WebhookEvent, type WebhookEventType };

package/dist/index.js

@@ -30,6 +30,7 @@ __export(index_exports, {
   EntitlementsClient: () => EntitlementsClient,
   FeatureRequestsClient: () => FeatureRequestsClient,
   OrganizationsClient: () => OrganizationsClient,
+  PaymentMethodsClient: () => PaymentMethodsClient,
   PlansClient: () => PlansClient,
   ProductsClient: () => ProductsClient,
   StackBE: () => StackBE,
@@ -1168,6 +1169,201 @@ var SubscriptionsClient = class {
       `/v1/subscriptions/${subscriptionId}/has-access`
     );
   }
+  // ============================================
+  // StackBE-Managed Billing Methods
+  // ============================================
+  /**
+   * Manually charge a StackBE-managed subscription.
+   *
+   * This is useful for:
+   * - Testing billing in development
+   * - Recovering from failed automatic charges
+   * - Charging ahead of schedule
+   *
+   * The subscription must be in `stackbe_managed` billing mode.
+   *
+   * @example
+   * ```typescript
+   * const result = await stackbe.subscriptions.charge('sub_123');
+   *
+   * if (result.success) {
+   *   console.log('Charge successful:', result.chargeId);
+   * } else if (result.requiresAction) {
+   *   // Redirect customer to 3DS authentication
+   *   window.location.href = result.actionUrl;
+   * } else {
+   *   console.log('Charge failed:', result.errorMessage);
+   * }
+   * ```
+   */
+  async charge(subscriptionId) {
+    return this.http.post(
+      `/v1/subscriptions/${subscriptionId}/charge`
+    );
+  }
+  /**
+   * Migrate a subscription from gateway-managed to StackBE-managed billing.
+   *
+   * This will:
+   * 1. Extract the payment method from the gateway subscription
+   * 2. Store it in StackBE's PaymentMethod table
+   * 3. Set the subscription to `stackbe_managed` billing mode
+   * 4. Cancel the gateway subscription at period end
+   * 5. StackBE will handle renewals going forward
+   *
+   * Use cases:
+   * - Migrate existing Stripe subscriptions to unified StackBE billing
+   * - Prepare for multi-gateway support
+   * - Gain more control over billing timing and retry logic
+   *
+   * @example
+   * ```typescript
+   * const result = await stackbe.subscriptions.migrateToStackbeManaged('sub_123');
+   *
+   * console.log('Migration complete');
+   * console.log('Payment method:', result.paymentMethodId);
+   * console.log('Next billing date:', result.nextBillingDate);
+   * ```
+   */
+  async migrateToStackbeManaged(subscriptionId) {
+    return this.http.post(
+      `/v1/subscriptions/${subscriptionId}/migrate-to-stackbe-managed`
+    );
+  }
+};
+
+// src/payment-methods.ts
+var PaymentMethodsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a setup session for collecting a payment method.
+   *
+   * Returns a URL to redirect the customer to for secure payment method collection.
+   * This is similar to Stripe Checkout but in setup mode - no charge is made.
+   *
+   * @example
+   * ```typescript
+   * const session = await stackbe.paymentMethods.createSetupSession('cust_123', {
+   *   successUrl: 'https://yourapp.com/payment-methods/success',
+   *   cancelUrl: 'https://yourapp.com/payment-methods/cancel',
+   * });
+   *
+   * // Redirect customer to payment method collection
+   * window.location.href = session.url;
+   * ```
+   */
+  async createSetupSession(customerId, options) {
+    return this.http.post(
+      `/v1/apps/{appId}/customers/${customerId}/payment-methods/setup`,
+      options
+    );
+  }
+  /**
+   * Attach a payment method to a customer.
+   *
+   * After the customer completes the setup session, call this to store
+   * the payment method in StackBE for future charges.
+   *
+   * @example
+   * ```typescript
+   * // After redirect from setup session
+   * const paymentMethod = await stackbe.paymentMethods.attach('cust_123', {
+   *   gatewayPaymentMethodId: 'pm_1234...', // From setup session completion
+   *   setAsDefault: true,
+   * });
+   *
+   * console.log(`Added ${paymentMethod.brand} ending in ${paymentMethod.last4}`);
+   * ```
+   */
+  async attach(customerId, options) {
+    return this.http.post(
+      `/v1/apps/{appId}/customers/${customerId}/payment-methods`,
+      options
+    );
+  }
+  /**
+   * List all payment methods for a customer.
+   *
+   * @example
+   * ```typescript
+   * const paymentMethods = await stackbe.paymentMethods.list('cust_123');
+   *
+   * for (const pm of paymentMethods) {
+   *   console.log(`${pm.brand} **** ${pm.last4} ${pm.isDefault ? '(default)' : ''}`);
+   * }
+   * ```
+   */
+  async list(customerId, options) {
+    const params = {};
+    if (options?.status) params.status = options.status;
+    return this.http.get(
+      `/v1/apps/{appId}/customers/${customerId}/payment-methods`,
+      params
+    );
+  }
+  /**
+   * Get a specific payment method.
+   *
+   * @example
+   * ```typescript
+   * const pm = await stackbe.paymentMethods.get('cust_123', 'pm_123');
+   * console.log(`Expires: ${pm.expiryMonth}/${pm.expiryYear}`);
+   * ```
+   */
+  async get(customerId, paymentMethodId) {
+    return this.http.get(
+      `/v1/apps/{appId}/customers/${customerId}/payment-methods/${paymentMethodId}`
+    );
+  }
+  /**
+   * Set a payment method as the default for a customer.
+   *
+   * The default payment method is used for subscription renewals.
+   *
+   * @example
+   * ```typescript
+   * await stackbe.paymentMethods.setDefault('cust_123', 'pm_456');
+   * console.log('Default payment method updated');
+   * ```
+   */
+  async setDefault(customerId, paymentMethodId) {
+    return this.http.post(
+      `/v1/apps/{appId}/customers/${customerId}/payment-methods/${paymentMethodId}/default`
+    );
+  }
+  /**
+   * Remove a payment method.
+   *
+   * Cannot remove a payment method that is being used by an active subscription.
+   *
+   * @example
+   * ```typescript
+   * await stackbe.paymentMethods.remove('cust_123', 'pm_old');
+   * console.log('Payment method removed');
+   * ```
+   */
+  async remove(customerId, paymentMethodId) {
+    return this.http.delete(
+      `/v1/apps/{appId}/customers/${customerId}/payment-methods/${paymentMethodId}`
+    );
+  }
+  /**
+   * Get the default payment method for a customer.
+   *
+   * @example
+   * ```typescript
+   * const defaultPM = await stackbe.paymentMethods.getDefault('cust_123');
+   * if (defaultPM) {
+   *   console.log(`Default: ${defaultPM.brand} **** ${defaultPM.last4}`);
+   * }
+   * ```
+   */
+  async getDefault(customerId) {
+    const paymentMethods = await this.list(customerId, { status: "active" });
+    return paymentMethods.find((pm) => pm.isDefault) || null;
+  }
 };
 
 // src/auth.ts
@@ -2566,6 +2762,7 @@ var StackBE = class {
     this.customers = new CustomersClient(this.http, config.appId);
     this.checkout = new CheckoutClient(this.http, config.appId);
     this.subscriptions = new SubscriptionsClient(this.http);
+    this.paymentMethods = new PaymentMethodsClient(this.http);
     this.auth = new AuthClient(this.http, config.appId, {
       sessionCacheTTL: config.sessionCacheTTL,
       devCallbackUrl: config.devCallbackUrl
@@ -2721,6 +2918,7 @@ var StackBE = class {
   EntitlementsClient,
   FeatureRequestsClient,
   OrganizationsClient,
+  PaymentMethodsClient,
   PlansClient,
   ProductsClient,
   StackBE,

package/dist/index.mjs

@@ -1127,6 +1127,201 @@ var SubscriptionsClient = class {
       `/v1/subscriptions/${subscriptionId}/has-access`
     );
   }
+  // ============================================
+  // StackBE-Managed Billing Methods
+  // ============================================
+  /**
+   * Manually charge a StackBE-managed subscription.
+   *
+   * This is useful for:
+   * - Testing billing in development
+   * - Recovering from failed automatic charges
+   * - Charging ahead of schedule
+   *
+   * The subscription must be in `stackbe_managed` billing mode.
+   *
+   * @example
+   * ```typescript
+   * const result = await stackbe.subscriptions.charge('sub_123');
+   *
+   * if (result.success) {
+   *   console.log('Charge successful:', result.chargeId);
+   * } else if (result.requiresAction) {
+   *   // Redirect customer to 3DS authentication
+   *   window.location.href = result.actionUrl;
+   * } else {
+   *   console.log('Charge failed:', result.errorMessage);
+   * }
+   * ```
+   */
+  async charge(subscriptionId) {
+    return this.http.post(
+      `/v1/subscriptions/${subscriptionId}/charge`
+    );
+  }
+  /**
+   * Migrate a subscription from gateway-managed to StackBE-managed billing.
+   *
+   * This will:
+   * 1. Extract the payment method from the gateway subscription
+   * 2. Store it in StackBE's PaymentMethod table
+   * 3. Set the subscription to `stackbe_managed` billing mode
+   * 4. Cancel the gateway subscription at period end
+   * 5. StackBE will handle renewals going forward
+   *
+   * Use cases:
+   * - Migrate existing Stripe subscriptions to unified StackBE billing
+   * - Prepare for multi-gateway support
+   * - Gain more control over billing timing and retry logic
+   *
+   * @example
+   * ```typescript
+   * const result = await stackbe.subscriptions.migrateToStackbeManaged('sub_123');
+   *
+   * console.log('Migration complete');
+   * console.log('Payment method:', result.paymentMethodId);
+   * console.log('Next billing date:', result.nextBillingDate);
+   * ```
+   */
+  async migrateToStackbeManaged(subscriptionId) {
+    return this.http.post(
+      `/v1/subscriptions/${subscriptionId}/migrate-to-stackbe-managed`
+    );
+  }
+};
+
+// src/payment-methods.ts
+var PaymentMethodsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Create a setup session for collecting a payment method.
+   *
+   * Returns a URL to redirect the customer to for secure payment method collection.
+   * This is similar to Stripe Checkout but in setup mode - no charge is made.
+   *
+   * @example
+   * ```typescript
+   * const session = await stackbe.paymentMethods.createSetupSession('cust_123', {
+   *   successUrl: 'https://yourapp.com/payment-methods/success',
+   *   cancelUrl: 'https://yourapp.com/payment-methods/cancel',
+   * });
+   *
+   * // Redirect customer to payment method collection
+   * window.location.href = session.url;
+   * ```
+   */
+  async createSetupSession(customerId, options) {
+    return this.http.post(
+      `/v1/apps/{appId}/customers/${customerId}/payment-methods/setup`,
+      options
+    );
+  }
+  /**
+   * Attach a payment method to a customer.
+   *
+   * After the customer completes the setup session, call this to store
+   * the payment method in StackBE for future charges.
+   *
+   * @example
+   * ```typescript
+   * // After redirect from setup session
+   * const paymentMethod = await stackbe.paymentMethods.attach('cust_123', {
+   *   gatewayPaymentMethodId: 'pm_1234...', // From setup session completion
+   *   setAsDefault: true,
+   * });
+   *
+   * console.log(`Added ${paymentMethod.brand} ending in ${paymentMethod.last4}`);
+   * ```
+   */
+  async attach(customerId, options) {
+    return this.http.post(
+      `/v1/apps/{appId}/customers/${customerId}/payment-methods`,
+      options
+    );
+  }
+  /**
+   * List all payment methods for a customer.
+   *
+   * @example
+   * ```typescript
+   * const paymentMethods = await stackbe.paymentMethods.list('cust_123');
+   *
+   * for (const pm of paymentMethods) {
+   *   console.log(`${pm.brand} **** ${pm.last4} ${pm.isDefault ? '(default)' : ''}`);
+   * }
+   * ```
+   */
+  async list(customerId, options) {
+    const params = {};
+    if (options?.status) params.status = options.status;
+    return this.http.get(
+      `/v1/apps/{appId}/customers/${customerId}/payment-methods`,
+      params
+    );
+  }
+  /**
+   * Get a specific payment method.
+   *
+   * @example
+   * ```typescript
+   * const pm = await stackbe.paymentMethods.get('cust_123', 'pm_123');
+   * console.log(`Expires: ${pm.expiryMonth}/${pm.expiryYear}`);
+   * ```
+   */
+  async get(customerId, paymentMethodId) {
+    return this.http.get(
+      `/v1/apps/{appId}/customers/${customerId}/payment-methods/${paymentMethodId}`
+    );
+  }
+  /**
+   * Set a payment method as the default for a customer.
+   *
+   * The default payment method is used for subscription renewals.
+   *
+   * @example
+   * ```typescript
+   * await stackbe.paymentMethods.setDefault('cust_123', 'pm_456');
+   * console.log('Default payment method updated');
+   * ```
+   */
+  async setDefault(customerId, paymentMethodId) {
+    return this.http.post(
+      `/v1/apps/{appId}/customers/${customerId}/payment-methods/${paymentMethodId}/default`
+    );
+  }
+  /**
+   * Remove a payment method.
+   *
+   * Cannot remove a payment method that is being used by an active subscription.
+   *
+   * @example
+   * ```typescript
+   * await stackbe.paymentMethods.remove('cust_123', 'pm_old');
+   * console.log('Payment method removed');
+   * ```
+   */
+  async remove(customerId, paymentMethodId) {
+    return this.http.delete(
+      `/v1/apps/{appId}/customers/${customerId}/payment-methods/${paymentMethodId}`
+    );
+  }
+  /**
+   * Get the default payment method for a customer.
+   *
+   * @example
+   * ```typescript
+   * const defaultPM = await stackbe.paymentMethods.getDefault('cust_123');
+   * if (defaultPM) {
+   *   console.log(`Default: ${defaultPM.brand} **** ${defaultPM.last4}`);
+   * }
+   * ```
+   */
+  async getDefault(customerId) {
+    const paymentMethods = await this.list(customerId, { status: "active" });
+    return paymentMethods.find((pm) => pm.isDefault) || null;
+  }
 };
 
 // src/auth.ts
@@ -2525,6 +2720,7 @@ var StackBE = class {
     this.customers = new CustomersClient(this.http, config.appId);
     this.checkout = new CheckoutClient(this.http, config.appId);
     this.subscriptions = new SubscriptionsClient(this.http);
+    this.paymentMethods = new PaymentMethodsClient(this.http);
     this.auth = new AuthClient(this.http, config.appId, {
       sessionCacheTTL: config.sessionCacheTTL,
       devCallbackUrl: config.devCallbackUrl
@@ -2679,6 +2875,7 @@ export {
   EntitlementsClient,
   FeatureRequestsClient,
   OrganizationsClient,
+  PaymentMethodsClient,
   PlansClient,
   ProductsClient,
   StackBE,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbe/sdk",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Official JavaScript/TypeScript SDK for StackBE - the billing backend for your side project",
   "main": "dist/index.js",
   "module": "dist/index.mjs",