@stackbe/sdk 0.3.0 → 0.5.0

package/README.md

@@ -392,6 +392,54 @@ const stackbe = new StackBE({
   appId: 'app_...',                // Required: Your App ID
   baseUrl: 'https://api.stackbe.io', // Optional: API base URL
   timeout: 30000,                   // Optional: Request timeout in ms
+
+  // Session caching (reduces API calls)
+  sessionCacheTTL: 120,            // Optional: Cache sessions for 2 minutes
+
+  // Environment-aware redirects
+  devCallbackUrl: 'http://localhost:3000/auth/callback', // Optional: Auto-use in dev
+});
+```
+
+### Session Caching
+
+Enable session caching to reduce API calls on every request:
+
+```typescript
+const stackbe = new StackBE({
+  apiKey,
+  appId,
+  sessionCacheTTL: 120, // Cache for 2 minutes
+});
+
+// Cached calls won't hit the API
+const session1 = await stackbe.auth.getSession(token); // API call
+const session2 = await stackbe.auth.getSession(token); // From cache
+
+// Manually invalidate cache
+stackbe.auth.invalidateSession(token);
+stackbe.auth.clearCache(); // Clear all
+```
+
+### Environment-Aware Redirects
+
+Auto-detect development environment for magic link redirects:
+
+```typescript
+const stackbe = new StackBE({
+  apiKey,
+  appId,
+  devCallbackUrl: 'http://localhost:3000/auth/callback',
+});
+
+// In development (NODE_ENV !== 'production'), uses devCallbackUrl automatically
+await stackbe.auth.sendMagicLink('user@example.com');
+// Redirects to: http://localhost:3000/auth/callback
+
+// In production, uses your configured auth callback URL
+// Or pass explicit redirectUrl to override
+await stackbe.auth.sendMagicLink('user@example.com', {
+  redirectUrl: 'https://myapp.com/custom-callback',
 });
 ```
 

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>;
 }
@@ -24,6 +25,30 @@ interface StackBEConfig {
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /**
+     * Session cache TTL in seconds (default: 0 = disabled).
+     * When set, getSession() results are cached to reduce API calls.
+     * @example
+     * ```typescript
+     * new StackBE({ apiKey, appId, sessionCacheTTL: 120 }) // Cache for 2 minutes
+     * ```
+     */
+    sessionCacheTTL?: number;
+    /**
+     * Development callback URL for magic link redirects.
+     * When set, this URL is used automatically when:
+     * - NODE_ENV !== 'production', or
+     * - useDev: true is passed to sendMagicLink()
+     * @example
+     * ```typescript
+     * new StackBE({
+     *   apiKey,
+     *   appId,
+     *   devCallbackUrl: 'http://localhost:3000/auth/callback'
+     * })
+     * ```
+     */
+    devCallbackUrl?: string;
 }
 interface TrackUsageOptions {
     /** Quantity to track (default: 1) */
@@ -65,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;
@@ -385,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 {
@@ -691,13 +862,37 @@ declare class SubscriptionsClient {
     isActive(customerId: string): Promise<boolean>;
 }
 
+interface AuthClientOptions {
+    /** Session cache TTL in seconds (0 = disabled) */
+    sessionCacheTTL?: number;
+    /** Development callback URL for magic links */
+    devCallbackUrl?: string;
+}
 declare class AuthClient {
     private http;
     private appId;
-    constructor(http: HttpClient, appId: string);
+    private sessionCache;
+    private sessionCacheTTL;
+    private devCallbackUrl?;
+    constructor(http: HttpClient, appId: string, options?: AuthClientOptions);
+    /**
+     * Check if we're in a development environment.
+     */
+    private isDev;
+    /**
+     * Clear the session cache (useful for testing or logout).
+     */
+    clearCache(): void;
+    /**
+     * Remove a specific session from the cache.
+     */
+    invalidateSession(sessionToken: string): void;
     /**
      * Send a magic link email to a customer for passwordless authentication.
      *
+     * If `devCallbackUrl` is configured and we're in a dev environment (NODE_ENV !== 'production'),
+     * the dev callback URL will be used automatically.
+     *
      * @example
      * ```typescript
      * // Send magic link
@@ -708,7 +903,7 @@ declare class AuthClient {
      *   redirectUrl: 'https://myapp.com/dashboard',
      * });
      *
