@stackbe/sdk 0.8.4 → 0.8.6

package/dist/index.d.mts

@@ -720,6 +720,63 @@ declare class EntitlementsClient {
     require(customerId: string, feature: string): Promise<void>;
 }
 
+interface CustomerSubscriptionHistory {
+    id: string;
+    status: string;
+    planId: string;
+    planName?: string;
+    priceCents?: number;
+    currency?: string;
+    interval?: string;
+    currentPeriodStart?: string;
+    currentPeriodEnd?: string;
+    cancelAtPeriodEnd: boolean;
+    pausedAt?: string | null;
+    resumesAt?: string | null;
+    createdAt: string;
+}
+interface CustomerSubscriptionHistoryResponse {
+    subscriptions: CustomerSubscriptionHistory[];
+    total: number;
+}
+interface CustomerInvoice {
+    id: string;
+    number?: string;
+    status?: string;
+    amountPaid: number;
+    amountDue: number;
+    currency: string;
+    created: string;
+    periodStart?: string;
+    periodEnd?: string;
+    invoiceUrl?: string;
+    invoicePdf?: string;
+}
+interface CustomerInvoicesResponse {
+    invoices: CustomerInvoice[];
+    hasMore: boolean;
+}
+interface CustomerPaymentMethod {
+    hasPaymentMethod: boolean;
+    card: {
+        brand: string;
+        last4: string;
+        expMonth: number;
+        expYear: number;
+    } | null;
+}
+interface BillingPortalSession {
+    url: string;
+}
+interface UpcomingInvoice {
+    amountDue: number;
+    currency: string;
+    dueDate: string | null;
+    lines: Array<{
+        description: string;
+        amount: number;
+    }>;
+}
 declare class CustomersClient {
     private http;
     private appId;
@@ -814,6 +871,84 @@ declare class CustomersClient {
      * ```
      */
     getSession(token: string): Promise<SessionResponse>;
+    /**
+     * Get a customer's subscription history (all subscriptions, including past).
+     *
+     * @example
+     * ```typescript
+     * const { subscriptions, total } = await stackbe.customers.getSubscriptionHistory('cust_123');
+     *
+     * subscriptions.forEach(sub => {
+     *   console.log(`${sub.planName} - ${sub.status} (${sub.createdAt})`);
+     * });
+     * ```
+     */
+    getSubscriptionHistory(customerId: string): Promise<CustomerSubscriptionHistoryResponse>;
+    /**
+     * Get a customer's invoice/payment history from Stripe.
+     *
+     * @example
+     * ```typescript
+     * const { invoices, hasMore } = await stackbe.customers.getInvoices('cust_123');
+     *
+     * invoices.forEach(inv => {
+     *   console.log(`Invoice ${inv.number}: $${inv.amountPaid} - ${inv.status}`);
+     *   console.log(`PDF: ${inv.invoicePdf}`);
+     * });
+     * ```
+     */
+    getInvoices(customerId: string, options?: {
+        limit?: number;
+    }): Promise<CustomerInvoicesResponse>;
+    /**
+     * Get the customer's saved payment method (card) from Stripe.
+     *
+     * @example
+     * ```typescript
+     * const paymentMethod = await stackbe.customers.getPaymentMethod('cust_123');
+     *
+     * if (paymentMethod.hasPaymentMethod && paymentMethod.card) {
+     *   console.log(`${paymentMethod.card.brand} ending in ${paymentMethod.card.last4}`);
+     *   console.log(`Expires: ${paymentMethod.card.expMonth}/${paymentMethod.card.expYear}`);
+     * }
+     * ```
+     */
+    getPaymentMethod(customerId: string): Promise<CustomerPaymentMethod>;
+    /**
+     * Create a Stripe billing portal session for the customer.
+     * Redirect the customer to the returned URL to let them manage their billing.
+     *
+     * @example
+     * ```typescript
+     * const { url } = await stackbe.customers.createBillingPortalSession('cust_123', {
+     *   returnUrl: 'https://myapp.com/account'
+     * });
+     *
+     * // Redirect customer to Stripe billing portal
+     * window.location.href = url;
+     * ```
+     */
+    createBillingPortalSession(customerId: string, options?: {
+        returnUrl?: string;
+    }): Promise<BillingPortalSession>;
+    /**
+     * Get the customer's upcoming invoice preview (next charge).
+     * Returns null if the customer has no active subscription.
+     *
+     * @example
+     * ```typescript
+     * const upcoming = await stackbe.customers.getUpcomingInvoice('cust_123');
+     *
+     * if (upcoming) {
+     *   console.log(`Next charge: $${upcoming.amountDue} ${upcoming.currency}`);
+     *   console.log(`Due: ${upcoming.dueDate}`);
+     *   upcoming.lines.forEach(line => {
+     *     console.log(`  ${line.description}: $${line.amount}`);
+     *   });
+     * }
+     * ```
+     */
+    getUpcomingInvoice(customerId: string): Promise<UpcomingInvoice | null>;
 }
 
 declare class CheckoutClient {
@@ -2081,4 +2216,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, type AnyWebhookEvent, AuthClient, type CancelSubscriptionOptions, type CancelSubscriptionResponse, type CheckEntitlementResponse, type CheckUsageResponse, CheckoutClient, type CheckoutSessionResponse, type CreateCheckoutOptions, type CreateCustomerOptions, type CreateEarlyAccessSignupOptions, type CreateFeatureRequestOptions, type CreateOrganizationOptions, type Customer, type CustomerCreatedEvent, type CustomerFeatureActivity, type CustomerUpdatedEvent, type CustomerUsageResponse, type CustomerWebhookPayload, type CustomerWithSubscription, CustomersClient, EarlyAccessClient, type EarlyAccessSignup, type EarlyAccessSignupListResponse, type EnrollOptions, EntitlementsClient, type EntitlementsResponse, type FeatureRequest, type FeatureRequestComment, type FeatureRequestImage, type FeatureRequestListResponse, FeatureRequestsClient, type GetSubscriptionOptions, type InterestedCustomer, type InterestedCustomersResponse, type InviteMemberOptions, type ListEarlyAccessOptions, type ListFeatureRequestsOptions, type ListPlansOptions, type ListProductsOptions, type MagicLinkOptions, type MagicLinkResponse, type Organization, type OrganizationInvite, type OrganizationMember, OrganizationsClient, type PaymentFailedEvent, type PaymentSucceededEvent, type PaymentWebhookPayload, type Plan, PlansClient, type Product, ProductsClient, 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 TrackReferralResponse, type TrackUsageOptions, type TrackUsageResponse, type TrialEndedEvent, type TrialStartedEvent, type UpdateCustomerOptions, type UpdateOrganizationOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type VerifyTokenResponse, type WebhookEvent, type WebhookEventType };
+export { type AddMemberOptions, type AffiliateCommission, type AffiliateCommissionsResponse, type AffiliateEnrollment, type AffiliateInfo, type AffiliateStats, AffiliatesClient, type AnyWebhookEvent, AuthClient, type BillingPortalSession, type CancelSubscriptionOptions, type CancelSubscriptionResponse, type CheckEntitlementResponse, type CheckUsageResponse, CheckoutClient, type CheckoutSessionResponse, type CreateCheckoutOptions, 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, EarlyAccessClient, type EarlyAccessSignup, type EarlyAccessSignupListResponse, type EnrollOptions, EntitlementsClient, type EntitlementsResponse, type FeatureRequest, type FeatureRequestComment, type FeatureRequestImage, type FeatureRequestListResponse, FeatureRequestsClient, type GetSubscriptionOptions, type InterestedCustomer, type InterestedCustomersResponse, type InviteMemberOptions, type ListEarlyAccessOptions, type ListFeatureRequestsOptions, type ListPlansOptions, type ListProductsOptions, type MagicLinkOptions, type MagicLinkResponse, type Organization, type OrganizationInvite, type OrganizationMember, OrganizationsClient, type PaymentFailedEvent, type PaymentSucceededEvent, type PaymentWebhookPayload, type Plan, PlansClient, type Product, ProductsClient, 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 TrackReferralResponse, type TrackUsageOptions, type TrackUsageResponse, type TrialEndedEvent, type TrialStartedEvent, type UpcomingInvoice, type UpdateCustomerOptions, type UpdateOrganizationOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type VerifyTokenResponse, type WebhookEvent, type WebhookEventType };

package/dist/index.d.ts

@@ -720,6 +720,63 @@ declare class EntitlementsClient {
     require(customerId: string, feature: string): Promise<void>;
 }
 
+interface CustomerSubscriptionHistory {
+    id: string;
+    status: string;
+    planId: string;
+    planName?: string;
+    priceCents?: number;
+    currency?: string;
+    interval?: string;
+    currentPeriodStart?: string;
+    currentPeriodEnd?: string;
+    cancelAtPeriodEnd: boolean;
+    pausedAt?: string | null;
+    resumesAt?: string | null;
+    createdAt: string;
+}
+interface CustomerSubscriptionHistoryResponse {
+    subscriptions: CustomerSubscriptionHistory[];
+    total: number;
+}
+interface CustomerInvoice {
+    id: string;
+    number?: string;
+    status?: string;
+    amountPaid: number;
+    amountDue: number;
+    currency: string;
+    created: string;
+    periodStart?: string;
+    periodEnd?: string;
+    invoiceUrl?: string;
+    invoicePdf?: string;
+}
+interface CustomerInvoicesResponse {
+    invoices: CustomerInvoice[];
+    hasMore: boolean;
+}
+interface CustomerPaymentMethod {
+    hasPaymentMethod: boolean;
+    card: {
+        brand: string;
+        last4: string;
+        expMonth: number;
+        expYear: number;
+    } | null;
+}
+interface BillingPortalSession {
+    url: string;
+}
+interface UpcomingInvoice {
+    amountDue: number;
+    currency: string;
+    dueDate: string | null;
+    lines: Array<{
+        description: string;
+        amount: number;
+    }>;
+}
 declare class CustomersClient {
     private http;
     private appId;
@@ -814,6 +871,84 @@ declare class CustomersClient {
      * ```
      */
     getSession(token: string): Promise<SessionResponse>;
+    /**
+     * Get a customer's subscription history (all subscriptions, including past).
+     *
+     * @example
+     * ```typescript
+     * const { subscriptions, total } = await stackbe.customers.getSubscriptionHistory('cust_123');
+     *
+     * subscriptions.forEach(sub => {
+     *   console.log(`${sub.planName} - ${sub.status} (${sub.createdAt})`);
+     * });
+     * ```
+     */
+    getSubscriptionHistory(customerId: string): Promise<CustomerSubscriptionHistoryResponse>;
+    /**
+     * Get a customer's invoice/payment history from Stripe.
+     *
+     * @example
+     * ```typescript
+     * const { invoices, hasMore } = await stackbe.customers.getInvoices('cust_123');
+     *
+     * invoices.forEach(inv => {
+     *   console.log(`Invoice ${inv.number}: $${inv.amountPaid} - ${inv.status}`);
+     *   console.log(`PDF: ${inv.invoicePdf}`);
+     * });
+     * ```
+     */
+    getInvoices(customerId: string, options?: {
+        limit?: number;
+    }): Promise<CustomerInvoicesResponse>;
+    /**
+     * Get the customer's saved payment method (card) from Stripe.
+     *
+     * @example
+     * ```typescript
+     * const paymentMethod = await stackbe.customers.getPaymentMethod('cust_123');
+     *
+     * if (paymentMethod.hasPaymentMethod && paymentMethod.card) {
+     *   console.log(`${paymentMethod.card.brand} ending in ${paymentMethod.card.last4}`);
+     *   console.log(`Expires: ${paymentMethod.card.expMonth}/${paymentMethod.card.expYear}`);
+     * }
+     * ```
+     */
+    getPaymentMethod(customerId: string): Promise<CustomerPaymentMethod>;
+    /**
+     * Create a Stripe billing portal session for the customer.
+     * Redirect the customer to the returned URL to let them manage their billing.
+     *
+     * @example
+     * ```typescript
+     * const { url } = await stackbe.customers.createBillingPortalSession('cust_123', {
+     *   returnUrl: 'https://myapp.com/account'
+     * });
+     *
+     * // Redirect customer to Stripe billing portal
+     * window.location.href = url;
+     * ```
+     */
+    createBillingPortalSession(customerId: string, options?: {
+        returnUrl?: string;
+    }): Promise<BillingPortalSession>;
+    /**
+     * Get the customer's upcoming invoice preview (next charge).
+     * Returns null if the customer has no active subscription.
+     *
+     * @example
+     * ```typescript
+     * const upcoming = await stackbe.customers.getUpcomingInvoice('cust_123');
+     *
+     * if (upcoming) {
+     *   console.log(`Next charge: $${upcoming.amountDue} ${upcoming.currency}`);
+     *   console.log(`Due: ${upcoming.dueDate}`);
+     *   upcoming.lines.forEach(line => {
+     *     console.log(`  ${line.description}: $${line.amount}`);
+     *   });
+     * }
+     * ```
+     */
+    getUpcomingInvoice(customerId: string): Promise<UpcomingInvoice | null>;
 }
 
 declare class CheckoutClient {
@@ -2081,4 +2216,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, type AnyWebhookEvent, AuthClient, type CancelSubscriptionOptions, type CancelSubscriptionResponse, type CheckEntitlementResponse, type CheckUsageResponse, CheckoutClient, type CheckoutSessionResponse, type CreateCheckoutOptions, type CreateCustomerOptions, type CreateEarlyAccessSignupOptions, type CreateFeatureRequestOptions, type CreateOrganizationOptions, type Customer, type CustomerCreatedEvent, type CustomerFeatureActivity, type CustomerUpdatedEvent, type CustomerUsageResponse, type CustomerWebhookPayload, type CustomerWithSubscription, CustomersClient, EarlyAccessClient, type EarlyAccessSignup, type EarlyAccessSignupListResponse, type EnrollOptions, EntitlementsClient, type EntitlementsResponse, type FeatureRequest, type FeatureRequestComment, type FeatureRequestImage, type FeatureRequestListResponse, FeatureRequestsClient, type GetSubscriptionOptions, type InterestedCustomer, type InterestedCustomersResponse, type InviteMemberOptions, type ListEarlyAccessOptions, type ListFeatureRequestsOptions, type ListPlansOptions, type ListProductsOptions, type MagicLinkOptions, type MagicLinkResponse, type Organization, type OrganizationInvite, type OrganizationMember, OrganizationsClient, type PaymentFailedEvent, type PaymentSucceededEvent, type PaymentWebhookPayload, type Plan, PlansClient, type Product, ProductsClient, 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 TrackReferralResponse, type TrackUsageOptions, type TrackUsageResponse, type TrialEndedEvent, type TrialStartedEvent, type UpdateCustomerOptions, type UpdateOrganizationOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type VerifyTokenResponse, type WebhookEvent, type WebhookEventType };
+export { type AddMemberOptions, type AffiliateCommission, type AffiliateCommissionsResponse, type AffiliateEnrollment, type AffiliateInfo, type AffiliateStats, AffiliatesClient, type AnyWebhookEvent, AuthClient, type BillingPortalSession, type CancelSubscriptionOptions, type CancelSubscriptionResponse, type CheckEntitlementResponse, type CheckUsageResponse, CheckoutClient, type CheckoutSessionResponse, type CreateCheckoutOptions, 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, EarlyAccessClient, type EarlyAccessSignup, type EarlyAccessSignupListResponse, type EnrollOptions, EntitlementsClient, type EntitlementsResponse, type FeatureRequest, type FeatureRequestComment, type FeatureRequestImage, type FeatureRequestListResponse, FeatureRequestsClient, type GetSubscriptionOptions, type InterestedCustomer, type InterestedCustomersResponse, type InviteMemberOptions, type ListEarlyAccessOptions, type ListFeatureRequestsOptions, type ListPlansOptions, type ListProductsOptions, type MagicLinkOptions, type MagicLinkResponse, type Organization, type OrganizationInvite, type OrganizationMember, OrganizationsClient, type PaymentFailedEvent, type PaymentSucceededEvent, type PaymentWebhookPayload, type Plan, PlansClient, type Product, ProductsClient, 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 TrackReferralResponse, type TrackUsageOptions, type TrackUsageResponse, type TrialEndedEvent, type TrialStartedEvent, type UpcomingInvoice, type UpdateCustomerOptions, type UpdateOrganizationOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type VerifyTokenResponse, type WebhookEvent, type WebhookEventType };

package/dist/index.js

@@ -612,6 +612,106 @@ var CustomersClient = class {
     }
     return response.json();
   }
