@stackbe/sdk 0.13.0 → 0.15.0

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
@@ -2022,37 +2217,18 @@ var AffiliatesClient = class {
   /**
    * Get the current customer's affiliate info.
    * Requires customer session token.
-   *
-   * @example
-   * ```typescript
-   * const affiliate = await stackbe.affiliates.get();
-   *
-   * if (affiliate.enrolled) {
-   *   console.log(`Your referral code: ${affiliate.code}`);
-   *   console.log(`Earnings: $${(affiliate.totalEarned! / 100).toFixed(2)}`);
-   * } else {
-   *   console.log('Not enrolled in affiliate program');
-   * }
-   * ```
    */
   async get() {
     return this.http.get("/v1/affiliate");
   }
   /**
-   * Enroll the current customer as an affiliate.
+   * Enroll the current customer as an affiliate/partner.
    * Requires customer session token.
    *
    * @example
    * ```typescript
-   * // Enroll with auto-generated code
-   * const affiliate = await stackbe.affiliates.enroll();
+   * const affiliate = await stackbe.affiliates.enroll({ type: 'referral' });
    * console.log(`Your referral code: ${affiliate.code}`);
-   *
-   * // Enroll with custom code
-   * const affiliate = await stackbe.affiliates.enroll({
-   *   code: 'MYCODE',
-   *   payoutEmail: 'payouts@example.com',
-   * });
    * ```
    */
   async enroll(options = {}) {
@@ -2061,18 +2237,6 @@ var AffiliatesClient = class {
   /**
    * Get affiliate statistics.
    * Requires customer session token.
-   *
-   * @example
-   * ```typescript
-   * const stats = await stackbe.affiliates.getStats();
-   *
-   * if (stats.enrolled) {
-   *   console.log(`Total earned: $${(stats.totalEarned / 100).toFixed(2)}`);
-   *   console.log(`Pending: $${(stats.pendingBalance / 100).toFixed(2)}`);
-   *   console.log(`Referrals: ${stats.totalReferrals}`);
-   *   console.log(`Conversions: ${stats.totalConversions}`);
-   * }
-   * ```
    */
   async getStats() {
     return this.http.get("/v1/affiliate/stats");
@@ -2080,34 +2244,13 @@ var AffiliatesClient = class {
   /**
    * Get affiliate commission history.
    * Requires customer session token.
-   *
-   * @example
-   * ```typescript
-   * const { commissions, total } = await stackbe.affiliates.getCommissions();
-   *
-   * commissions.forEach((c) => {
-   *   console.log(`$${(c.amount / 100).toFixed(2)} - ${c.status}`);
-   * });
-   * ```
    */
   async getCommissions() {
     return this.http.get("/v1/affiliate/commissions");
   }
   /**
    * Track a referral click (store token for attribution).
-   * Call this when a user lands on your site with a referral code.
    * Requires API key.
-   *
-   * @example
-   * ```typescript
-   * // In your landing page handler
-   * const refCode = req.query.ref;
-   * if (refCode) {
-   *   const { token, expiresInDays } = await stackbe.affiliates.trackReferral(refCode);
-   *   // Store token in cookie for attribution on signup
-   *   res.cookie('ref_token', token, { maxAge: expiresInDays * 24 * 60 * 60 * 1000 });
-   * }
-   * ```
    */
   async trackReferral(code, referralUrl) {
     return this.http.post("/v1/affiliate/track", {
@@ -2115,6 +2258,44 @@ var AffiliatesClient = class {
       referralUrl
     });
   }
+  /**
+   * Get the full partner dashboard with stats, earnings by source, deals, and coupons.
+   * Requires customer session token.
+   *
+   * @example
+   * ```typescript
+   * const dashboard = await stackbe.affiliates.getDashboard();
+   * console.log(`Link earnings: $${dashboard.earningsBySource.link}`);
+   * console.log(`Coupon earnings: $${dashboard.earningsBySource.coupon}`);
+   * console.log(`Deal earnings: $${dashboard.earningsBySource.deal}`);
+   * ```
+   */
+  async getDashboard() {
+    return this.http.get("/v1/affiliate/dashboard");
+  }
+  /**
+   * Register a deal (lead attribution).
+   * Requires customer session token and active partner enrollment.
+   *
+   * @example
+   * ```typescript
+   * const deal = await stackbe.affiliates.registerDeal({
+   *   leadEmail: 'prospect@company.com',
+   *   leadName: 'John Smith',
+   *   notes: 'Met at conference, interested in Pro plan',
+   * });
+   * ```
+   */
+  async registerDeal(options) {
+    return this.http.post("/v1/affiliate/deals", options);
+  }
+  /**
+   * List the current partner's deal registrations.
+   * Requires customer session token.
+   */
+  async listDeals() {
+    return this.http.get("/v1/affiliate/deals");
+  }
 };
 
 // src/early-access.ts
@@ -2525,6 +2706,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 +2861,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.15.0",
   "description": "Official JavaScript/TypeScript SDK for StackBE - the billing backend for your side project",
   "main": "dist/index.js",
   "module": "dist/index.mjs",