@socketsecurity/sdk 1.10.1 → 1.11.0

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [1.11.0](https://github.com/SocketDev/socket-sdk-js/releases/tag/v1.11.0) - 2025-10-04
+
+### Added
+- Optional TTL caching for API responses with configurable cache duration
+- New `cache` option (default: false) to enable response caching
+- New `cacheTtl` option (default: 5 minutes) to customize cache duration
+
 ## [1.10.1](https://github.com/SocketDev/socket-sdk-js/releases/tag/v1.10.1) - 2025-10-04
 
 ### Added

package/README.md

@@ -20,8 +20,8 @@ pnpm add @socketsecurity/sdk
 import { SocketSdk } from '@socketsecurity/sdk'
 
 const client = new SocketSdk('yourApiKeyHere', {
-  retries: 3,        // Retry failed requests up to 3 times (default: 3)
-  retryDelay: 1000,  // Start with 1s delay, exponential backoff (default: 1000ms)
+  retries: 3,        // Retry failed requests up to 3 times (default: 0, disabled)
+  retryDelay: 1000,  // Start with 1s delay, exponential backoff (default: 100ms)
   timeout: 30000,    // Request timeout in milliseconds (optional)
 })
 
@@ -41,18 +41,19 @@ The SDK constructor accepts the following options:
 interface SocketSdkOptions {
   baseUrl?: string          // API base URL (default: 'https://api.socket.dev/v0/')
   timeout?: number          // Request timeout in milliseconds
-  retries?: number          // Number of retry attempts for failed requests (default: 3)
-  retryDelay?: number       // Initial retry delay in ms, with exponential backoff (default: 1000)
+  retries?: number          // Number of retry attempts for failed requests (default: 0, disabled)
+  retryDelay?: number       // Initial retry delay in ms, with exponential backoff (default: 100)
   userAgent?: string        // Custom user agent string
   agent?: Agent             // Custom HTTP agent for advanced networking
 }
 ```
 
 **Retry Logic:**
-- Automatically retries transient network errors and 5xx server responses
-- Uses exponential backoff: 1s, 2s, 4s, 8s... (configurable via `retryDelay`)
+- **Disabled by default** (opt-in pattern following Node.js fs.rm() convention)
+- Set `retries: 3` (recommended for production) to enable automatic retries
+- Retries transient network errors and 5xx server responses
+- Uses exponential backoff: 100ms, 200ms, 400ms, 800ms... (configurable via `retryDelay`)
 - Does NOT retry 401/403 authentication errors (immediate failure)
-- Set `retries: 0` to disable retry logic entirely
 
 ### Quota Management Example
 

package/dist/http-client.d.ts

@@ -81,8 +81,8 @@ export declare function reshapeArtifactForPublicPolicy<T extends Record<string,
  * Wraps any async HTTP function and retries on failure.
  *
  * @param fn - Async function to retry
- * @param retries - Number of retry attempts (default: 3)
- * @param retryDelay - Initial delay in ms (default: 1000)
+ * @param retries - Number of retry attempts (default: 0, retries disabled)
+ * @param retryDelay - Initial delay in ms (default: 100)
  * @returns Result of the function call
  * @throws {Error} Last error if all retries exhausted
  */
@@ -91,23 +91,23 @@ export declare function withRetry<T>(fn: () => Promise<T>, retries?: number, ret
  * Create GET request with automatic retry logic.
  * Retries on network errors and 5xx responses.
  *
- * @param retries - Number of retry attempts (default: 3)
- * @param retryDelay - Initial delay in ms (default: 1000)
+ * @param retries - Number of retry attempts (default: 0, retries disabled)
+ * @param retryDelay - Initial delay in ms (default: 100)
  */
 export declare function createGetRequestWithRetry(baseUrl: string, urlPath: string, options: RequestOptions, retries?: number, retryDelay?: number): Promise<IncomingMessage>;
 /**
  * Create DELETE request with automatic retry logic.
  * Retries on network errors and 5xx responses.
  *
- * @param retries - Number of retry attempts (default: 3)
- * @param retryDelay - Initial delay in ms (default: 1000)
+ * @param retries - Number of retry attempts (default: 0, retries disabled)
+ * @param retryDelay - Initial delay in ms (default: 100)
  */
 export declare function createDeleteRequestWithRetry(baseUrl: string, urlPath: string, options: RequestOptions, retries?: number, retryDelay?: number): Promise<IncomingMessage>;
 /**
  * Create request with JSON payload and automatic retry logic.
  * Retries on network errors and 5xx responses.
  *
- * @param retries - Number of retry attempts (default: 3)
- * @param retryDelay - Initial delay in ms (default: 1000)
+ * @param retries - Number of retry attempts (default: 0, retries disabled)
+ * @param retryDelay - Initial delay in ms (default: 100)
  */
 export declare function createRequestWithJsonAndRetry(method: SendMethod, baseUrl: string, urlPath: string, json: unknown, options: RequestOptions, retries?: number, retryDelay?: number): Promise<IncomingMessage>;

package/dist/http-client.js

@@ -273,12 +273,12 @@ function reshapeArtifactForPublicPolicy(data, isAuthenticated, actions) {
  * Wraps any async HTTP function and retries on failure.
  *
  * @param fn - Async function to retry
- * @param retries - Number of retry attempts (default: 3)
- * @param retryDelay - Initial delay in ms (default: 1000)
+ * @param retries - Number of retry attempts (default: 0, retries disabled)
+ * @param retryDelay - Initial delay in ms (default: 100)
  * @returns Result of the function call
  * @throws {Error} Last error if all retries exhausted
  */
-async function withRetry(fn, retries = 3, retryDelay = 1000) {
+async function withRetry(fn, retries = 0, retryDelay = 100) {
     let lastError;
     for (let attempt = 0; attempt <= retries; attempt++) {
         try {
@@ -319,29 +319,29 @@ async function withRetry(fn, retries = 3, retryDelay = 1000) {
  * Create GET request with automatic retry logic.
  * Retries on network errors and 5xx responses.
  *
- * @param retries - Number of retry attempts (default: 3)
- * @param retryDelay - Initial delay in ms (default: 1000)
+ * @param retries - Number of retry attempts (default: 0, retries disabled)
+ * @param retryDelay - Initial delay in ms (default: 100)
  */
-async function createGetRequestWithRetry(baseUrl, urlPath, options, retries = 3, retryDelay = 1000) {
+async function createGetRequestWithRetry(baseUrl, urlPath, options, retries = 0, retryDelay = 100) {
     return await withRetry(() => createGetRequest(baseUrl, urlPath, options), retries, retryDelay);
 }
 /**
  * Create DELETE request with automatic retry logic.
  * Retries on network errors and 5xx responses.
  *
- * @param retries - Number of retry attempts (default: 3)
- * @param retryDelay - Initial delay in ms (default: 1000)
+ * @param retries - Number of retry attempts (default: 0, retries disabled)
+ * @param retryDelay - Initial delay in ms (default: 100)
  */
-async function createDeleteRequestWithRetry(baseUrl, urlPath, options, retries = 3, retryDelay = 1000) {
+async function createDeleteRequestWithRetry(baseUrl, urlPath, options, retries = 0, retryDelay = 100) {
     return await withRetry(() => createDeleteRequest(baseUrl, urlPath, options), retries, retryDelay);
 }
 /**
  * Create request with JSON payload and automatic retry logic.
  * Retries on network errors and 5xx responses.
  *
- * @param retries - Number of retry attempts (default: 3)
- * @param retryDelay - Initial delay in ms (default: 1000)
+ * @param retries - Number of retry attempts (default: 0, retries disabled)
+ * @param retryDelay - Initial delay in ms (default: 100)
  */
-async function createRequestWithJsonAndRetry(method, baseUrl, urlPath, json, options, retries = 3, retryDelay = 1000) {
+async function createRequestWithJsonAndRetry(method, baseUrl, urlPath, json, options, retries = 0, retryDelay = 100) {
     return await withRetry(() => createRequestWithJson(method, baseUrl, urlPath, json, options), retries, retryDelay);
 }

package/dist/socket-sdk-class.d.ts

@@ -8,7 +8,7 @@ export declare class SocketSdk {
     #private;
     /**
      * Initialize Socket SDK with API token and configuration options.
-     * Sets up authentication, base URL, HTTP client options, and retry behavior.
+     * Sets up authentication, base URL, HTTP client options, retry behavior, and caching.
      */
     constructor(apiToken: string, options?: SocketSdkOptions | undefined);
     /**

package/dist/socket-sdk-class.js

@@ -11,6 +11,7 @@ exports.SocketSdk = void 0;
 const node_events_1 = __importDefault(require("node:events"));
 const node_fs_1 = require("node:fs");
 const node_readline_1 = __importDefault(require("node:readline"));
+const cache_with_ttl_1 = require("@socketsecurity/registry/lib/cache-with-ttl");
 const SOCKET_PUBLIC_API_TOKEN_1 = __importDefault(require("@socketsecurity/registry/lib/constants/SOCKET_PUBLIC_API_TOKEN"));
 const UNKNOWN_ERROR_1 = __importDefault(require("@socketsecurity/registry/lib/constants/UNKNOWN_ERROR"));
 const abort_signal_1 = __importDefault(require("@socketsecurity/registry/lib/constants/abort-signal"));
@@ -30,15 +31,16 @@ const utils_1 = require("./utils");
 class SocketSdk {
     #apiToken;
     #baseUrl;
+    #cache;
     #reqOptions;
     #retries;
     #retryDelay;
     /**
      * Initialize Socket SDK with API token and configuration options.
-     * Sets up authentication, base URL, HTTP client options, and retry behavior.
+     * Sets up authentication, base URL, HTTP client options, retry behavior, and caching.
      */
     constructor(apiToken, options) {
-        const { agent: agentOrObj, baseUrl = 'https://api.socket.dev/v0/', retries = 3, retryDelay = 1000, timeout, userAgent, } = { __proto__: null, ...options };
+        const { agent: agentOrObj, baseUrl = 'https://api.socket.dev/v0/', cache = false, cacheTtl = 5 * 60 * 1000, retries = 0, retryDelay = 100, timeout, userAgent, } = { __proto__: null, ...options };
         const agentKeys = agentOrObj ? Object.keys(agentOrObj) : [];
         const agentAsGotOptions = agentOrObj;
         const agent = (agentKeys.length && agentKeys.every(k => constants_1.httpAgentNames.has(k))
@@ -49,6 +51,13 @@ class SocketSdk {
             : agentOrObj);
         this.#apiToken = apiToken;
         this.#baseUrl = (0, utils_1.normalizeBaseUrl)(baseUrl);
+        this.#cache = cache
+            ? (0, cache_with_ttl_1.createTtlCache)({
+                memoize: true,
+                prefix: 'socket-sdk',
+                ttl: cacheTtl,
+            })
+            : undefined;
         this.#retries = retries;
         this.#retryDelay = retryDelay;
         this.#reqOptions = {
@@ -88,6 +97,20 @@ class SocketSdk {
         }
         return result;
     }
+    /**
+     * Execute a GET request with optional caching.
+     * Internal method for handling cached GET requests with retry logic.
+     */
+    async #getCached(cacheKey, fetcher) {
+        // If caching is disabled, just execute the request.
+        if (!this.#cache) {
+            return await this.#executeWithRetry(fetcher);
+        }
+        // Use cache with retry logic.
+        return await this.#cache.getOrFetch(cacheKey, async () => {
+            return await this.#executeWithRetry(fetcher);
+        });
+    }
     /**
      * Create async generator for streaming batch package URL processing.
      * Internal method for handling chunked PURL responses with error handling.
@@ -812,7 +835,7 @@ class SocketSdk {
      */
     async getOrganizations() {
         try {
-            const data = await this.#executeWithRetry(async () => await (0, http_client_1.getResponseJson)(await (0, http_client_1.createGetRequest)(this.#baseUrl, 'organizations', this.#reqOptions)));
+            const data = await this.#getCached('organizations', async () => await (0, http_client_1.getResponseJson)(await (0, http_client_1.createGetRequest)(this.#baseUrl, 'organizations', this.#reqOptions)));
             return this.#handleApiSuccess(data);
         }
         catch (e) {
@@ -977,7 +1000,7 @@ class SocketSdk {
      */
     async getQuota() {
         try {
-            const data = await this.#executeWithRetry(async () => await (0, http_client_1.getResponseJson)(await (0, http_client_1.createGetRequest)(this.#baseUrl, 'quota', this.#reqOptions)));
+            const data = await this.#getCached('quota', async () => await (0, http_client_1.getResponseJson)(await (0, http_client_1.createGetRequest)(this.#baseUrl, 'quota', this.#reqOptions)));
             return this.#handleApiSuccess(data);
         }
         catch (e) {

package/dist/types.d.ts

@@ -129,12 +129,38 @@ export type SocketSdkGenericResult<T> = {
     status: number;
     success: false;
 };
+/**
+ * Configuration options for SocketSdk.
+ */
 export interface SocketSdkOptions {
+    /** HTTP agent for connection pooling and proxy support */
     agent?: Agent | GotOptions | undefined;
+    /** Base URL for Socket API (default: 'https://api.socket.dev/v0/') */
     baseUrl?: string | undefined;
+    /**
+     * Enable TTL caching for API responses (default: false).
+     * When enabled, GET requests are cached with a 5-minute TTL.
+     */
+    cache?: boolean | undefined;
+    /**
+     * Cache TTL in milliseconds (default: 300000 = 5 minutes).
+     * Only used when cache is enabled.
+     */
+    cacheTtl?: number | undefined;
+    /**
+     * Number of retry attempts on failure (default: 0, retries disabled).
+     * Retries are opt-in following Node.js fs.rm() pattern.
+     * Recommended: 3 for production, 0 for testing.
+     */
     retries?: number | undefined;
+    /**
+     * Initial delay in milliseconds between retries (default: 100).
+     * Uses exponential backoff: 100ms, 200ms, 400ms, etc.
+     */
     retryDelay?: number | undefined;
+    /** Request timeout in milliseconds */
     timeout?: number | undefined;
+    /** Custom User-Agent header */
     userAgent?: string | undefined;
 }
 export type UploadManifestFilesResponse = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/sdk",
-  "version": "1.10.1",
+  "version": "1.11.0",
   "license": "MIT",
   "description": "SDK for the Socket API client",
   "author": {
@@ -75,7 +75,7 @@
     "update:socket": "pnpm -r update '@socketsecurity/*' --latest"
   },
   "dependencies": {
-    "@socketsecurity/registry": "1.4.1"
+    "@socketsecurity/registry": "1.4.2"
   },
   "devDependencies": {
     "@biomejs/biome": "2.2.4",