feat(cache): add per-endpoint TTL configuration for API caching

Add ability to configure different cache TTLs for different endpoints:
- Support both single TTL (backward compatible) and per-endpoint config
- Add recommended TTLs: organizations (30 min), quota (10 min)
- Implement cache instance pooling to support multiple TTL values
- Maintain backward compatibility with existing cacheTtl number param

This reduces unnecessary API calls for rarely-changing data like
organization lists while keeping more dynamic data like quotas fresher.

Example usage:
```typescript
const sdk = new SocketSdk(token, {
  cache: true,
  cacheTtl: {
    default: 5 * 60 * 1000,        // 5 minutes
    organizations: 30 * 60 * 1000, // 30 minutes
    quota: 10 * 60 * 1000          // 10 minutes
  }
});
```

Author: jdalton

src/constants.ts

@@ -26,6 +26,17 @@ export const DEFAULT_RETRIES = 3
 // Default delay before first retry (milliseconds)
 export const DEFAULT_RETRY_DELAY = 1000
 
+// Default cache TTL (5 minutes)
+export const DEFAULT_CACHE_TTL = 5 * 60 * 1000
+
+// Recommended cache TTL for organizations endpoint (30 minutes)
+// Organizations list rarely changes - only when joining/leaving orgs.
+export const RECOMMENDED_CACHE_TTL_ORGANIZATIONS = 30 * 60 * 1000
+
+// Recommended cache TTL for quota endpoint (10 minutes)
+// Quota changes incrementally and doesn't need real-time accuracy.
+export const RECOMMENDED_CACHE_TTL_QUOTA = 10 * 60 * 1000
+
 // Maximum timeout for HTTP requests (5 minutes)
 export const MAX_HTTP_TIMEOUT = 5 * 60 * 1000
 

src/socket-sdk-class.ts

@@ -20,6 +20,7 @@ import { urlSearchParamAsBoolean } from '@socketsecurity/lib/url'
 const abortSignal = getAbortSignal()
 
 import {
+  DEFAULT_CACHE_TTL,
   DEFAULT_HTTP_TIMEOUT,
   DEFAULT_RETRIES,
   DEFAULT_RETRY_DELAY,
@@ -116,6 +117,8 @@ export class SocketSdk {
   readonly #apiToken: string
   readonly #baseUrl: string
   readonly #cache: TtlCache | undefined
+  readonly #cacheByTtl: Map<number, TtlCache>
+  readonly #cacheTtlConfig: SocketSdkOptions['cacheTtl']
   readonly #hooks: SocketSdkOptions['hooks']
   readonly #onFileValidation: FileValidationCallback | undefined
   readonly #reqOptions: RequestOptions
@@ -146,7 +149,7 @@ export class SocketSdk {
       agent: agentOrObj,
       baseUrl = 'https://api.socket.dev/v0/',
       cache = false,
-      cacheTtl = 5 * 60 * 1000,
+      cacheTtl,
       hooks,
       onFileValidation,
       retries = DEFAULT_RETRIES,
@@ -180,13 +183,22 @@ export class SocketSdk {
     ) as Agent | undefined
     this.#apiToken = trimmedToken
     this.#baseUrl = normalizeBaseUrl(baseUrl)
+    this.#cacheTtlConfig = cacheTtl
+    // For backward compatibility, if cacheTtl is a number, use it as default TTL.
+    // If it's an object, use the default property or fallback to DEFAULT_CACHE_TTL.
+    const defaultTtl =
+      typeof cacheTtl === 'number'
+        ? cacheTtl
+        : (cacheTtl?.default ?? DEFAULT_CACHE_TTL)
     this.#cache = cache
       ? createTtlCache({
           memoize: true,
           prefix: 'socket-sdk',
-          ttl: cacheTtl,
+          ttl: defaultTtl,
         })
       : /* c8 ignore next - cache disabled by default */ undefined
+    // Map of TTL values to cache instances for per-endpoint caching.
+    this.#cacheByTtl = new Map()
     this.#hooks = hooks
     this.#onFileValidation = onFileValidation
     this.#retries = retries
@@ -366,18 +378,74 @@ export class SocketSdk {
     return result
   }
 
+  /**
+   * Get the TTL for a specific endpoint.
+   * Returns endpoint-specific TTL if configured, otherwise returns default TTL.
+   */
+  #getTtlForEndpoint(endpoint: string): number | undefined {
+    const cacheTtl = this.#cacheTtlConfig
+    if (typeof cacheTtl === 'number') {
+      return cacheTtl
+    }
+    if (cacheTtl && typeof cacheTtl === 'object') {
+      // Check for endpoint-specific TTL first.
+      const endpointTtl = (cacheTtl as any)[endpoint]
+      if (typeof endpointTtl === 'number') {
+        return endpointTtl
+      }
+      // Fall back to default.
+      return cacheTtl.default
+    }
+    return undefined
+  }
+
+  /**
+   * Get or create a cache instance with the specified TTL.
+   * Reuses existing cache instances to avoid creating duplicates.
+   */
+  #getCacheForTtl(ttl: number): TtlCache {
+    let cache = this.#cacheByTtl.get(ttl)
+    if (!cache) {
+      cache = createTtlCache({
+        memoize: true,
+        prefix: 'socket-sdk',
+        ttl,
+      })
+      this.#cacheByTtl.set(ttl, cache)
+    }
+    return cache
+  }
+
   /**
    * Execute a GET request with optional caching.
    * Internal method for handling cached GET requests with retry logic.
+   * Supports per-endpoint TTL configuration.
    */
-  async #getCached<T>(cacheKey: string, fetcher: () => Promise<T>): Promise<T> {
+  async #getCached<T>(
+    cacheKey: string,
+    fetcher: () => Promise<T>,
+    endpointName?: string | undefined,
+  ): Promise<T> {
     // If caching is disabled, just execute the request.
     if (!this.#cache) {
       return await this.#executeWithRetry(fetcher)
     }
 
+    // Get endpoint-specific TTL if provided.
+    const endpointTtl = endpointName
+      ? this.#getTtlForEndpoint(endpointName)
+      : undefined
+
+    // Select the appropriate cache instance.
+    // If endpoint has custom TTL, get/create cache for that TTL.
+    // Otherwise use the default cache.
+    const cacheToUse =
+      endpointTtl !== undefined
+        ? this.#getCacheForTtl(endpointTtl)
+        : this.#cache
+
     // Use cache with retry logic.
-    return await this.#cache.getOrFetch(cacheKey, async () => {
+    return await cacheToUse.getOrFetch(cacheKey, async () => {
       return await this.#executeWithRetry(fetcher)
     })
   }
