@stackbe/sdk 0.9.2 → 0.9.4

package/dist/index.d.mts

@@ -184,12 +184,32 @@ 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;
     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 CustomerWithSubscription extends Customer {
     subscription?: Subscription;
 }
@@ -1177,6 +1197,49 @@ 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>;
 }
 
 interface AuthClientOptions {
@@ -2094,6 +2157,8 @@ declare class EarlyAccessClient {
 }
 
 type CouponDiscountType = 'percentage' | 'fixed_amount';
+/** How long the discount applies */
+type CouponDuration = 'once' | 'repeating' | 'forever';
 interface Coupon {
     id: string;
     code: string;
@@ -2101,6 +2166,10 @@ interface Coupon {
     discountType: CouponDiscountType;
     discountValue: number;
     currency?: string;
+    /** How long the discount applies: once (first invoice), repeating (X months), forever */
+    duration: CouponDuration;
+    /** Number of months for repeating duration */
+    durationInMonths?: number;
     maxRedemptions?: number;
     timesRedeemed: number;
     expiresAt?: string;
@@ -2120,6 +2189,15 @@ interface CreateCouponOptions {
     discountValue: number;
     /** Currency code (required for fixed_amount) */
     currency?: string;
+    /**
+     * How long the discount applies (default: 'once')
+     * - 'once': Applies to first invoice only
+     * - 'repeating': Applies for X months (requires durationInMonths)
+     * - 'forever': Applies to all future invoices
+     */
+    duration?: CouponDuration;
+    /** Number of months the discount applies (required when duration is 'repeating') */
+    durationInMonths?: number;
     /** Maximum number of times this coupon can be used */
     maxRedemptions?: number;
     /** When the coupon expires (ISO date string) */
@@ -2353,4 +2431,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, 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,32 @@ 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;
     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 CustomerWithSubscription extends Customer {
     subscription?: Subscription;
 }
@@ -1177,6 +1197,49 @@ 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>;
 }
 
 interface AuthClientOptions {
@@ -2094,6 +2157,8 @@ declare class EarlyAccessClient {
 }
 
 type CouponDiscountType = 'percentage' | 'fixed_amount';
+/** How long the discount applies */
+type CouponDuration = 'once' | 'repeating' | 'forever';
 interface Coupon {
     id: string;
     code: string;
@@ -2101,6 +2166,10 @@ interface Coupon {
     discountType: CouponDiscountType;
     discountValue: number;
     currency?: string;
+    /** How long the discount applies: once (first invoice), repeating (X months), forever */
+    duration: CouponDuration;
+    /** Number of months for repeating duration */
+    durationInMonths?: number;
     maxRedemptions?: number;
     timesRedeemed: number;
     expiresAt?: string;
@@ -2120,6 +2189,15 @@ interface CreateCouponOptions {
     discountValue: number;
     /** Currency code (required for fixed_amount) */
     currency?: string;
+    /**
+     * How long the discount applies (default: 'once')
+     * - 'once': Applies to first invoice only
+     * - 'repeating': Applies for X months (requires durationInMonths)
+     * - 'forever': Applies to all future invoices
+     */
+    duration?: CouponDuration;
+    /** Number of months the discount applies (required when duration is 'repeating') */
+    durationInMonths?: number;
     /** Maximum number of times this coupon can be used */
     maxRedemptions?: number;
     /** When the coupon expires (ISO date string) */
@@ -2353,4 +2431,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, 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,65 @@ 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`
+    );
+  }
 };
 
 // src/auth.ts

package/dist/index.mjs

@@ -987,6 +987,65 @@ 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`
+    );
+  }
 };
 
 // src/auth.ts

package/package.json

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