@stackbe/sdk 0.9.4 → 0.10.0

package/dist/index.d.mts

@@ -194,6 +194,12 @@ interface Subscription {
     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 {
@@ -210,6 +216,28 @@ interface TrialStatus {
     /** 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;
 }
@@ -1240,6 +1268,72 @@ declare class SubscriptionsClient {
      * ```
      */
     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 {
@@ -2302,6 +2396,195 @@ declare class CouponsClient {
     delete(couponId: string): Promise<void>;
 }
 
+interface DashboardMetrics {
+    revenue: {
+        mrr: number;
+        arpu: number;
+    };
+    subscriptions: {
+        active: number;
+        churnRate: number;
+    };
+    trials: {
+        active: number;
+        conversionRate: number;
+        avgDays: number;
+    };
+    growth: {
+        newSubscribers: number;
+        churnedSubscribers: number;
+        netGrowth: number;
+        growthRate: number;
+    };
+    conversion: {
+        rate: number;
+    };
+    api: {
+        errorRate: number;
+        avgResponseTime: number;
+    };
+}
+interface MRRHistoryPoint {
+    date: string;
+    mrr: number;
+}
+interface RevenueByPlan {
+    planId: string;
+    planName: string;
+    mrr: number;
+    subscriberCount: number;
+    percentage: number;
+}
+interface TrialMetrics {
+    trialStarts: number;
+    trialConversions: number;
+    trialConversionRate: number;
+    avgTrialDays: number;
+    activeTrials: number;
+}
+interface GrowthMetrics {
+    newSubscribers: number;
+    churnedSubscribers: number;
+    netGrowth: number;
+    growthRate: number;
+}
+interface GrowthChartPoint {
+    date: string;
+    new: number;
+    churned: number;
+    net: number;
+}
+interface PlanMetrics {
+    planId: string;
+    planName: string;
+    subscriberCount: number;
+    percentage: number;
+    priceCents: number;
+    interval: string;
+}
+interface RequestCountPoint {
+    date: string;
+    count: number;
+}
+interface PopularEndpoint {
+    endpoint: string;
+    count: number;
+}
+interface PerformanceMetrics {
+    errorRate: number;
+    avgResponseTime: number;
+}
+interface FeatureUsagePoint {
+    date: string;
+    count: number;
+}
+interface AnalyticsFilterOptions {
+    appId?: string;
+}
+interface TimeRangeOptions extends AnalyticsFilterOptions {
+    days?: number;
+}
+/**
+ * Analytics client for accessing business metrics
+ *
+ * @example
+ * ```typescript
+ * const stackbe = new StackBE({ apiKey: '...', appId: '...' });
+ *
+ * // Get full dashboard
+ * const dashboard = await stackbe.analytics.getDashboard();
+ *
+ * // Get MRR history
+ * const mrrHistory = await stackbe.analytics.getMRRHistory({ days: 30 });
+ *
+ * // Get revenue by plan
+ * const revenueByPlan = await stackbe.analytics.getRevenueByPlan();
+ *
+ * // Get trial metrics
+ * const trials = await stackbe.analytics.getTrialMetrics({ days: 30 });
+ *
+ * // Get growth chart
+ * const growth = await stackbe.analytics.getGrowthChart({ days: 30 });
+ * ```
+ */
+declare class AnalyticsClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get the full analytics dashboard with all key metrics
+     */
+    getDashboard(options?: AnalyticsFilterOptions): Promise<DashboardMetrics>;
+    /**
+     * Get current Monthly Recurring Revenue
+     */
+    getMRR(options?: AnalyticsFilterOptions): Promise<{
+        mrr: number;
+    }>;
+    /**
+     * Get MRR history over time for trend analysis
+     */
+    getMRRHistory(options?: TimeRangeOptions): Promise<MRRHistoryPoint[]>;
+    /**
+     * Get revenue breakdown by plan
+     */
+    getRevenueByPlan(options?: AnalyticsFilterOptions): Promise<RevenueByPlan[]>;
+    /**
+     * Get Average Revenue Per User
+     */
+    getARPU(options?: AnalyticsFilterOptions): Promise<{
+        arpu: number;
+    }>;
+    /**
+     * Get subscription metrics (active count, churn rate)
+     */
+    getSubscriptionMetrics(options?: TimeRangeOptions): Promise<{
+        active: number;
+        churnRate: number;
+    }>;
+    /**
+     * Get subscriber distribution by plan
+     */
+    getSubscribersByPlan(options?: AnalyticsFilterOptions): Promise<PlanMetrics[]>;
+    /**
+     * Get trial metrics (starts, conversions, conversion rate)
+     * Useful for freemium and trial-based pricing models
+     */
+    getTrialMetrics(options?: TimeRangeOptions): Promise<TrialMetrics>;
+    /**
+     * Get growth metrics (new vs churned subscribers)
+     */
+    getGrowthMetrics(options?: TimeRangeOptions): Promise<GrowthMetrics>;
+    /**
+     * Get growth chart data (daily new vs churned for charting)
+     */
+    getGrowthChart(options?: TimeRangeOptions): Promise<GrowthChartPoint[]>;
+    /**
+     * Get checkout conversion rate
+     */
+    getConversionRate(options?: TimeRangeOptions): Promise<{
+        rate: number;
+        period: number;
+    }>;
+    /**
+     * Get API request counts over time
+     */
+    getRequestCounts(options?: TimeRangeOptions): Promise<RequestCountPoint[]>;
+    /**
+     * Get most popular API endpoints
+     */
+    getPopularEndpoints(options?: AnalyticsFilterOptions & {
+        limit?: number;
+    }): Promise<PopularEndpoint[]>;
+    /**
+     * Get API performance metrics (error rate, response time)
+     */
+    getPerformance(options?: TimeRangeOptions): Promise<PerformanceMetrics>;
+    /**
+     * Get feature usage over time (entitlement checks)
+     */
+    getFeatureUsage(options?: TimeRangeOptions): Promise<FeatureUsagePoint[]>;
+}
+
 declare class StackBE {
     private http;
     private appId;
@@ -2331,6 +2614,8 @@ declare class StackBE {
     readonly earlyAccess: EarlyAccessClient;
     /** Coupon/promo code management */
     readonly coupons: CouponsClient;
+    /** Analytics and business metrics */
+    readonly analytics: AnalyticsClient;
     /**
      * Create a new StackBE client.
      *
@@ -2431,4 +2716,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, 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 };
+export { type AddMemberOptions, type AffiliateCommission, type AffiliateCommissionsResponse, type AffiliateEnrollment, type AffiliateInfo, type AffiliateStats, AffiliatesClient, AnalyticsClient, type AnalyticsFilterOptions, 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 DashboardMetrics, type DunningStatus, EarlyAccessClient, type EarlyAccessSignup, type EarlyAccessSignupListResponse, type EnrollOptions, EntitlementsClient, type EntitlementsResponse, type FeatureRequest, type FeatureRequestComment, type FeatureRequestImage, type FeatureRequestListResponse, FeatureRequestsClient, type FeatureUsagePoint, type GetSubscriptionOptions, type GrowthChartPoint, type GrowthMetrics, type InterestedCustomer, type InterestedCustomersResponse, type InviteMemberOptions, type ListEarlyAccessOptions, type ListFeatureRequestsOptions, type ListPlansOptions, type ListProductsOptions, type MRRHistoryPoint, type MagicLinkOptions, type MagicLinkResponse, type Organization, type OrganizationInvite, type OrganizationMember, OrganizationsClient, type PaymentFailedEvent, type PaymentSucceededEvent, type PaymentWebhookPayload, type PerformanceMetrics, type Plan, type PlanMetrics, PlansClient, type PopularEndpoint, type Product, ProductsClient, type RequestCountPoint, type RevenueByPlan, 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 TimeRangeOptions, type TrackReferralResponse, type TrackUsageOptions, type TrackUsageResponse, type TrialEndedEvent, type TrialMetrics, 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

@@ -194,6 +194,12 @@ interface Subscription {
     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 {
@@ -210,6 +216,28 @@ interface TrialStatus {
     /** 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;
 }
@@ -1240,6 +1268,72 @@ declare class SubscriptionsClient {
      * ```
      */
     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 {
@@ -2302,6 +2396,195 @@ declare class CouponsClient {
     delete(couponId: string): Promise<void>;
 }
 
+interface DashboardMetrics {
+    revenue: {
+        mrr: number;
+        arpu: number;
+    };
+    subscriptions: {
+        active: number;
+        churnRate: number;
+    };
+    trials: {
+        active: number;
+        conversionRate: number;
+        avgDays: number;
+    };
+    growth: {
+        newSubscribers: number;
+        churnedSubscribers: number;
+        netGrowth: number;
+        growthRate: number;
+    };
+    conversion: {
+        rate: number;
+    };
+    api: {
+        errorRate: number;
+        avgResponseTime: number;
+    };
+}
+interface MRRHistoryPoint {
+    date: string;
+    mrr: number;
+}
+interface RevenueByPlan {
+    planId: string;
+    planName: string;
+    mrr: number;
+    subscriberCount: number;
+    percentage: number;
+}
+interface TrialMetrics {
+    trialStarts: number;
+    trialConversions: number;
+    trialConversionRate: number;
+    avgTrialDays: number;
+    activeTrials: number;
+}
+interface GrowthMetrics {
+    newSubscribers: number;
+    churnedSubscribers: number;
+    netGrowth: number;
+    growthRate: number;
+}
+interface GrowthChartPoint {
+    date: string;
+    new: number;
+    churned: number;
+    net: number;
+}
+interface PlanMetrics {
+    planId: string;
+    planName: string;
+    subscriberCount: number;
+    percentage: number;
+    priceCents: number;
+    interval: string;
+}
+interface RequestCountPoint {
+    date: string;
+    count: number;
+}
+interface PopularEndpoint {
+    endpoint: string;
+    count: number;
+}
+interface PerformanceMetrics {
+    errorRate: number;
+    avgResponseTime: number;
+}
+interface FeatureUsagePoint {
+    date: string;
+    count: number;
+}
+interface AnalyticsFilterOptions {
+    appId?: string;
+}
+interface TimeRangeOptions extends AnalyticsFilterOptions {
+    days?: number;
+}
+/**
+ * Analytics client for accessing business metrics
+ *
+ * @example
+ * ```typescript
+ * const stackbe = new StackBE({ apiKey: '...', appId: '...' });
+ *
+ * // Get full dashboard
+ * const dashboard = await stackbe.analytics.getDashboard();
+ *
+ * // Get MRR history
+ * const mrrHistory = await stackbe.analytics.getMRRHistory({ days: 30 });
+ *
+ * // Get revenue by plan
+ * const revenueByPlan = await stackbe.analytics.getRevenueByPlan();
+ *
+ * // Get trial metrics
+ * const trials = await stackbe.analytics.getTrialMetrics({ days: 30 });
+ *
+ * // Get growth chart
+ * const growth = await stackbe.analytics.getGrowthChart({ days: 30 });
+ * ```
+ */
+declare class AnalyticsClient {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Get the full analytics dashboard with all key metrics
+     */
+    getDashboard(options?: AnalyticsFilterOptions): Promise<DashboardMetrics>;
+    /**
+     * Get current Monthly Recurring Revenue
+     */
+    getMRR(options?: AnalyticsFilterOptions): Promise<{
+        mrr: number;
+    }>;
+    /**
+     * Get MRR history over time for trend analysis
+     */
+    getMRRHistory(options?: TimeRangeOptions): Promise<MRRHistoryPoint[]>;
+    /**
+     * Get revenue breakdown by plan
+     */
+    getRevenueByPlan(options?: AnalyticsFilterOptions): Promise<RevenueByPlan[]>;
+    /**
+     * Get Average Revenue Per User
+     */
+    getARPU(options?: AnalyticsFilterOptions): Promise<{
+        arpu: number;
+    }>;
+    /**
+     * Get subscription metrics (active count, churn rate)
+     */
+    getSubscriptionMetrics(options?: TimeRangeOptions): Promise<{
+        active: number;
+        churnRate: number;
+    }>;
+    /**
+     * Get subscriber distribution by plan
+     */
+    getSubscribersByPlan(options?: AnalyticsFilterOptions): Promise<PlanMetrics[]>;
+    /**
+     * Get trial metrics (starts, conversions, conversion rate)
+     * Useful for freemium and trial-based pricing models
+     */
+    getTrialMetrics(options?: TimeRangeOptions): Promise<TrialMetrics>;
+    /**
+     * Get growth metrics (new vs churned subscribers)
+     */
+    getGrowthMetrics(options?: TimeRangeOptions): Promise<GrowthMetrics>;
+    /**
+     * Get growth chart data (daily new vs churned for charting)
+     */
+    getGrowthChart(options?: TimeRangeOptions): Promise<GrowthChartPoint[]>;
+    /**
+     * Get checkout conversion rate
+     */
+    getConversionRate(options?: TimeRangeOptions): Promise<{
+        rate: number;
+        period: number;
+    }>;
+    /**
+     * Get API request counts over time
+     */
+    getRequestCounts(options?: TimeRangeOptions): Promise<RequestCountPoint[]>;
+    /**
+     * Get most popular API endpoints
+     */
+    getPopularEndpoints(options?: AnalyticsFilterOptions & {
+        limit?: number;
+    }): Promise<PopularEndpoint[]>;
+    /**
+     * Get API performance metrics (error rate, response time)
+     */
+    getPerformance(options?: TimeRangeOptions): Promise<PerformanceMetrics>;
+    /**
+     * Get feature usage over time (entitlement checks)
+     */
+    getFeatureUsage(options?: TimeRangeOptions): Promise<FeatureUsagePoint[]>;
+}
+
 declare class StackBE {
     private http;
     private appId;
@@ -2331,6 +2614,8 @@ declare class StackBE {
     readonly earlyAccess: EarlyAccessClient;
     /** Coupon/promo code management */
     readonly coupons: CouponsClient;
+    /** Analytics and business metrics */
+    readonly analytics: AnalyticsClient;
     /**
      * Create a new StackBE client.
      *
@@ -2431,4 +2716,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, 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 };
+export { type AddMemberOptions, type AffiliateCommission, type AffiliateCommissionsResponse, type AffiliateEnrollment, type AffiliateInfo, type AffiliateStats, AffiliatesClient, AnalyticsClient, type AnalyticsFilterOptions, 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 DashboardMetrics, type DunningStatus, EarlyAccessClient, type EarlyAccessSignup, type EarlyAccessSignupListResponse, type EnrollOptions, EntitlementsClient, type EntitlementsResponse, type FeatureRequest, type FeatureRequestComment, type FeatureRequestImage, type FeatureRequestListResponse, FeatureRequestsClient, type FeatureUsagePoint, type GetSubscriptionOptions, type GrowthChartPoint, type GrowthMetrics, type InterestedCustomer, type InterestedCustomersResponse, type InviteMemberOptions, type ListEarlyAccessOptions, type ListFeatureRequestsOptions, type ListPlansOptions, type ListProductsOptions, type MRRHistoryPoint, type MagicLinkOptions, type MagicLinkResponse, type Organization, type OrganizationInvite, type OrganizationMember, OrganizationsClient, type PaymentFailedEvent, type PaymentSucceededEvent, type PaymentWebhookPayload, type PerformanceMetrics, type Plan, type PlanMetrics, PlansClient, type PopularEndpoint, type Product, ProductsClient, type RequestCountPoint, type RevenueByPlan, 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 TimeRangeOptions, type TrackReferralResponse, type TrackUsageOptions, type TrackUsageResponse, type TrialEndedEvent, type TrialMetrics, 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

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   AffiliatesClient: () => AffiliatesClient,
+  AnalyticsClient: () => AnalyticsClient,
   AuthClient: () => AuthClient,
   CheckoutClient: () => CheckoutClient,
   CouponsClient: () => CouponsClient,
@@ -1086,6 +1087,87 @@ var SubscriptionsClient = class {
       `/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
@@ -2196,6 +2278,159 @@ var CouponsClient = class {
   }
 };
 
+// src/analytics.ts
+var AnalyticsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get the full analytics dashboard with all key metrics
+   */
+  async getDashboard(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/dashboard${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get current Monthly Recurring Revenue
+   */
+  async getMRR(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/revenue/mrr${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get MRR history over time for trend analysis
+   */
+  async getMRRHistory(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/revenue/history${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get revenue breakdown by plan
+   */
+  async getRevenueByPlan(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/revenue/by-plan${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get Average Revenue Per User
+   */
+  async getARPU(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/revenue/arpu${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get subscription metrics (active count, churn rate)
+   */
+  async getSubscriptionMetrics(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/subscriptions/metrics${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get subscriber distribution by plan
+   */
+  async getSubscribersByPlan(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/subscriptions/by-plan${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get trial metrics (starts, conversions, conversion rate)
+   * Useful for freemium and trial-based pricing models
+   */
+  async getTrialMetrics(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/trials/metrics${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get growth metrics (new vs churned subscribers)
+   */
+  async getGrowthMetrics(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/growth/metrics${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get growth chart data (daily new vs churned for charting)
+   */
+  async getGrowthChart(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/growth/chart${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get checkout conversion rate
+   */
+  async getConversionRate(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/conversion/rate${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get API request counts over time
+   */
+  async getRequestCounts(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/api/requests${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get most popular API endpoints
+   */
+  async getPopularEndpoints(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.limit) params.append("limit", options.limit.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/api/endpoints${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get API performance metrics (error rate, response time)
+   */
+  async getPerformance(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/api/performance${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get feature usage over time (entitlement checks)
+   */
+  async getFeatureUsage(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/features/usage${query ? `?${query}` : ""}`);
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.stackbe.io";
 var DEFAULT_TIMEOUT = 3e4;
@@ -2262,6 +2497,7 @@ var StackBE = class {
     this.affiliates = new AffiliatesClient(this.http);
     this.earlyAccess = new EarlyAccessClient(this.http, config.appId);
     this.coupons = new CouponsClient(this.http, config.appId);
+    this.analytics = new AnalyticsClient(this.http);
   }
   /**
    * Create a middleware for Express that tracks usage automatically.
@@ -2396,6 +2632,7 @@ var StackBE = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AffiliatesClient,
+  AnalyticsClient,
   AuthClient,
   CheckoutClient,
   CouponsClient,

package/dist/index.mjs

@@ -1046,6 +1046,87 @@ var SubscriptionsClient = class {
       `/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
@@ -2156,6 +2237,159 @@ var CouponsClient = class {
   }
 };
 
+// src/analytics.ts
+var AnalyticsClient = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get the full analytics dashboard with all key metrics
+   */
+  async getDashboard(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/dashboard${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get current Monthly Recurring Revenue
+   */
+  async getMRR(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/revenue/mrr${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get MRR history over time for trend analysis
+   */
+  async getMRRHistory(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/revenue/history${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get revenue breakdown by plan
+   */
+  async getRevenueByPlan(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/revenue/by-plan${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get Average Revenue Per User
+   */
+  async getARPU(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/revenue/arpu${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get subscription metrics (active count, churn rate)
+   */
+  async getSubscriptionMetrics(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/subscriptions/metrics${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get subscriber distribution by plan
+   */
+  async getSubscribersByPlan(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/subscriptions/by-plan${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get trial metrics (starts, conversions, conversion rate)
+   * Useful for freemium and trial-based pricing models
+   */
+  async getTrialMetrics(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/trials/metrics${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get growth metrics (new vs churned subscribers)
+   */
+  async getGrowthMetrics(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/growth/metrics${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get growth chart data (daily new vs churned for charting)
+   */
+  async getGrowthChart(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/growth/chart${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get checkout conversion rate
+   */
+  async getConversionRate(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/conversion/rate${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get API request counts over time
+   */
+  async getRequestCounts(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/api/requests${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get most popular API endpoints
+   */
+  async getPopularEndpoints(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.limit) params.append("limit", options.limit.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/api/endpoints${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get API performance metrics (error rate, response time)
+   */
+  async getPerformance(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/api/performance${query ? `?${query}` : ""}`);
+  }
+  /**
+   * Get feature usage over time (entitlement checks)
+   */
+  async getFeatureUsage(options) {
+    const params = new URLSearchParams();
+    if (options?.appId) params.append("appId", options.appId);
+    if (options?.days) params.append("days", options.days.toString());
+    const query = params.toString();
+    return this.http.get(`/v1/analytics/features/usage${query ? `?${query}` : ""}`);
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.stackbe.io";
 var DEFAULT_TIMEOUT = 3e4;
@@ -2222,6 +2456,7 @@ var StackBE = class {
     this.affiliates = new AffiliatesClient(this.http);
     this.earlyAccess = new EarlyAccessClient(this.http, config.appId);
     this.coupons = new CouponsClient(this.http, config.appId);
+    this.analytics = new AnalyticsClient(this.http);
   }
   /**
    * Create a middleware for Express that tracks usage automatically.
@@ -2355,6 +2590,7 @@ var StackBE = class {
 };
 export {
   AffiliatesClient,
+  AnalyticsClient,
   AuthClient,
   CheckoutClient,
   CouponsClient,

package/package.json

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