@stackbe/sdk 0.8.5 → 0.9.0

package/dist/index.d.mts

@@ -353,6 +353,8 @@ interface CreateCheckoutOptions {
     cancelUrl?: string;
     /** Organization ID for org-level subscriptions. Customer must be owner/admin of the org. */
     organizationId?: string;
+    /** Coupon/promo code to apply (e.g., "SAVE20") */
+    couponCode?: string;
     /** Allow promotion codes */
     allowPromotionCodes?: boolean;
     /** Trial period in days */
@@ -756,6 +758,27 @@ 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;
@@ -879,6 +902,55 @@ declare class CustomersClient {
     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 {
@@ -2019,6 +2091,137 @@ declare class EarlyAccessClient {
     updateStatus(signupId: string, status: 'new' | 'invited' | 'converted' | 'archived'): Promise<EarlyAccessSignup>;
 }
 
+type CouponDiscountType = 'percentage' | 'fixed_amount';
+interface Coupon {
+    id: string;
+    code: string;
+    name?: string;
+    discountType: CouponDiscountType;
+    discountValue: number;
+    currency?: string;
+    maxRedemptions?: number;
+    timesRedeemed: number;
+    expiresAt?: string;
+    validPlanIds: string[];
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateCouponOptions {
+    /** Coupon code (alphanumeric, will be uppercased) */
+    code: string;
+    /** Internal name for dashboard */
+    name?: string;
+    /** Type of discount */
+    discountType: CouponDiscountType;
+    /** Discount value (percentage 1-100, or cents for fixed_amount) */
+    discountValue: number;
+    /** Currency code (required for fixed_amount) */
+    currency?: string;
+    /** Maximum number of times this coupon can be used */
+    maxRedemptions?: number;
+    /** When the coupon expires (ISO date string) */
+    expiresAt?: string;
+    /** Restrict to specific plan IDs (empty = valid for all plans) */
+    validPlanIds?: string[];
+    /** Whether the coupon is active */
+    active?: boolean;
+}
+interface UpdateCouponOptions {
+    name?: string;
+    maxRedemptions?: number;
+    expiresAt?: string;
+    validPlanIds?: string[];
+    active?: boolean;
+}
+interface ValidateCouponResult {
+    valid: boolean;
+    coupon?: {
+        id: string;
+        code: string;
+        discountType: CouponDiscountType;
+        discountValue: number;
+        currency?: string;
+    };
+    error?: string;
+}
+declare class CouponsClient {
+    private http;
+    private appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Create a new coupon/promo code.
+     *
+     * @example
+     * ```typescript
+     * const coupon = await stackbe.coupons.create({
+     *   code: 'SAVE20',
+     *   discountType: 'percentage',
+     *   discountValue: 20,
+     *   maxRedemptions: 100,
+     *   expiresAt: '2026-12-31T23:59:59Z',
+     * });
+     * ```
+     */
+    create(options: CreateCouponOptions): Promise<Coupon>;
+    /**
+     * List all coupons for your app.
+     *
+     * @example
+     * ```typescript
+     * const coupons = await stackbe.coupons.list();
+     * const activeCoupons = await stackbe.coupons.list({ active: true });
+     * ```
+     */
+    list(options?: {
+        active?: boolean;
+    }): Promise<Coupon[]>;
+    /**
+     * Get a specific coupon by ID.
+     *
+     * @example
+     * ```typescript
+     * const coupon = await stackbe.coupons.get('coupon_abc123');
+     * ```
+     */
+    get(couponId: string): Promise<Coupon>;
+    /**
+     * Validate a coupon code before checkout.
+     *
+     * @example
+     * ```typescript
+     * const result = await stackbe.coupons.validate('SAVE20', 'plan_pro');
+     *
+     * if (result.valid) {
+     *   console.log(`${result.coupon.discountValue}% off!`);
+     * } else {
+     *   console.log(result.error); // "Coupon has expired"
+     * }
+     * ```
+     */
+    validate(code: string, planId?: string): Promise<ValidateCouponResult>;
+    /**
+     * Update a coupon.
+     *
+     * @example
+     * ```typescript
+     * const coupon = await stackbe.coupons.update('coupon_abc123', {
+     *   active: false,
+     * });
+     * ```
+     */
+    update(couponId: string, options: UpdateCouponOptions): Promise<Coupon>;
+    /**
+     * Delete a coupon.
+     *
+     * @example
+     * ```typescript
+     * await stackbe.coupons.delete('coupon_abc123');
+     * ```
+     */
+    delete(couponId: string): Promise<void>;
+}
+
 declare class StackBE {
     private http;
     private appId;
@@ -2046,6 +2249,8 @@ declare class StackBE {
     readonly affiliates: AffiliatesClient;
     /** Early access / waitlist signups */
     readonly earlyAccess: EarlyAccessClient;
+    /** Coupon/promo code management */
+    readonly coupons: CouponsClient;
     /**
      * Create a new StackBE client.
      *
@@ -2146,4 +2351,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 CustomerInvoice, type CustomerInvoicesResponse, 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 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 Coupon, type CouponDiscountType, 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, 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 UpdateCouponOptions, type UpdateCustomerOptions, type UpdateOrganizationOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type ValidateCouponResult, type VerifyTokenResponse, type WebhookEvent, type WebhookEventType };

package/dist/index.d.ts

@@ -353,6 +353,8 @@ interface CreateCheckoutOptions {
     cancelUrl?: string;
     /** Organization ID for org-level subscriptions. Customer must be owner/admin of the org. */
     organizationId?: string;
+    /** Coupon/promo code to apply (e.g., "SAVE20") */
+    couponCode?: string;
     /** Allow promotion codes */
     allowPromotionCodes?: boolean;
     /** Trial period in days */
@@ -756,6 +758,27 @@ 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;
@@ -879,6 +902,55 @@ declare class CustomersClient {
     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 {
@@ -2019,6 +2091,137 @@ declare class EarlyAccessClient {
     updateStatus(signupId: string, status: 'new' | 'invited' | 'converted' | 'archived'): Promise<EarlyAccessSignup>;
 }
 
+type CouponDiscountType = 'percentage' | 'fixed_amount';
+interface Coupon {
+    id: string;
+    code: string;
+    name?: string;
+    discountType: CouponDiscountType;
+    discountValue: number;
+    currency?: string;
+    maxRedemptions?: number;
+    timesRedeemed: number;
+    expiresAt?: string;
+    validPlanIds: string[];
+    active: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+interface CreateCouponOptions {
+    /** Coupon code (alphanumeric, will be uppercased) */
+    code: string;
+    /** Internal name for dashboard */
+    name?: string;
+    /** Type of discount */
+    discountType: CouponDiscountType;
+    /** Discount value (percentage 1-100, or cents for fixed_amount) */
+    discountValue: number;
+    /** Currency code (required for fixed_amount) */
+    currency?: string;
+    /** Maximum number of times this coupon can be used */
+    maxRedemptions?: number;
+    /** When the coupon expires (ISO date string) */
+    expiresAt?: string;
+    /** Restrict to specific plan IDs (empty = valid for all plans) */
+    validPlanIds?: string[];
+    /** Whether the coupon is active */
+    active?: boolean;
+}
+interface UpdateCouponOptions {
+    name?: string;
+    maxRedemptions?: number;
+    expiresAt?: string;
+    validPlanIds?: string[];
+    active?: boolean;
+}
+interface ValidateCouponResult {
+    valid: boolean;
+    coupon?: {
+        id: string;
+        code: string;
+        discountType: CouponDiscountType;
+        discountValue: number;
+        currency?: string;
+    };
+    error?: string;
+}
+declare class CouponsClient {
+    private http;
+    private appId;
+    constructor(http: HttpClient, appId: string);
+    /**
+     * Create a new coupon/promo code.
+     *
+     * @example
+     * ```typescript
+     * const coupon = await stackbe.coupons.create({
+     *   code: 'SAVE20',
+     *   discountType: 'percentage',
+     *   discountValue: 20,
+     *   maxRedemptions: 100,
+     *   expiresAt: '2026-12-31T23:59:59Z',
+     * });
+     * ```
+     */
+    create(options: CreateCouponOptions): Promise<Coupon>;
+    /**
+     * List all coupons for your app.
+     *
+     * @example
+     * ```typescript
+     * const coupons = await stackbe.coupons.list();
+     * const activeCoupons = await stackbe.coupons.list({ active: true });
+     * ```
+     */
+    list(options?: {
+        active?: boolean;
+    }): Promise<Coupon[]>;
+    /**
+     * Get a specific coupon by ID.
+     *
+     * @example
+     * ```typescript
+     * const coupon = await stackbe.coupons.get('coupon_abc123');
+     * ```
+     */
+    get(couponId: string): Promise<Coupon>;
+    /**
+     * Validate a coupon code before checkout.
+     *
+     * @example
+     * ```typescript
+     * const result = await stackbe.coupons.validate('SAVE20', 'plan_pro');
+     *
+     * if (result.valid) {
+     *   console.log(`${result.coupon.discountValue}% off!`);
+     * } else {
+     *   console.log(result.error); // "Coupon has expired"
+     * }
+     * ```
+     */
+    validate(code: string, planId?: string): Promise<ValidateCouponResult>;
+    /**
+     * Update a coupon.
+     *
+     * @example
+     * ```typescript
+     * const coupon = await stackbe.coupons.update('coupon_abc123', {
+     *   active: false,
+     * });
+     * ```
+     */
+    update(couponId: string, options: UpdateCouponOptions): Promise<Coupon>;
+    /**
+     * Delete a coupon.
+     *
+     * @example
+     * ```typescript
+     * await stackbe.coupons.delete('coupon_abc123');
+     * ```
+     */
+    delete(couponId: string): Promise<void>;
+}
+
 declare class StackBE {
     private http;
     private appId;
@@ -2046,6 +2249,8 @@ declare class StackBE {
     readonly affiliates: AffiliatesClient;
     /** Early access / waitlist signups */
     readonly earlyAccess: EarlyAccessClient;
+    /** Coupon/promo code management */
+    readonly coupons: CouponsClient;
     /**
      * Create a new StackBE client.
      *
@@ -2146,4 +2351,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 CustomerInvoice, type CustomerInvoicesResponse, 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 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 Coupon, type CouponDiscountType, 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, 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 UpdateCouponOptions, type UpdateCustomerOptions, type UpdateOrganizationOptions, type UpdateSubscriptionOptions, UsageClient, type UsageMetric, type ValidateCouponResult, type VerifyTokenResponse, type WebhookEvent, type WebhookEventType };

package/dist/index.js

@@ -23,6 +23,7 @@ __export(index_exports, {
   AffiliatesClient: () => AffiliatesClient,
   AuthClient: () => AuthClient,
   CheckoutClient: () => CheckoutClient,
+  CouponsClient: () => CouponsClient,
   CustomersClient: () => CustomersClient,
   EarlyAccessClient: () => EarlyAccessClient,
   EntitlementsClient: () => EntitlementsClient,
@@ -651,6 +652,67 @@ var CustomersClient = class {
       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
@@ -707,6 +769,7 @@ var CheckoutClient = class {
       successUrl: options.successUrl,
       cancelUrl: options.cancelUrl,
       organizationId: options.organizationId,
+      couponCode: options.couponCode,
       allowPromotionCodes: options.allowPromotionCodes,
       trialDays: options.trialDays,
       metadata: options.metadata
@@ -1978,6 +2041,102 @@ var EarlyAccessClient = class {
   }
 };
 
+// src/coupons.ts
+var CouponsClient = class {
+  constructor(http, appId) {
+    this.http = http;
+    this.appId = appId;
+  }
+  /**
+   * Create a new coupon/promo code.
+   *
+   * @example
+   * ```typescript
+   * const coupon = await stackbe.coupons.create({
+   *   code: 'SAVE20',
+   *   discountType: 'percentage',
+   *   discountValue: 20,
+   *   maxRedemptions: 100,
+   *   expiresAt: '2026-12-31T23:59:59Z',
+   * });
+   * ```
+   */
+  async create(options) {
+    return this.http.post(`/v1/apps/${this.appId}/coupons`, options);
+  }
+  /**
+   * List all coupons for your app.
+   *
+   * @example
+   * ```typescript
+   * const coupons = await stackbe.coupons.list();
+   * const activeCoupons = await stackbe.coupons.list({ active: true });
+   * ```
+   */
+  async list(options) {
+    const params = {};
+    if (options?.active !== void 0) {
+      params.active = String(options.active);
+    }
+    return this.http.get(`/v1/apps/${this.appId}/coupons`, params);
+  }
+  /**
+   * Get a specific coupon by ID.
+   *
+   * @example
+   * ```typescript
+   * const coupon = await stackbe.coupons.get('coupon_abc123');
+   * ```
+   */
+  async get(couponId) {
+    return this.http.get(`/v1/apps/${this.appId}/coupons/${couponId}`);
+  }
+  /**
+   * Validate a coupon code before checkout.
+   *
+   * @example
+   * ```typescript
+   * const result = await stackbe.coupons.validate('SAVE20', 'plan_pro');
+   *
+   * if (result.valid) {
+   *   console.log(`${result.coupon.discountValue}% off!`);
+   * } else {
+   *   console.log(result.error); // "Coupon has expired"
+   * }
+   * ```
+   */
+  async validate(code, planId) {
+    return this.http.post(`/v1/apps/${this.appId}/coupons/validate`, {
+      code,
+      planId
+    });
+  }
+  /**
+   * Update a coupon.
+   *
+   * @example
+   * ```typescript
+   * const coupon = await stackbe.coupons.update('coupon_abc123', {
+   *   active: false,
+   * });
+   * ```
+   */
+  async update(couponId, options) {
+    return this.http.patch(`/v1/apps/${this.appId}/coupons/${couponId}`, options);
+  }
+  /**
+   * Delete a coupon.
+   *
+   * @example
+   * ```typescript
+   * await stackbe.coupons.delete('coupon_abc123');
+   * ```
+   */
+  async delete(couponId) {
+    await this.http.delete(`/v1/apps/${this.appId}/coupons/${couponId}`);
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.stackbe.io";
 var DEFAULT_TIMEOUT = 3e4;
@@ -2043,6 +2202,7 @@ var StackBE = class {
     this.featureRequests = new FeatureRequestsClient(this.http, config.appId);
     this.affiliates = new AffiliatesClient(this.http);
     this.earlyAccess = new EarlyAccessClient(this.http, config.appId);
+    this.coupons = new CouponsClient(this.http, config.appId);
   }
   /**
    * Create a middleware for Express that tracks usage automatically.
@@ -2179,6 +2339,7 @@ var StackBE = class {
   AffiliatesClient,
   AuthClient,
   CheckoutClient,
+  CouponsClient,
   CustomersClient,
   EarlyAccessClient,
   EntitlementsClient,

package/dist/index.mjs

@@ -612,6 +612,67 @@ var CustomersClient = class {
       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
@@ -668,6 +729,7 @@ var CheckoutClient = class {
       successUrl: options.successUrl,
       cancelUrl: options.cancelUrl,
       organizationId: options.organizationId,
+      couponCode: options.couponCode,
       allowPromotionCodes: options.allowPromotionCodes,
       trialDays: options.trialDays,
       metadata: options.metadata
@@ -1939,6 +2001,102 @@ var EarlyAccessClient = class {
   }
 };
 
+// src/coupons.ts
+var CouponsClient = class {
+  constructor(http, appId) {
+    this.http = http;
+    this.appId = appId;
+  }
+  /**
+   * Create a new coupon/promo code.
+   *
+   * @example
+   * ```typescript
+   * const coupon = await stackbe.coupons.create({
+   *   code: 'SAVE20',
+   *   discountType: 'percentage',
+   *   discountValue: 20,
+   *   maxRedemptions: 100,
+   *   expiresAt: '2026-12-31T23:59:59Z',
+   * });
+   * ```
+   */
+  async create(options) {
+    return this.http.post(`/v1/apps/${this.appId}/coupons`, options);
+  }
+  /**
+   * List all coupons for your app.
+   *
+   * @example
+   * ```typescript
+   * const coupons = await stackbe.coupons.list();
+   * const activeCoupons = await stackbe.coupons.list({ active: true });
+   * ```
+   */
+  async list(options) {
+    const params = {};
+    if (options?.active !== void 0) {
+      params.active = String(options.active);
+    }
+    return this.http.get(`/v1/apps/${this.appId}/coupons`, params);
+  }
+  /**
+   * Get a specific coupon by ID.
+   *
+   * @example
+   * ```typescript
+   * const coupon = await stackbe.coupons.get('coupon_abc123');
+   * ```
+   */
+  async get(couponId) {
+    return this.http.get(`/v1/apps/${this.appId}/coupons/${couponId}`);
+  }
+  /**
+   * Validate a coupon code before checkout.
+   *
+   * @example
+   * ```typescript
+   * const result = await stackbe.coupons.validate('SAVE20', 'plan_pro');
+   *
+   * if (result.valid) {
+   *   console.log(`${result.coupon.discountValue}% off!`);
+   * } else {
+   *   console.log(result.error); // "Coupon has expired"
+   * }
+   * ```
+   */
+  async validate(code, planId) {
+    return this.http.post(`/v1/apps/${this.appId}/coupons/validate`, {
+      code,
+      planId
+    });
+  }
+  /**
+   * Update a coupon.
+   *
+   * @example
+   * ```typescript
+   * const coupon = await stackbe.coupons.update('coupon_abc123', {
+   *   active: false,
+   * });
+   * ```
+   */
+  async update(couponId, options) {
+    return this.http.patch(`/v1/apps/${this.appId}/coupons/${couponId}`, options);
+  }
+  /**
+   * Delete a coupon.
+   *
+   * @example
+   * ```typescript
+   * await stackbe.coupons.delete('coupon_abc123');
+   * ```
+   */
+  async delete(couponId) {
+    await this.http.delete(`/v1/apps/${this.appId}/coupons/${couponId}`);
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.stackbe.io";
 var DEFAULT_TIMEOUT = 3e4;
@@ -2004,6 +2162,7 @@ var StackBE = class {
     this.featureRequests = new FeatureRequestsClient(this.http, config.appId);
     this.affiliates = new AffiliatesClient(this.http);
     this.earlyAccess = new EarlyAccessClient(this.http, config.appId);
+    this.coupons = new CouponsClient(this.http, config.appId);
   }
   /**
    * Create a middleware for Express that tracks usage automatically.
@@ -2139,6 +2298,7 @@ export {
   AffiliatesClient,
   AuthClient,
   CheckoutClient,
+  CouponsClient,
   CustomersClient,
   EarlyAccessClient,
   EntitlementsClient,

package/package.json

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