@stackbe/sdk 0.9.3 → 0.9.5

package/dist/index.d.mts

@@ -184,12 +184,60 @@ interface Subscription {
     currentPeriodStart: string;
     currentPeriodEnd: string;
     cancelAtPeriodEnd: boolean;
+    /** When the trial started (null if no trial) */
+    trialStart?: string | null;
+    /** When the trial ends/ended (null if no trial) */
+    trialEnd?: string | null;
+    /** When trial converted to paid (null if not converted yet) */
+    trialConvertedAt?: string | null;
     /** When the subscription was paused (null if not paused) */
     pausedAt?: string | null;
     /** When the subscription will auto-resume (null = indefinite pause) */
     resumesAt?: string | null;
+    /** Number of consecutive failed payment attempts */
+    failedPaymentCount?: number;
+    /** Timestamp of most recent failed payment */
+    lastPaymentFailedAt?: string | null;
+    /** When access will be revoked if payment not recovered */
+    gracePeriodEndsAt?: string | null;
     createdAt: string;
 }
+interface TrialStatus {
+    /** Whether the subscription is currently in trial */
+    isTrialing: boolean;
+    /** When the trial started */
+    trialStart: string | null;
+    /** When the trial ends/ended */
+    trialEnd: string | null;
+    /** When the trial converted to paid (null if not converted) */
+    trialConvertedAt: string | null;
+    /** Days remaining in trial (null if not trialing) */
+    daysRemaining: number | null;
+    /** Whether the trial has converted to paid */
+    hasConverted: boolean;
+}
+interface DunningStatus {
+    /** Whether the subscription is past due */
+    isPastDue: boolean;
+    /** Whether the subscription is in grace period (past due but still has access) */
+    isInGracePeriod: boolean;
+    /** Number of consecutive failed payment attempts */
+    failedPaymentCount: number;
+    /** Timestamp of most recent failed payment */
+    lastPaymentFailedAt: string | null;
+    /** When access will be revoked if payment not recovered */
+    gracePeriodEndsAt: string | null;
+    /** Days until access is revoked (null if not in grace period) */
+    daysUntilAccessRevoked: number | null;
+    /** Days since payment failed */
+    daysSinceFailure: number | null;
+    /** Configured dunning email schedule (days after failure) */
+    dunningEmailSchedule: number[];
+    /** Which dunning emails have been sent (days) */
+    emailsSent: number[];
+    /** Whether the customer still has access (considering grace period) */
+    hasAccess: boolean;
+}
 interface CustomerWithSubscription extends Customer {
     subscription?: Subscription;
 }