+  // ==================== Billing History ====================
+  /**
+   * Get a customer's subscription history (all subscriptions, including past).
+   *
+   * @example
+   * ```typescript
+   * const { subscriptions, total } = await stackbe.customers.getSubscriptionHistory('cust_123');
+   *
+   * subscriptions.forEach(sub => {
+   *   console.log(`${sub.planName} - ${sub.status} (${sub.createdAt})`);
+   * });
+   * ```
+   */
+  async getSubscriptionHistory(customerId) {
+    return this.http.get(
+      `/v1/apps/${this.appId}/customers/${customerId}/subscriptions`
+    );
+  }
+  /**
+   * Get a customer's invoice/payment history from Stripe.
+   *
+   * @example
+   * ```typescript
+   * const { invoices, hasMore } = await stackbe.customers.getInvoices('cust_123');
+   *
+   * invoices.forEach(inv => {
+   *   console.log(`Invoice ${inv.number}: $${inv.amountPaid} - ${inv.status}`);
+   *   console.log(`PDF: ${inv.invoicePdf}`);
+   * });
+   * ```
+   */
+  async getInvoices(customerId, options) {
+    const params = {};
+    if (options?.limit) params.limit = options.limit;
+    return this.http.get(
+      `/v1/apps/${this.appId}/customers/${customerId}/invoices`,
+      params
+    );
+  }
+  // ==================== Billing Self-Service ====================
+  /**
+   * Get the customer's saved payment method (card) from Stripe.
+   *
+   * @example
+   * ```typescript
+   * const paymentMethod = await stackbe.customers.getPaymentMethod('cust_123');
+   *
+   * if (paymentMethod.hasPaymentMethod && paymentMethod.card) {
+   *   console.log(`${paymentMethod.card.brand} ending in ${paymentMethod.card.last4}`);
+   *   console.log(`Expires: ${paymentMethod.card.expMonth}/${paymentMethod.card.expYear}`);
+   * }
+   * ```
+   */
+  async getPaymentMethod(customerId) {
+    return this.http.get(
+      `/v1/apps/${this.appId}/customers/${customerId}/payment-method`
+    );
+  }
+  /**
+   * Create a Stripe billing portal session for the customer.
+   * Redirect the customer to the returned URL to let them manage their billing.
+   *
+   * @example
+   * ```typescript
+   * const { url } = await stackbe.customers.createBillingPortalSession('cust_123', {
+   *   returnUrl: 'https://myapp.com/account'
+   * });
+   *
+   * // Redirect customer to Stripe billing portal
+   * window.location.href = url;
+   * ```
+   */
+  async createBillingPortalSession(customerId, options) {
+    return this.http.post(
+      `/v1/apps/${this.appId}/customers/${customerId}/billing-portal`,
+      { returnUrl: options?.returnUrl }
+    );
+  }
+  /**
+   * Get the customer's upcoming invoice preview (next charge).
+   * Returns null if the customer has no active subscription.
+   *
+   * @example
+   * ```typescript
+   * const upcoming = await stackbe.customers.getUpcomingInvoice('cust_123');
+   *
+   * if (upcoming) {
+   *   console.log(`Next charge: $${upcoming.amountDue} ${upcoming.currency}`);
+   *   console.log(`Due: ${upcoming.dueDate}`);
+   *   upcoming.lines.forEach(line => {
+   *     console.log(`  ${line.description}: $${line.amount}`);
+   *   });
+   * }
+   * ```
+   */
+  async getUpcomingInvoice(customerId) {
+    return this.http.get(
+      `/v1/apps/${this.appId}/customers/${customerId}/upcoming-invoice`
+    );
+  }
 };
 
 // src/checkout.ts