@@ -1789,6 +1857,7 @@ export class SocketSdk {
               this.#hooks,
             ),
           ),
+        'organizations',
       )
       return {
         cause: undefined,
@@ -2370,6 +2439,7 @@ export class SocketSdk {
               this.#hooks,
             ),
           ),
+        'quota',
       )
       return this.#handleApiSuccess<'getQuota'>(data)
       /* c8 ignore start - Standard API error handling, tested via public method error cases */

src/types.ts

@@ -302,14 +302,39 @@ export interface SocketSdkOptions {
   baseUrl?: string | undefined
   /**
    * Enable TTL caching for API responses (default: false).
-   * When enabled, GET requests are cached with a 5-minute TTL.
+   * When enabled, GET requests are cached with configurable TTLs.
+   * Only applies to listOrganizations() and getQuota() methods.
    */
   cache?: boolean | undefined
   /**
    * Cache TTL in milliseconds (default: 300_000 = 5 minutes).
    * Only used when cache is enabled.
+   * Can be a single number for all endpoints or an object for per-endpoint TTLs.
+   *
+   * Recommended TTLs by endpoint:
+   * - organizations: 30 minutes (rarely changes)
+   * - quota: 10 minutes (changes incrementally)
+   *
+   * @example
+   * // Single TTL for all endpoints.
+   * cacheTtl: 15 * 60 * 1000  // 15 minutes
+   *
+   * @example
+   * // Per-endpoint TTLs with recommended values.
+   * cacheTtl: {
+   *   default: 5 * 60 * 1000,        // 5 minutes default
+   *   organizations: 30 * 60 * 1000, // 30 minutes (recommended)
+   *   quota: 10 * 60 * 1000          // 10 minutes (recommended)
+   * }
    */
-  cacheTtl?: number | undefined
+  cacheTtl?:
+    | number
+    | {
+        default?: number | undefined
+        organizations?: number | undefined
+        quota?: number | undefined
+      }
+    | undefined
   /**
    * Callback for file validation events.
    * Called when any file-upload method detects unreadable files: