@stackbe/sdk 0.4.0 → 0.5.0

package/dist/index.d.mts

@@ -11,6 +11,7 @@ declare class HttpClient {
     private request;
     get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
     post<T>(path: string, body?: unknown, params?: Record<string, string | number | undefined>): Promise<T>;
+    put<T>(path: string, body?: unknown, params?: Record<string, string | number | undefined>): Promise<T>;
     patch<T>(path: string, body?: unknown): Promise<T>;
     delete<T>(path: string): Promise<T>;
 }
@@ -89,6 +90,69 @@ interface CustomerUsageResponse {
     billingPeriod: string;
     metrics: UsageMetric[];
 }
+interface SyncUsageOptions {
+    /** Idempotency key to prevent duplicate syncs */
+    idempotencyKey?: string;
+}
+interface SyncUsageResponse {
+    success: boolean;
+    currentUsage: number;
+    billingPeriod: string;
+    limit: number | null;
+    remaining: number | null;
+}
+interface CheckUsageWithAddonsResponse extends CheckUsageResponse {
+    /** Limit from plan (before addons) */
+    planLimit: number | null;
+    /** Total addon credits available */
+    addonCredits: number;
+    /** Total effective limit (plan + addons) */
+    effectiveLimit: number | null;
+}
+interface TrackUsageWithAddonsResponse extends TrackUsageResponse {
+    /** Usage deducted from plan allocation */
+    planUsage: number;
+    /** Usage deducted from addon credits */
+    addonUsage: number;
+}
+interface UsageAddon {
+    id: string;
+    appId: string;
+    metricId: string;
+    metricName: string;
+    name: string;
+    description?: string;
+    quantity: number;
+    priceCents: number;
+    currency: string;
+    status: 'active' | 'archived';
+    stripePriceId?: string;
+    createdAt: string;
+}
+interface UsageAddonPurchase {
+    id: string;
+    addonId: string;
+    addonName: string;
+    customerId: string;
+    metricId: string;
+    metricName: string;
+    quantity: number;
+    usedQuantity: number;
+    remainingQuantity: number;
+    priceCents: number;
+    currency: string;
+    billingPeriod: string;
+    expiresAt?: string;
+    createdAt: string;
+}
+interface CustomerCreditsResponse {
+    customerId: string;
+    metricName: string;
+    totalPurchased: number;
+    totalUsed: number;
+    remaining: number;
+    purchases: UsageAddonPurchase[];
+}
 interface CheckEntitlementResponse {
     /** Whether the customer has access to this feature */
     hasAccess: boolean;
@@ -409,6 +473,89 @@ declare class UsageClient {
     trackAndCheck(customerId: string, metric: string, options?: TrackUsageOptions): Promise<TrackUsageResponse & {
         allowed: boolean;
     }>;
+    /**
+     * Sync usage to an absolute value (instead of incrementing).
+     * Use this when your app tracks usage internally and reports the final count periodically.
+     *
+     * @example
+     * ```typescript
+     * // Your app tracks 847 billable tickets internally
+     * await stackbe.usage.sync('cust_123', 'tickets', 847);
+     * ```
+     */
+    sync(customerId: string, metric: string, value: number, options?: SyncUsageOptions): Promise<SyncUsageResponse>;
+    /**
+     * Check usage limits including purchased add-on credits.
+     *
+     * @example
+     * ```typescript
+     * const result = await stackbe.usage.checkWithAddons('cust_123', 'tickets');
+     *
+     * console.log(`Plan limit: ${result.planLimit}`);
+     * console.log(`Addon credits: ${result.addonCredits}`);
+     * console.log(`Effective limit: ${result.effectiveLimit}`);
+     *
+     * if (!result.allowed) {
+     *   // Prompt to purchase more credits
+     * }
+     * ```
+     */
+    checkWithAddons(customerId: string, metric: string): Promise<CheckUsageWithAddonsResponse>;
+    /**
+     * Track usage with automatic add-on credit deduction.
+     * When plan limit is exceeded, usage is deducted from purchased add-on credits.
+     *
+     * @example
+     * ```typescript
+     * const result = await stackbe.usage.trackWithAddons('cust_123', 'tickets');
+     *
+     * if (result.addonUsage > 0) {
+     *   console.log(`Used ${result.addonUsage} from addon credits`);
+     * }
+     * ```
+     */
+    trackWithAddons(customerId: string, metric: string, options?: TrackUsageOptions): Promise<TrackUsageWithAddonsResponse>;
+    /**
+     * List available add-on packs for purchase.
+     *
+     * @example
+     * ```typescript
+     * const addons = await stackbe.usage.listAddons();
+     *
+     * for (const addon of addons) {
+     *   console.log(`${addon.name}: ${addon.quantity} ${addon.metricName} for $${addon.priceCents / 100}`);
+     * }
+     * ```
+     */
+    listAddons(): Promise<UsageAddon[]>;
+    /**
+     * Purchase an add-on pack for a customer.
+     * Credits are immediately available after purchase.
+     *
+     * @example
+     * ```typescript
+     * // Purchase a 10k ticket pack
+     * const purchase = await stackbe.usage.purchaseAddon('cust_123', 'addon_xyz');
+     * console.log(`Purchased ${purchase.quantity} credits`);
+     * ```
+     */
+    purchaseAddon(customerId: string, addonId: string): Promise<UsageAddonPurchase>;
+    /**
+     * Get customer's purchased add-on credits for a metric.
+     *
+     * @example
+     * ```typescript
+     * const credits = await stackbe.usage.getCredits('cust_123', 'tickets');
+     *
+     * console.log(`Total purchased: ${credits.totalPurchased}`);
+     * console.log(`Remaining: ${credits.remaining}`);
+     *
+     * for (const purchase of credits.purchases) {
+     *   console.log(`${purchase.addonName}: ${purchase.remainingQuantity} left`);
+     * }
+     * ```
+     */
+    getCredits(customerId: string, metric: string): Promise<CustomerCreditsResponse>;
 }
 
 declare class EntitlementsClient {

package/dist/index.d.ts

@@ -11,6 +11,7 @@ declare class HttpClient {
     private request;
     get<T>(path: string, params?: Record<string, string | number | undefined>): Promise<T>;
     post<T>(path: string, body?: unknown, params?: Record<string, string | number | undefined>): Promise<T>;
+    put<T>(path: string, body?: unknown, params?: Record<string, string | number | undefined>): Promise<T>;
     patch<T>(path: string, body?: unknown): Promise<T>;
     delete<T>(path: string): Promise<T>;
 }
@@ -89,6 +90,69 @@ interface CustomerUsageResponse {
     billingPeriod: string;
     metrics: UsageMetric[];
 }
+interface SyncUsageOptions {
+    /** Idempotency key to prevent duplicate syncs */
+    idempotencyKey?: string;
+}
+interface SyncUsageResponse {
+    success: boolean;
+    currentUsage: number;
+    billingPeriod: string;
+    limit: number | null;
+    remaining: number | null;
+}
+interface CheckUsageWithAddonsResponse extends CheckUsageResponse {
+    /** Limit from plan (before addons) */
+    planLimit: number | null;
+    /** Total addon credits available */
+    addonCredits: number;
+    /** Total effective limit (plan + addons) */
+    effectiveLimit: number | null;
+}
+interface TrackUsageWithAddonsResponse extends TrackUsageResponse {
+    /** Usage deducted from plan allocation */
+    planUsage: number;
+    /** Usage deducted from addon credits */
+    addonUsage: number;
+}
+interface UsageAddon {
+    id: string;
+    appId: string;
+    metricId: string;
+    metricName: string;
+    name: string;
+    description?: string;
+    quantity: number;
+    priceCents: number;
+    currency: string;
+    status: 'active' | 'archived';
+    stripePriceId?: string;
+    createdAt: string;
+}
+interface UsageAddonPurchase {
+    id: string;
+    addonId: string;
+    addonName: string;
+    customerId: string;
+    metricId: string;
+    metricName: string;
+    quantity: number;
+    usedQuantity: number;
+    remainingQuantity: number;
+    priceCents: number;
+    currency: string;
+    billingPeriod: string;
+    expiresAt?: string;
+    createdAt: string;
+}
+interface CustomerCreditsResponse {
+    customerId: string;
+    metricName: string;
+    totalPurchased: number;
+    totalUsed: number;
+    remaining: number;
+    purchases: UsageAddonPurchase[];
+}
 interface CheckEntitlementResponse {
     /** Whether the customer has access to this feature */
     hasAccess: boolean;
@@ -409,6 +473,89 @@ declare class UsageClient {
     trackAndCheck(customerId: string, metric: string, options?: TrackUsageOptions): Promise<TrackUsageResponse & {
         allowed: boolean;
     }>;
+    /**
+     * Sync usage to an absolute value (instead of incrementing).
+     * Use this when your app tracks usage internally and reports the final count periodically.
+     *
+     * @example
+     * ```typescript
+     * // Your app tracks 847 billable tickets internally
+     * await stackbe.usage.sync('cust_123', 'tickets', 847);
+     * ```
+     */
+    sync(customerId: string, metric: string, value: number, options?: SyncUsageOptions): Promise<SyncUsageResponse>;
+    /**
+     * Check usage limits including purchased add-on credits.
+     *
+     * @example
+     * ```typescript
+     * const result = await stackbe.usage.checkWithAddons('cust_123', 'tickets');
+     *
+     * console.log(`Plan limit: ${result.planLimit}`);
+     * console.log(`Addon credits: ${result.addonCredits}`);
+     * console.log(`Effective limit: ${result.effectiveLimit}`);
+     *
+     * if (!result.allowed) {
+     *   // Prompt to purchase more credits
+     * }
+     * ```
+     */
+    checkWithAddons(customerId: string, metric: string): Promise<CheckUsageWithAddonsResponse>;
+    /**
+     * Track usage with automatic add-on credit deduction.
+     * When plan limit is exceeded, usage is deducted from purchased add-on credits.
+     *
+     * @example
+     * ```typescript
+     * const result = await stackbe.usage.trackWithAddons('cust_123', 'tickets');
+     *
+     * if (result.addonUsage > 0) {
+     *   console.log(`Used ${result.addonUsage} from addon credits`);
+     * }
+     * ```
+     */
+    trackWithAddons(customerId: string, metric: string, options?: TrackUsageOptions): Promise<TrackUsageWithAddonsResponse>;
+    /**
+     * List available add-on packs for purchase.
+     *
+     * @example
+     * ```typescript
+     * const addons = await stackbe.usage.listAddons();
+     *
+     * for (const addon of addons) {
+     *   console.log(`${addon.name}: ${addon.quantity} ${addon.metricName} for $${addon.priceCents / 100}`);
+     * }
+     * ```
+     */
+    listAddons(): Promise<UsageAddon[]>;
+    /**
+     * Purchase an add-on pack for a customer.
+     * Credits are immediately available after purchase.
+     *
+     * @example
+     * ```typescript
+     * // Purchase a 10k ticket pack
+     * const purchase = await stackbe.usage.purchaseAddon('cust_123', 'addon_xyz');
+     * console.log(`Purchased ${purchase.quantity} credits`);
+     * ```
+     */
+    purchaseAddon(customerId: string, addonId: string): Promise<UsageAddonPurchase>;
+    /**
+     * Get customer's purchased add-on credits for a metric.
+     *
+     * @example
+     * ```typescript
+     * const credits = await stackbe.usage.getCredits('cust_123', 'tickets');
+     *
+     * console.log(`Total purchased: ${credits.totalPurchased}`);
+     * console.log(`Remaining: ${credits.remaining}`);
+     *
+     * for (const purchase of credits.purchases) {
+     *   console.log(`${purchase.addonName}: ${purchase.remainingQuantity} left`);
+     * }
+     * ```
+     */
+    getCredits(customerId: string, metric: string): Promise<CustomerCreditsResponse>;
 }
 
 declare class EntitlementsClient {

package/dist/index.js

@@ -157,6 +157,9 @@ var HttpClient = class {
   async post(path, body, params) {
     return this.request("POST", path, { body, params });
   }
+  async put(path, body, params) {
+    return this.request("PUT", path, { body, params });
+  }
   async patch(path, body) {
     return this.request("PATCH", path, { body });
   }
@@ -256,6 +259,122 @@ var UsageClient = class {
       allowed
     };
   }
+  /**
+   * Sync usage to an absolute value (instead of incrementing).
+   * Use this when your app tracks usage internally and reports the final count periodically.
+   *
+   * @example
+   * ```typescript
+   * // Your app tracks 847 billable tickets internally
+   * await stackbe.usage.sync('cust_123', 'tickets', 847);
+   * ```
+   */
+  async sync(customerId, metric, value, options = {}) {
+    const headers = {};
+    if (options.idempotencyKey) {
+      headers["Idempotency-Key"] = options.idempotencyKey;
+    }
+    return this.http.put("/v1/usage/sync", {
+      customerId,
+      metric,
+      value
+    });
+  }
+  /**
+   * Check usage limits including purchased add-on credits.
+   *
+   * @example
+   * ```typescript
+   * const result = await stackbe.usage.checkWithAddons('cust_123', 'tickets');
+   *
+   * console.log(`Plan limit: ${result.planLimit}`);
+   * console.log(`Addon credits: ${result.addonCredits}`);
+   * console.log(`Effective limit: ${result.effectiveLimit}`);
+   *
+   * if (!result.allowed) {
+   *   // Prompt to purchase more credits
+   * }
+   * ```
+   */
+  async checkWithAddons(customerId, metric) {
+    return this.http.get(
+      `/v1/customers/${customerId}/usage/check-with-addons`,
+      { metric }
+    );
+  }
+  /**
+   * Track usage with automatic add-on credit deduction.
+   * When plan limit is exceeded, usage is deducted from purchased add-on credits.
+   *
+   * @example
+   * ```typescript
+   * const result = await stackbe.usage.trackWithAddons('cust_123', 'tickets');
+   *
+   * if (result.addonUsage > 0) {
+   *   console.log(`Used ${result.addonUsage} from addon credits`);
+   * }
+   * ```
+   */
+  async trackWithAddons(customerId, metric, options = {}) {
+    return this.http.post("/v1/usage/addons/track", {
+      customerId,
+      metric,
+      quantity: options.quantity ?? 1
+    });
+  }
+  /**
+   * List available add-on packs for purchase.
+   *
+   * @example
+   * ```typescript
+   * const addons = await stackbe.usage.listAddons();
+   *
+   * for (const addon of addons) {
+   *   console.log(`${addon.name}: ${addon.quantity} ${addon.metricName} for $${addon.priceCents / 100}`);
+   * }
+   * ```
+   */
+  async listAddons() {
+    return this.http.get("/v1/usage/addons");
+  }
+  /**
+   * Purchase an add-on pack for a customer.
+   * Credits are immediately available after purchase.
+   *
+   * @example
+   * ```typescript
+   * // Purchase a 10k ticket pack
+   * const purchase = await stackbe.usage.purchaseAddon('cust_123', 'addon_xyz');
+   * console.log(`Purchased ${purchase.quantity} credits`);
+   * ```
+   */
+  async purchaseAddon(customerId, addonId) {
+    return this.http.post("/v1/usage/addons/purchase", {
+      customerId,
+      addonId
+    });
+  }
+  /**
+   * Get customer's purchased add-on credits for a metric.
+   *
+   * @example
+   * ```typescript
+   * const credits = await stackbe.usage.getCredits('cust_123', 'tickets');
+   *
+   * console.log(`Total purchased: ${credits.totalPurchased}`);
+   * console.log(`Remaining: ${credits.remaining}`);
+   *
+   * for (const purchase of credits.purchases) {
+   *   console.log(`${purchase.addonName}: ${purchase.remainingQuantity} left`);
+   * }
+   * ```
+   */
+  async getCredits(customerId, metric) {
+    return this.http.get(
+      `/v1/customers/${customerId}/usage/credits`,
+      { metric }
+    );
+  }
 };
 
 // src/entitlements.ts

package/dist/index.mjs

@@ -124,6 +124,9 @@ var HttpClient = class {
   async post(path, body, params) {
     return this.request("POST", path, { body, params });
   }
+  async put(path, body, params) {
+    return this.request("PUT", path, { body, params });
+  }
   async patch(path, body) {
     return this.request("PATCH", path, { body });
   }
@@ -223,6 +226,122 @@ var UsageClient = class {
       allowed
     };
   }
+  /**
+   * Sync usage to an absolute value (instead of incrementing).
+   * Use this when your app tracks usage internally and reports the final count periodically.
+   *
+   * @example
+   * ```typescript
+   * // Your app tracks 847 billable tickets internally
+   * await stackbe.usage.sync('cust_123', 'tickets', 847);
+   * ```
+   */
+  async sync(customerId, metric, value, options = {}) {
+    const headers = {};
+    if (options.idempotencyKey) {
+      headers["Idempotency-Key"] = options.idempotencyKey;
+    }
+    return this.http.put("/v1/usage/sync", {
+      customerId,
+      metric,
+      value
+    });
+  }
+  /**
+   * Check usage limits including purchased add-on credits.
+   *
+   * @example
+   * ```typescript
+   * const result = await stackbe.usage.checkWithAddons('cust_123', 'tickets');
+   *
+   * console.log(`Plan limit: ${result.planLimit}`);
+   * console.log(`Addon credits: ${result.addonCredits}`);
+   * console.log(`Effective limit: ${result.effectiveLimit}`);
+   *
+   * if (!result.allowed) {
+   *   // Prompt to purchase more credits
+   * }
+   * ```
+   */
+  async checkWithAddons(customerId, metric) {
+    return this.http.get(
+      `/v1/customers/${customerId}/usage/check-with-addons`,
+      { metric }
+    );
+  }
+  /**
+   * Track usage with automatic add-on credit deduction.
+   * When plan limit is exceeded, usage is deducted from purchased add-on credits.
+   *
+   * @example
+   * ```typescript
+   * const result = await stackbe.usage.trackWithAddons('cust_123', 'tickets');
+   *
+   * if (result.addonUsage > 0) {
+   *   console.log(`Used ${result.addonUsage} from addon credits`);
+   * }
+   * ```
+   */
+  async trackWithAddons(customerId, metric, options = {}) {
+    return this.http.post("/v1/usage/addons/track", {
+      customerId,
+      metric,
+      quantity: options.quantity ?? 1
+    });
+  }
+  /**
+   * List available add-on packs for purchase.
+   *
+   * @example
+   * ```typescript
+   * const addons = await stackbe.usage.listAddons();
+   *
+   * for (const addon of addons) {
+   *   console.log(`${addon.name}: ${addon.quantity} ${addon.metricName} for $${addon.priceCents / 100}`);
+   * }
+   * ```
+   */
+  async listAddons() {
+    return this.http.get("/v1/usage/addons");
+  }
+  /**
+   * Purchase an add-on pack for a customer.
+   * Credits are immediately available after purchase.
+   *
+   * @example
+   * ```typescript
+   * // Purchase a 10k ticket pack
+   * const purchase = await stackbe.usage.purchaseAddon('cust_123', 'addon_xyz');
+   * console.log(`Purchased ${purchase.quantity} credits`);
+   * ```
+   */
+  async purchaseAddon(customerId, addonId) {
+    return this.http.post("/v1/usage/addons/purchase", {
+      customerId,
+      addonId
+    });
+  }
+  /**
+   * Get customer's purchased add-on credits for a metric.
+   *
+   * @example
+   * ```typescript
+   * const credits = await stackbe.usage.getCredits('cust_123', 'tickets');
+   *
+   * console.log(`Total purchased: ${credits.totalPurchased}`);
+   * console.log(`Remaining: ${credits.remaining}`);
+   *
+   * for (const purchase of credits.purchases) {
+   *   console.log(`${purchase.addonName}: ${purchase.remainingQuantity} left`);
+   * }
+   * ```
+   */
+  async getCredits(customerId, metric) {
+    return this.http.get(
+      `/v1/customers/${customerId}/usage/credits`,
+      { metric }
+    );
+  }
 };
 
 // src/entitlements.ts

package/package.json

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