@@ -1177,6 +1225,115 @@ declare class SubscriptionsClient {
      * ```
      */
     resume(subscriptionId: string): Promise<Subscription>;
+    /**
+     * Get trial status for a subscription.
+     *
+     * @example
+     * ```typescript
+     * const trial = await stackbe.subscriptions.getTrialStatus('sub_123');
+     *
+     * if (trial.isTrialing) {
+     *   console.log(`Trial ends in ${trial.daysRemaining} days`);
+     * }
+     *
+     * if (trial.hasConverted) {
+     *   console.log(`Converted to paid on ${trial.trialConvertedAt}`);
+     * }
+     * ```
+     */
+    getTrialStatus(subscriptionId: string): Promise<TrialStatus>;
+    /**
+     * Extend a trial by a number of days.
+     *
+     * Only works for subscriptions currently in trial.
+     *
+     * @example
+     * ```typescript
+     * // Give the customer 7 more days
+     * const subscription = await stackbe.subscriptions.extendTrial('sub_123', 7);
+     * console.log(`New trial end: ${subscription.trialEnd}`);
+     * ```
+     */
+    extendTrial(subscriptionId: string, days: number): Promise<Subscription>;
+    /**
+     * End trial immediately and convert to paid subscription.
+     *
+     * The customer will be charged right away.
+     *
+     * @example
+     * ```typescript
+     * // Customer wants to start paying immediately
+     * const subscription = await stackbe.subscriptions.endTrial('sub_123');
+     * console.log(`Converted at: ${subscription.trialConvertedAt}`);
+     * ```
+     */
+    endTrial(subscriptionId: string): Promise<Subscription>;
+    /**
+     * Get dunning/payment recovery status for a subscription.
+     *
+     * Shows if the subscription is past due, in grace period, and when access
+     * will be revoked if payment isn't recovered.
+     *
+     * @example
+     * ```typescript
+     * const dunning = await stackbe.subscriptions.getDunningStatus('sub_123');
+     *
+     * if (dunning.isPastDue) {
+     *   console.log(`Payment failed ${dunning.daysSinceFailure} days ago`);
+     *
+     *   if (dunning.isInGracePeriod) {
+     *     console.log(`Access ends in ${dunning.daysUntilAccessRevoked} days`);
+     *   }
+     * }
+     *
+     * // Check if customer still has access
+     * if (dunning.hasAccess) {
+     *   // Allow access
+     * }
+     * ```
+     */
+    getDunningStatus(subscriptionId: string): Promise<DunningStatus>;
+    /**
+     * List all past-due subscriptions.
+     *
+     * Useful for monitoring and recovery efforts.
+     *
+     * @example
+     * ```typescript
+     * // List all past-due subscriptions
+     * const pastDue = await stackbe.subscriptions.listPastDue();
+     *
+     * // List subscriptions losing access within 3 days
+     * const urgent = await stackbe.subscriptions.listPastDue({ gracePeriodExpiringSoon: 3 });
+     *
+     * for (const sub of urgent) {
+     *   console.log(`${sub.customer.email} loses access in ${sub.gracePeriodEndsAt}`);
+     * }
+     * ```
+     */
+    listPastDue(options?: {
+        appId?: string;
+        gracePeriodExpiringSoon?: number;
+    }): Promise<Subscription[]>;
+    /**
+     * Check if a subscription still has access (considering grace period).
+     *
+     * Returns true if:
+     * - Subscription is active
+     * - Subscription is trialing
+     * - Subscription is past_due but within grace period
+     *
+     * @example
+     * ```typescript
+     * const { hasAccess } = await stackbe.subscriptions.checkAccess('sub_123');
+     * if (!hasAccess) {
+     *   // Show upgrade prompt or block feature
+     * }
+     * ```
+     */
+    checkAccess(subscriptionId: string): Promise<{
+        hasAccess: boolean;
+    }>;
 }
 
 interface AuthClientOptions {
@@ -2368,4 +2525,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 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 };
+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, 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 DunningStatus, 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 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

@@ -184,12 +184,60 @@ interface Subscription {
     currentPeriodStart: string;
     currentPeriodEnd: string;
     cancelAtPeriodEnd: boolean;
+    /** When the trial started (null if no trial) */
+    trialStart?: string | null;
+    /** When the trial ends/ended (null if no trial) */
+    trialEnd?: string | null;
+    /** When trial converted to paid (null if not converted yet) */
+    trialConvertedAt?: string | null;
     /** When the subscription was paused (null if not paused) */
     pausedAt?: string | null;
     /** When the subscription will auto-resume (null = indefinite pause) */
     resumesAt?: string | null;
+    /** Number of consecutive failed payment attempts */
+    failedPaymentCount?: number;
+    /** Timestamp of most recent failed payment */
+    lastPaymentFailedAt?: string | null;
+    /** When access will be revoked if payment not recovered */
+    gracePeriodEndsAt?: string | null;
     createdAt: string;
 }
+interface TrialStatus {
+    /** Whether the subscription is currently in trial */
+    isTrialing: boolean;
+    /** When the trial started */
+    trialStart: string | null;
+    /** When the trial ends/ended */
+    trialEnd: string | null;
+    /** When the trial converted to paid (null if not converted) */
+    trialConvertedAt: string | null;
+    /** Days remaining in trial (null if not trialing) */
+    daysRemaining: number | null;
+    /** Whether the trial has converted to paid */
+    hasConverted: boolean;
+}
+interface DunningStatus {
+    /** Whether the subscription is past due */
+    isPastDue: boolean;
+    /** Whether the subscription is in grace period (past due but still has access) */
+    isInGracePeriod: boolean;
+    /** Number of consecutive failed payment attempts */
+    failedPaymentCount: number;
+    /** Timestamp of most recent failed payment */
+    lastPaymentFailedAt: string | null;
+    /** When access will be revoked if payment not recovered */
+    gracePeriodEndsAt: string | null;
+    /** Days until access is revoked (null if not in grace period) */
+    daysUntilAccessRevoked: number | null;
+    /** Days since payment failed */
+    daysSinceFailure: number | null;
+    /** Configured dunning email schedule (days after failure) */
+    dunningEmailSchedule: number[];
+    /** Which dunning emails have been sent (days) */
+    emailsSent: number[];
+    /** Whether the customer still has access (considering grace period) */
+    hasAccess: boolean;
+}
 interface CustomerWithSubscription extends Customer {
     subscription?: Subscription;
 }
@@ -1177,6 +1225,115 @@ declare class SubscriptionsClient {
      * ```
      */
     resume(subscriptionId: string): Promise<Subscription>;
+    /**
+     * Get trial status for a subscription.
+     *
+     * @example
+     * ```typescript
+     * const trial = await stackbe.subscriptions.getTrialStatus('sub_123');
+     *
+     * if (trial.isTrialing) {
+     *   console.log(`Trial ends in ${trial.daysRemaining} days`);
+     * }
+     *
+     * if (trial.hasConverted) {
+     *   console.log(`Converted to paid on ${trial.trialConvertedAt}`);
+     * }
+     * ```
+     */
+    getTrialStatus(subscriptionId: string): Promise<TrialStatus>;
+    /**
+     * Extend a trial by a number of days.
+     *
+     * Only works for subscriptions currently in trial.
+     *
+     * @example
+     * ```typescript
+     * // Give the customer 7 more days
+     * const subscription = await stackbe.subscriptions.extendTrial('sub_123', 7);
+     * console.log(`New trial end: ${subscription.trialEnd}`);
+     * ```
+     */
+    extendTrial(subscriptionId: string, days: number): Promise<Subscription>;
+    /**
+     * End trial immediately and convert to paid subscription.
+     *
+     * The customer will be charged right away.
+     *
+     * @example
+     * ```typescript
+     * // Customer wants to start paying immediately
+     * const subscription = await stackbe.subscriptions.endTrial('sub_123');
+     * console.log(`Converted at: ${subscription.trialConvertedAt}`);
+     * ```
+     */
+    endTrial(subscriptionId: string): Promise<Subscription>;
+    /**
+     * Get dunning/payment recovery status for a subscription.
+     *
+     * Shows if the subscription is past due, in grace period, and when access
+     * will be revoked if payment isn't recovered.
+     *
+     * @example
+     * ```typescript
+     * const dunning = await stackbe.subscriptions.getDunningStatus('sub_123');
+     *
+     * if (dunning.isPastDue) {
+     *   console.log(`Payment failed ${dunning.daysSinceFailure} days ago`);
+     *
+     *   if (dunning.isInGracePeriod) {
+     *     console.log(`Access ends in ${dunning.daysUntilAccessRevoked} days`);
+     *   }
+     * }
+     *
+     * // Check if customer still has access
+     * if (dunning.hasAccess) {
+     *   // Allow access
+     * }
+     * ```
+     */
+    getDunningStatus(subscriptionId: string): Promise<DunningStatus>;
+    /**
+     * List all past-due subscriptions.
+     *
+     * Useful for monitoring and recovery efforts.
+     *
+     * @example
+     * ```typescript
+     * // List all past-due subscriptions
+     * const pastDue = await stackbe.subscriptions.listPastDue();
+     *
+     * // List subscriptions losing access within 3 days
+     * const urgent = await stackbe.subscriptions.listPastDue({ gracePeriodExpiringSoon: 3 });
+     *
+     * for (const sub of urgent) {
+     *   console.log(`${sub.customer.email} loses access in ${sub.gracePeriodEndsAt}`);
+     * }
+     * ```
+     */
+    listPastDue(options?: {
+        appId?: string;
+        gracePeriodExpiringSoon?: number;
+    }): Promise<Subscription[]>;
+    /**
+     * Check if a subscription still has access (considering grace period).
+     *
+     * Returns true if:
+     * - Subscription is active
+     * - Subscription is trialing
+     * - Subscription is past_due but within grace period
+     *
+     * @example
+     * ```typescript
+     * const { hasAccess } = await stackbe.subscriptions.checkAccess('sub_123');
+     * if (!hasAccess) {
+     *   // Show upgrade prompt or block feature
+     * }
+     * ```
+     */
+    checkAccess(subscriptionId: string): Promise<{
+        hasAccess: boolean;
+    }>;
 }
 
 interface AuthClientOptions {
@@ -2368,4 +2525,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 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 };
+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, 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 DunningStatus, 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 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

