@stackbe/sdk 0.9.5 → 0.11.0

package/dist/index.d.mts

@@ -2396,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;
@@ -2425,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.
      *
@@ -2525,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, 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 };
+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

@@ -2396,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;
@@ -2425,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.
      *
@@ -2525,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, 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 };
+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,
@@ -2277,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;
@@ -2343,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.
@@ -2477,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

@@ -2237,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;
@@ -2303,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.
@@ -2436,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.5",
+  "version": "0.11.0",
   "description": "Official JavaScript/TypeScript SDK for StackBE - the billing backend for your side project",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -20,7 +20,10 @@
     "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
     "lint": "eslint src/",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "jest",
+    "test:contract": "jest test/contract.test.ts",
+    "test:contract:prod": "API_URL=https://api.stackbe.io jest test/contract.test.ts"
   },
   "keywords": [
     "stackbe",
@@ -42,7 +45,10 @@
     "url": "https://github.com/Epic-Design-Labs/app-stackbe-sdk/issues"
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/node": "^20.10.0",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
     "tsup": "^8.0.1",
     "typescript": "^5.3.0"
   },