@stackbe/sdk 0.3.0 → 0.4.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

@@ -24,6 +24,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) */
@@ -691,13 +715,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 +756,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 +796,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

@@ -24,6 +24,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) */
@@ -691,13 +715,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 +756,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 +796,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

@@ -697,13 +697,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 +741,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 +840,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 +862,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 +883,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 +898,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 +910,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 +1032,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

@@ -664,13 +664,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 +708,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 +807,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 +829,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 +850,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 +865,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 +877,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 +999,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.4.0",
   "description": "Official JavaScript/TypeScript SDK for StackBE - the billing backend for your side project",
   "main": "dist/index.js",
   "module": "dist/index.mjs",