@@ -1027,6 +1027,146 @@ var SubscriptionsClient = class {
       `/v1/subscriptions/${subscriptionId}/resume`
     );
   }
+  // ============================================
+  // Trial Management Methods
+  // ============================================
+  /**
+   * Get trial status for a subscription.
+   *
+   * @example
+   * ```typescript
+   * const trial = await stackbe.subscriptions.getTrialStatus('sub_123');
+   *
+   * if (trial.isTrialing) {
+   *   console.log(`Trial ends in ${trial.daysRemaining} days`);
+   * }
+   *
+   * if (trial.hasConverted) {
+   *   console.log(`Converted to paid on ${trial.trialConvertedAt}`);
+   * }
+   * ```
+   */
+  async getTrialStatus(subscriptionId) {
+    return this.http.get(
+      `/v1/subscriptions/${subscriptionId}/trial`
+    );
+  }
+  /**
+   * Extend a trial by a number of days.
+   *
+   * Only works for subscriptions currently in trial.
+   *
+   * @example
+   * ```typescript
+   * // Give the customer 7 more days
+   * const subscription = await stackbe.subscriptions.extendTrial('sub_123', 7);
+   * console.log(`New trial end: ${subscription.trialEnd}`);
+   * ```
+   */
+  async extendTrial(subscriptionId, days) {
+    return this.http.post(
+      `/v1/subscriptions/${subscriptionId}/trial/extend`,
+      { days }
+    );
+  }
+  /**
+   * End trial immediately and convert to paid subscription.
+   *
+   * The customer will be charged right away.
+   *
+   * @example
+   * ```typescript
+   * // Customer wants to start paying immediately
+   * const subscription = await stackbe.subscriptions.endTrial('sub_123');
+   * console.log(`Converted at: ${subscription.trialConvertedAt}`);
+   * ```
+   */
+  async endTrial(subscriptionId) {
+    return this.http.post(
+      `/v1/subscriptions/${subscriptionId}/trial/end`
+    );
+  }
+  // ============================================
+  // Dunning / Payment Recovery Methods
+  // ============================================
+  /**
+   * Get dunning/payment recovery status for a subscription.
+   *
+   * Shows if the subscription is past due, in grace period, and when access
+   * will be revoked if payment isn't recovered.
+   *
+   * @example
+   * ```typescript
+   * const dunning = await stackbe.subscriptions.getDunningStatus('sub_123');
+   *
+   * if (dunning.isPastDue) {
+   *   console.log(`Payment failed ${dunning.daysSinceFailure} days ago`);
+   *
+   *   if (dunning.isInGracePeriod) {
+   *     console.log(`Access ends in ${dunning.daysUntilAccessRevoked} days`);
+   *   }
+   * }
+   *
+   * // Check if customer still has access
+   * if (dunning.hasAccess) {
+   *   // Allow access
+   * }
+   * ```
+   */
+  async getDunningStatus(subscriptionId) {
+    return this.http.get(
+      `/v1/subscriptions/${subscriptionId}/dunning`
+    );
+  }
+  /**
+   * List all past-due subscriptions.
+   *
+   * Useful for monitoring and recovery efforts.
+   *
+   * @example
+   * ```typescript
+   * // List all past-due subscriptions
+   * const pastDue = await stackbe.subscriptions.listPastDue();
+   *
+   * // List subscriptions losing access within 3 days
+   * const urgent = await stackbe.subscriptions.listPastDue({ gracePeriodExpiringSoon: 3 });
+   *
+   * for (const sub of urgent) {
+   *   console.log(`${sub.customer.email} loses access in ${sub.gracePeriodEndsAt}`);
+   * }
+   * ```
+   */
+  async listPastDue(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.set("appId", options.appId);
+    if (options?.gracePeriodExpiringSoon) {
+      params.set("gracePeriodExpiringSoon", String(options.gracePeriodExpiringSoon));
+    }
+    const query = params.toString();
+    const path = `/v1/subscriptions/past-due${query ? `?${query}` : ""}`;
+    return this.http.get(path);
+  }
+  /**
+   * Check if a subscription still has access (considering grace period).
+   *
+   * Returns true if:
+   * - Subscription is active
+   * - Subscription is trialing
+   * - Subscription is past_due but within grace period
+   *
+   * @example
+   * ```typescript
+   * const { hasAccess } = await stackbe.subscriptions.checkAccess('sub_123');
+   * if (!hasAccess) {
+   *   // Show upgrade prompt or block feature
+   * }
+   * ```
+   */
+  async checkAccess(subscriptionId) {
+    return this.http.get(
+      `/v1/subscriptions/${subscriptionId}/has-access`
+    );
+  }
 };
 
 // src/auth.ts