-     * // For localhost development
+     * // For localhost development (auto-detected if devCallbackUrl is configured)
      * await stackbe.auth.sendMagicLink('user@example.com', {
      *   useDev: true,
      * });
@@ -748,6 +943,9 @@ declare class AuthClient {
      * Get the current session for an authenticated customer.
      * Use this to validate session tokens and get customer data.
      *
+     * If `sessionCacheTTL` is configured, results are cached to reduce API calls.
+     * Use `invalidateSession()` or `clearCache()` to manually clear cached sessions.
+     *
      * Returns session info including tenant and organization context extracted from the JWT.
      *
      * @example

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>;
 }
@@ -24,6 +25,30 @@ interface StackBEConfig {
     baseUrl?: string;
     /** Request timeout in milliseconds (default: 30000) */
     timeout?: number;
+    /**
+     * Session cache TTL in seconds (default: 0 = disabled).
+     * When set, getSession() results are cached to reduce API calls.
+     * @example
+     * ```typescript
+     * new StackBE({ apiKey, appId, sessionCacheTTL: 120 }) // Cache for 2 minutes
+     * ```
+     */
+    sessionCacheTTL?: number;
+    /**
+     * Development callback URL for magic link redirects.
+     * When set, this URL is used automatically when:
+     * - NODE_ENV !== 'production', or
+     * - useDev: true is passed to sendMagicLink()
+     * @example
+     * ```typescript
+     * new StackBE({
+     *   apiKey,
+     *   appId,
+     *   devCallbackUrl: 'http://localhost:3000/auth/callback'
+     * })
+     * ```
+     */
+    devCallbackUrl?: string;
 }
 interface TrackUsageOptions {
     /** Quantity to track (default: 1) */
@@ -65,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;
@@ -385,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 {
@@ -691,13 +862,37 @@ declare class SubscriptionsClient {
     isActive(customerId: string): Promise<boolean>;
 }
 
+interface AuthClientOptions {
+    /** Session cache TTL in seconds (0 = disabled) */
+    sessionCacheTTL?: number;
+    /** Development callback URL for magic links */
+    devCallbackUrl?: string;
+}
 declare class AuthClient {
     private http;
     private appId;
-    constructor(http: HttpClient, appId: string);
+    private sessionCache;
+    private sessionCacheTTL;
+    private devCallbackUrl?;
+    constructor(http: HttpClient, appId: string, options?: AuthClientOptions);
+    /**
+     * Check if we're in a development environment.
+     */
+    private isDev;
+    /**
+     * Clear the session cache (useful for testing or logout).
+     */
+    clearCache(): void;
+    /**
+     * Remove a specific session from the cache.
+     */
+    invalidateSession(sessionToken: string): void;
     /**
      * Send a magic link email to a customer for passwordless authentication.
      *
+     * If `devCallbackUrl` is configured and we're in a dev environment (NODE_ENV !== 'production'),
+     * the dev callback URL will be used automatically.
+     *
      * @example
      * ```typescript
      * // Send magic link
@@ -708,7 +903,7 @@ declare class AuthClient {
      *   redirectUrl: 'https://myapp.com/dashboard',
      * });
      *
-     * // For localhost development
+     * // For localhost development (auto-detected if devCallbackUrl is configured)
      * await stackbe.auth.sendMagicLink('user@example.com', {
      *   useDev: true,
      * });
@@ -748,6 +943,9 @@ declare class AuthClient {
      * Get the current session for an authenticated customer.
      * Use this to validate session tokens and get customer data.
      *
+     * If `sessionCacheTTL` is configured, results are cached to reduce API calls.
+     * Use `invalidateSession()` or `clearCache()` to manually clear cached sessions.
+     *
      * Returns session info including tenant and organization context extracted from the JWT.
      *
      * @example

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
@@ -697,13 +816,40 @@ function decodeJwt(token) {
   }
 }
 var AuthClient = class {
-  constructor(http, appId) {
+  constructor(http, appId, options = {}) {
     this.http = http;
     this.appId = appId;
+    this.sessionCache = /* @__PURE__ */ new Map();
+    this.sessionCacheTTL = (options.sessionCacheTTL ?? 0) * 1e3;
+    this.devCallbackUrl = options.devCallbackUrl;
+  }
+  /**
+   * Check if we're in a development environment.
+   */
+  isDev() {
+    if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Clear the session cache (useful for testing or logout).
+   */
+  clearCache() {
+    this.sessionCache.clear();
+  }
+  /**
+   * Remove a specific session from the cache.
+   */
+  invalidateSession(sessionToken) {
+    this.sessionCache.delete(sessionToken);
   }
   /**
    * Send a magic link email to a customer for passwordless authentication.
    *
+   * If `devCallbackUrl` is configured and we're in a dev environment (NODE_ENV !== 'production'),
+   * the dev callback URL will be used automatically.
+   *
    * @example
    * ```typescript
    * // Send magic link
@@ -714,19 +860,26 @@ var AuthClient = class {
    *   redirectUrl: 'https://myapp.com/dashboard',
    * });
    *
-   * // For localhost development
+   * // For localhost development (auto-detected if devCallbackUrl is configured)
    * await stackbe.auth.sendMagicLink('user@example.com', {
    *   useDev: true,
    * });
    * ```
    */
   async sendMagicLink(email, options = {}) {
+    let useDev = options.useDev;
+    let redirectUrl = options.redirectUrl;
+    if (!redirectUrl && this.devCallbackUrl) {
+      if (useDev || this.isDev()) {
+        redirectUrl = this.devCallbackUrl;
+      }
+    }
     return this.http.post(
       `/v1/apps/${this.appId}/auth/magic-link`,
       {
         email,
-        redirectUrl: options.redirectUrl,
-        useDev: options.useDev
+        redirectUrl,
+        useDev
       }
     );
   }
@@ -806,6 +959,9 @@ var AuthClient = class {
    * Get the current session for an authenticated customer.
    * Use this to validate session tokens and get customer data.
    *
+   * If `sessionCacheTTL` is configured, results are cached to reduce API calls.
+   * Use `invalidateSession()` or `clearCache()` to manually clear cached sessions.
+   *
    * Returns session info including tenant and organization context extracted from the JWT.
    *
    * @example
@@ -825,6 +981,15 @@ var AuthClient = class {
    * ```
    */
   async getSession(sessionToken) {
+    if (this.sessionCacheTTL > 0) {
+      const cached = this.sessionCache.get(sessionToken);
+      if (cached && cached.expiresAt > Date.now()) {
+        return cached.session;
+      }
+      if (cached) {
+        this.sessionCache.delete(sessionToken);
+      }
+    }
     try {
       const response = await fetch(
         `${this.http.baseUrl}/v1/apps/${this.appId}/auth/session`,
@@ -837,6 +1002,7 @@ var AuthClient = class {
       );
       if (!response.ok) {
         if (response.status === 401) {
+          this.sessionCache.delete(sessionToken);
           return null;
         }
         throw new StackBEError("Failed to get session", response.status, "SESSION_INVALID");
@@ -851,7 +1017,7 @@ var AuthClient = class {
         organizationId = payload.organizationId;
         orgRole = payload.orgRole;
       }
-      return {
+      const session = {
         valid: data.valid ?? true,
         customerId: data.customerId,
         email: data.email,
@@ -863,6 +1029,13 @@ var AuthClient = class {
         subscription: data.subscription,
         entitlements: data.entitlements
       };
+      if (this.sessionCacheTTL > 0) {
+        this.sessionCache.set(sessionToken, {
+          session,
+          expiresAt: Date.now() + this.sessionCacheTTL
+        });
+      }
+      return session;
     } catch (error) {
       if (error instanceof StackBEError) {
         throw error;
@@ -978,7 +1151,10 @@ var StackBE = class {
     this.customers = new CustomersClient(this.http);
     this.checkout = new CheckoutClient(this.http, config.appId);
     this.subscriptions = new SubscriptionsClient(this.http);
-    this.auth = new AuthClient(this.http, config.appId);
+    this.auth = new AuthClient(this.http, config.appId, {
+      sessionCacheTTL: config.sessionCacheTTL,
+      devCallbackUrl: config.devCallbackUrl
+    });
   }
   /**
    * Create a middleware for Express that tracks usage automatically.

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
@@ -664,13 +783,40 @@ function decodeJwt(token) {
   }
 }
 var AuthClient = class {
-  constructor(http, appId) {
+  constructor(http, appId, options = {}) {
     this.http = http;
     this.appId = appId;
+    this.sessionCache = /* @__PURE__ */ new Map();
+    this.sessionCacheTTL = (options.sessionCacheTTL ?? 0) * 1e3;
+    this.devCallbackUrl = options.devCallbackUrl;
+  }
+  /**
+   * Check if we're in a development environment.
+   */
+  isDev() {
+    if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production") {
+      return true;
+    }
+    return false;
+  }
+  /**
+   * Clear the session cache (useful for testing or logout).
+   */
+  clearCache() {
+    this.sessionCache.clear();
+  }
+  /**
+   * Remove a specific session from the cache.
+   */
+  invalidateSession(sessionToken) {
+    this.sessionCache.delete(sessionToken);
   }
   /**
    * Send a magic link email to a customer for passwordless authentication.
    *
+   * If `devCallbackUrl` is configured and we're in a dev environment (NODE_ENV !== 'production'),
+   * the dev callback URL will be used automatically.
+   *
    * @example
    * ```typescript
    * // Send magic link
@@ -681,19 +827,26 @@ var AuthClient = class {
    *   redirectUrl: 'https://myapp.com/dashboard',
    * });
    *
-   * // For localhost development
+   * // For localhost development (auto-detected if devCallbackUrl is configured)
    * await stackbe.auth.sendMagicLink('user@example.com', {
    *   useDev: true,
    * });
    * ```
    */
   async sendMagicLink(email, options = {}) {
+    let useDev = options.useDev;
+    let redirectUrl = options.redirectUrl;
+    if (!redirectUrl && this.devCallbackUrl) {
+      if (useDev || this.isDev()) {
+        redirectUrl = this.devCallbackUrl;
+      }
+    }
     return this.http.post(
       `/v1/apps/${this.appId}/auth/magic-link`,
       {
         email,
-        redirectUrl: options.redirectUrl,
-        useDev: options.useDev
+        redirectUrl,
+        useDev
       }
     );
   }
@@ -773,6 +926,9 @@ var AuthClient = class {
    * Get the current session for an authenticated customer.
    * Use this to validate session tokens and get customer data.
    *
+   * If `sessionCacheTTL` is configured, results are cached to reduce API calls.
+   * Use `invalidateSession()` or `clearCache()` to manually clear cached sessions.
+   *
    * Returns session info including tenant and organization context extracted from the JWT.
    *
    * @example
@@ -792,6 +948,15 @@ var AuthClient = class {
    * ```
    */
   async getSession(sessionToken) {
+    if (this.sessionCacheTTL > 0) {
+      const cached = this.sessionCache.get(sessionToken);
+      if (cached && cached.expiresAt > Date.now()) {
+        return cached.session;
+      }
+      if (cached) {
+        this.sessionCache.delete(sessionToken);
+      }
+    }
     try {
       const response = await fetch(
         `${this.http.baseUrl}/v1/apps/${this.appId}/auth/session`,
@@ -804,6 +969,7 @@ var AuthClient = class {
       );
       if (!response.ok) {
         if (response.status === 401) {
+          this.sessionCache.delete(sessionToken);
           return null;
         }
         throw new StackBEError("Failed to get session", response.status, "SESSION_INVALID");
@@ -818,7 +984,7 @@ var AuthClient = class {
         organizationId = payload.organizationId;
         orgRole = payload.orgRole;
       }
-      return {
+      const session = {
         valid: data.valid ?? true,
         customerId: data.customerId,
         email: data.email,
@@ -830,6 +996,13 @@ var AuthClient = class {
         subscription: data.subscription,
         entitlements: data.entitlements
       };
+      if (this.sessionCacheTTL > 0) {
+        this.sessionCache.set(sessionToken, {
+          session,
+          expiresAt: Date.now() + this.sessionCacheTTL
+        });
+      }
+      return session;
     } catch (error) {
       if (error instanceof StackBEError) {
         throw error;
@@ -945,7 +1118,10 @@ var StackBE = class {
     this.customers = new CustomersClient(this.http);
     this.checkout = new CheckoutClient(this.http, config.appId);
     this.subscriptions = new SubscriptionsClient(this.http);
-    this.auth = new AuthClient(this.http, config.appId);
+    this.auth = new AuthClient(this.http, config.appId, {
+      sessionCacheTTL: config.sessionCacheTTL,
+      devCallbackUrl: config.devCallbackUrl
+    });
   }
   /**
    * Create a middleware for Express that tracks usage automatically.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbe/sdk",
-  "version": "0.3.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",