package/dist/index.mjs

@@ -573,6 +573,106 @@ var CustomersClient = class {
     }
     return response.json();
   }
+  // ==================== Billing History ====================
+  /**
+   * Get a customer's subscription history (all subscriptions, including past).
+   *
+   * @example
+   * ```typescript
+   * const { subscriptions, total } = await stackbe.customers.getSubscriptionHistory('cust_123');
+   *
+   * subscriptions.forEach(sub => {
+   *   console.log(`${sub.planName} - ${sub.status} (${sub.createdAt})`);
+   * });
+   * ```
+   */
+  async getSubscriptionHistory(customerId) {
+    return this.http.get(
+      `/v1/apps/${this.appId}/customers/${customerId}/subscriptions`
+    );
+  }
+  /**
+   * Get a customer's invoice/payment history from Stripe.
+   *
+   * @example
+   * ```typescript
+   * const { invoices, hasMore } = await stackbe.customers.getInvoices('cust_123');
+   *
+   * invoices.forEach(inv => {
+   *   console.log(`Invoice ${inv.number}: $${inv.amountPaid} - ${inv.status}`);
+   *   console.log(`PDF: ${inv.invoicePdf}`);
+   * });
+   * ```
+   */
+  async getInvoices(customerId, options) {
+    const params = {};
+    if (options?.limit) params.limit = options.limit;
+    return this.http.get(
+      `/v1/apps/${this.appId}/customers/${customerId}/invoices`,
+      params
+    );
+  }
+  // ==================== Billing Self-Service ====================
+  /**
+   * Get the customer's saved payment method (card) from Stripe.
+   *
+   * @example
+   * ```typescript
+   * const paymentMethod = await stackbe.customers.getPaymentMethod('cust_123');
+   *
+   * if (paymentMethod.hasPaymentMethod && paymentMethod.card) {
+   *   console.log(`${paymentMethod.card.brand} ending in ${paymentMethod.card.last4}`);
+   *   console.log(`Expires: ${paymentMethod.card.expMonth}/${paymentMethod.card.expYear}`);
+   * }
+   * ```
+   */
+  async getPaymentMethod(customerId) {
+    return this.http.get(
+      `/v1/apps/${this.appId}/customers/${customerId}/payment-method`
+    );
+  }
+  /**
+   * Create a Stripe billing portal session for the customer.
+   * Redirect the customer to the returned URL to let them manage their billing.
+   *
+   * @example
+   * ```typescript
+   * const { url } = await stackbe.customers.createBillingPortalSession('cust_123', {
+   *   returnUrl: 'https://myapp.com/account'
+   * });
+   *
+   * // Redirect customer to Stripe billing portal
+   * window.location.href = url;
+   * ```
+   */
+  async createBillingPortalSession(customerId, options) {
+    return this.http.post(
+      `/v1/apps/${this.appId}/customers/${customerId}/billing-portal`,
+      { returnUrl: options?.returnUrl }
+    );
+  }
+  /**
+   * Get the customer's upcoming invoice preview (next charge).
+   * Returns null if the customer has no active subscription.
+   *
+   * @example
+   * ```typescript
+   * const upcoming = await stackbe.customers.getUpcomingInvoice('cust_123');
+   *
+   * if (upcoming) {
+   *   console.log(`Next charge: $${upcoming.amountDue} ${upcoming.currency}`);
+   *   console.log(`Due: ${upcoming.dueDate}`);
+   *   upcoming.lines.forEach(line => {
+   *     console.log(`  ${line.description}: $${line.amount}`);
+   *   });
+   * }
+   * ```
+   */
+  async getUpcomingInvoice(customerId) {
+    return this.http.get(
+      `/v1/apps/${this.appId}/customers/${customerId}/upcoming-invoice`
+    );
+  }
 };
 
 // src/checkout.ts

package/package.json

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