package/dist/index.mjs

@@ -987,6 +987,146 @@ var SubscriptionsClient = class {
       `/v1/subscriptions/${subscriptionId}/resume`
     );
   }
+  // ============================================
+  // Trial Management Methods
+  // ============================================
+  /**
+   * Get trial status for a subscription.
+   *
+   * @example
+   * ```typescript
+   * const trial = await stackbe.subscriptions.getTrialStatus('sub_123');
+   *
+   * if (trial.isTrialing) {
+   *   console.log(`Trial ends in ${trial.daysRemaining} days`);
+   * }
+   *
+   * if (trial.hasConverted) {
+   *   console.log(`Converted to paid on ${trial.trialConvertedAt}`);
+   * }
+   * ```
+   */
+  async getTrialStatus(subscriptionId) {
+    return this.http.get(
+      `/v1/subscriptions/${subscriptionId}/trial`
+    );
+  }
+  /**
+   * Extend a trial by a number of days.
+   *
+   * Only works for subscriptions currently in trial.
+   *
+   * @example
+   * ```typescript
+   * // Give the customer 7 more days
+   * const subscription = await stackbe.subscriptions.extendTrial('sub_123', 7);
+   * console.log(`New trial end: ${subscription.trialEnd}`);
+   * ```
+   */
+  async extendTrial(subscriptionId, days) {
+    return this.http.post(
+      `/v1/subscriptions/${subscriptionId}/trial/extend`,
+      { days }
+    );
+  }
+  /**
+   * End trial immediately and convert to paid subscription.
+   *
+   * The customer will be charged right away.
+   *
+   * @example
+   * ```typescript
+   * // Customer wants to start paying immediately
+   * const subscription = await stackbe.subscriptions.endTrial('sub_123');
+   * console.log(`Converted at: ${subscription.trialConvertedAt}`);
+   * ```
+   */
+  async endTrial(subscriptionId) {
+    return this.http.post(
+      `/v1/subscriptions/${subscriptionId}/trial/end`
+    );
+  }
+  // ============================================
+  // Dunning / Payment Recovery Methods
+  // ============================================
+  /**
+   * Get dunning/payment recovery status for a subscription.
+   *
+   * Shows if the subscription is past due, in grace period, and when access
+   * will be revoked if payment isn't recovered.
+   *
+   * @example
+   * ```typescript
+   * const dunning = await stackbe.subscriptions.getDunningStatus('sub_123');
+   *
+   * if (dunning.isPastDue) {
+   *   console.log(`Payment failed ${dunning.daysSinceFailure} days ago`);
+   *
+   *   if (dunning.isInGracePeriod) {
+   *     console.log(`Access ends in ${dunning.daysUntilAccessRevoked} days`);
+   *   }
+   * }
+   *
+   * // Check if customer still has access
+   * if (dunning.hasAccess) {
+   *   // Allow access
+   * }
+   * ```
+   */
+  async getDunningStatus(subscriptionId) {
+    return this.http.get(
+      `/v1/subscriptions/${subscriptionId}/dunning`
+    );
+  }
+  /**
+   * List all past-due subscriptions.
+   *
+   * Useful for monitoring and recovery efforts.
+   *
+   * @example
+   * ```typescript
+   * // List all past-due subscriptions
+   * const pastDue = await stackbe.subscriptions.listPastDue();
+   *
+   * // List subscriptions losing access within 3 days
+   * const urgent = await stackbe.subscriptions.listPastDue({ gracePeriodExpiringSoon: 3 });
+   *
+   * for (const sub of urgent) {
+   *   console.log(`${sub.customer.email} loses access in ${sub.gracePeriodEndsAt}`);
+   * }
+   * ```
+   */
+  async listPastDue(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.set("appId", options.appId);
+    if (options?.gracePeriodExpiringSoon) {
+      params.set("gracePeriodExpiringSoon", String(options.gracePeriodExpiringSoon));
+    }
+    const query = params.toString();
+    const path = `/v1/subscriptions/past-due${query ? `?${query}` : ""}`;
+    return this.http.get(path);
+  }
+  /**
+   * Check if a subscription still has access (considering grace period).
+   *
+   * Returns true if:
+   * - Subscription is active
+   * - Subscription is trialing
+   * - Subscription is past_due but within grace period
+   *
+   * @example
+   * ```typescript
+   * const { hasAccess } = await stackbe.subscriptions.checkAccess('sub_123');
+   * if (!hasAccess) {
+   *   // Show upgrade prompt or block feature
+   * }
+   * ```
+   */
+  async checkAccess(subscriptionId) {
+    return this.http.get(
+      `/v1/subscriptions/${subscriptionId}/has-access`
+    );
+  }
 };
 
 // src/auth.ts

package/package.json

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