@socketsecurity/sdk 1.9.1 → 1.10.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.10.0](https://github.com/SocketDev/socket-sdk-js/releases/tag/v1.10.0) - 2025-10-04
+
+### Added
+- Added `PromiseQueue` utility for controlled concurrency in async operations
+- HTTP retry logic with exponential backoff for improved reliability on transient failures
+- Added option type interfaces: `CreateDependenciesSnapshotOptions`, `CreateOrgFullScanOptions`, `CreateScanFromFilepathsOptions`, `StreamOrgFullScanOptions`, `UploadManifestFilesOptions`
+
+### Changed
+- **BREAKING**: Refactored SDK methods to use options objects instead of positional parameters for better API clarity:
+  - `createDependenciesSnapshot(filepaths, options)` - replaced `repo` and `branch` positional parameters with options object
+  - `createOrgFullScan(orgSlug, filepaths, options)` - replaced positional parameters with options object
+  - `createScanFromFilepaths(filepaths, options)` - replaced positional parameters with options object
+  - `streamOrgFullScan(orgSlug, fullScanId, options)` - replaced positional parameters with options object
+  - `uploadManifestFiles(orgSlug, filepaths, options)` - replaced positional parameters with options object
+- Improved type safety by replacing `any` types with `unknown` or `never` where appropriate
+- Enhanced code style with numeric separators for better readability of large numbers
+- Improved coverage reporting accuracy with c8 ignore comments
+- Updated `@socketsecurity/registry` dependency to 1.4.0
+
+### Fixed
+- Fixed import assertion syntax for JSON imports to use standard import syntax
+- Fixed HTTP retry test mocks to correctly match PUT method requests
+- Fixed critical issues in type handling and URL search parameter conversions
+
+## [1.9.2](https://github.com/SocketDev/socket-sdk-js/releases/tag/v1.9.2) - 2025-10-04
+
+### Changed
+- Improved TypeScript type definitions - All optional properties now include explicit `| undefined` type annotations for better type narrowing and null safety
+
 ## [1.9.1](https://github.com/SocketDev/socket-sdk-js/releases/tag/v1.9.1) - 2025-10-03
 
 ### Changed

package/README.md

@@ -1,13 +1,12 @@
 # @socketsecurity/sdk
 
 [![Socket Badge](https://socket.dev/api/badge/npm/package/@socketsecurity/sdk)](https://socket.dev/npm/package/@socketsecurity/sdk)
-[![npm version](https://img.shields.io/npm/v/@socketsecurity/sdk.svg?style=flat)](https://www.npmjs.com/package/@socketsecurity/sdk)
-[![TypeScript types](https://img.shields.io/npm/types/@socketsecurity/sdk.svg?style=flat)](https://www.npmjs.com/package/@socketsecurity/sdk)
-[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](https://github.com/SocketDev/eslint-config)
+[![CI](https://github.com/SocketDev/socket-sdk-js/actions/workflows/ci.yml/badge.svg)](https://github.com/SocketDev/socket-sdk-js/actions/workflows/ci.yml)
+
 [![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
 [![Follow @socket.dev on Bluesky](https://img.shields.io/badge/Follow-@socket.dev-1DA1F2?style=social&logo=bluesky)](https://bsky.app/profile/socket.dev)
 
-SDK for the Socket API client, generated by `api`.
+Official SDK for Socket.dev - Programmatic access to security analysis, vulnerability scanning, and compliance monitoring for your software supply chain.
 
 ## Usage
 
@@ -20,7 +19,11 @@ pnpm add @socketsecurity/sdk
 ```javascript
 import { SocketSdk } from '@socketsecurity/sdk'
 
-const client = new SocketSdk('yourApiKeyHere')
+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)
+  timeout: 30000,    // Request timeout in milliseconds (optional)
+})
 
 const res = await client.getQuota()
 
@@ -30,6 +33,27 @@ if (res.success) {
 }
 ```
 
+### Configuration Options
+
+The SDK constructor accepts the following options:
+
+```typescript
+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)
+  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`)
+- Does NOT retry 401/403 authentication errors (immediate failure)
+- Set `retries: 0` to disable retry logic entirely
+
 ### Quota Management Example
 
 ```javascript

package/dist/constants.js

@@ -8,9 +8,6 @@ exports.publicPolicy = exports.httpAgentNames = exports.DEFAULT_USER_AGENT = voi
  * @fileoverview Configuration constants and enums for the Socket SDK.
  * Provides default values, HTTP agents, and public policy configurations for API interactions.
  */
-// Import attributes are only supported when the '--module' option is set to
-// 'esnext', 'node18', 'node20', 'nodenext', or 'preserve'.
-// @ts-ignore: Avoid TS import attributes error.
 const package_json_1 = __importDefault(require("../package.json"));
 const user_agent_1 = require("./user-agent");
 exports.DEFAULT_USER_AGENT = (0, user_agent_1.createUserAgentFromPkgJson)(package_json_1.default);

package/dist/file-upload.js

@@ -24,7 +24,7 @@ function createRequestBodyForFilepaths(filepaths, basePath) {
         const filename = node_path_1.default.basename(absPath);
         requestBody.push([
             `Content-Disposition: form-data; name="${relPath}"; filename="${filename}"\r\n`,
-            `Content-Type: application/octet-stream\r\n\r\n`,
+            'Content-Type: application/octet-stream\r\n\r\n',
             (0, node_fs_1.createReadStream)(absPath, { highWaterMark: 1024 * 1024 }),
         ]);
     }
@@ -39,7 +39,7 @@ function createRequestBodyForJson(jsonData, basename = 'data.json') {
     const name = node_path_1.default.basename(basename, ext);
     return [
         `Content-Disposition: form-data; name="${name}"; filename="${basename}"\r\n` +
-            `Content-Type: application/json\r\n\r\n`,
+            'Content-Type: application/json\r\n\r\n',
         node_stream_1.Readable.from(JSON.stringify(jsonData), { highWaterMark: 1024 * 1024 }),
         '\r\n',
     ];

package/dist/http-client.d.ts

@@ -65,7 +65,7 @@ export declare function getResponse(req: ClientRequest): Promise<IncomingMessage
  * @throws {ResponseError} When response has non-2xx status code
  * @throws {SyntaxError} When response body contains invalid JSON
  */
-export declare function getResponseJson(response: IncomingMessage, method?: string): Promise<import("@socketsecurity/registry/lib/json").JsonValue | undefined>;
+export declare function getResponseJson(response: IncomingMessage, method?: string | undefined): Promise<import("@socketsecurity/registry/lib/json").JsonValue | undefined>;
 /**
  * Check if HTTP response has a successful status code (2xx range).
  * Returns true for status codes between 200-299, false otherwise.
@@ -75,4 +75,39 @@ export declare function isResponseOk(response: IncomingMessage): boolean;
  * Transform artifact data based on authentication status.
  * Filters and compacts response data for public/free-tier users.
  */
-export declare function reshapeArtifactForPublicPolicy<T extends Record<string, any>>(data: T, isAuthenticated: boolean, actions?: string): T;
+export declare function reshapeArtifactForPublicPolicy<T extends Record<string, unknown>>(data: T, isAuthenticated: boolean, actions?: string | undefined): T;
+/**
+ * Retry helper for HTTP requests with exponential backoff.
+ * 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)
+ * @returns Result of the function call
+ * @throws {Error} Last error if all retries exhausted
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, retries?: number, retryDelay?: number): Promise<T>;
+/**
+ * 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)
+ */
+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)
+ */
+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)
+ */
+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

@@ -13,6 +13,10 @@ exports.getResponse = getResponse;
 exports.getResponseJson = getResponseJson;
 exports.isResponseOk = isResponseOk;
 exports.reshapeArtifactForPublicPolicy = reshapeArtifactForPublicPolicy;
+exports.withRetry = withRetry;
+exports.createGetRequestWithRetry = createGetRequestWithRetry;
+exports.createDeleteRequestWithRetry = createDeleteRequestWithRetry;
+exports.createRequestWithJsonAndRetry = createRequestWithJsonAndRetry;
 /**
  * @fileoverview HTTP client utilities for Socket API communication.
  * Provides low-level HTTP request handling with proper error management and response parsing.
@@ -248,12 +252,15 @@ function reshapeArtifactForPublicPolicy(data, isAuthenticated, actions) {
         // Handle both single artifacts and objects with artifacts arrays.
         if (data['artifacts']) {
             // Object with artifacts array.
+            const artifacts = data['artifacts'];
             return {
                 ...data,
-                artifacts: data['artifacts']?.map(reshapeArtifact),
+                artifacts: Array.isArray(artifacts)
+                    ? artifacts.map(reshapeArtifact)
+                    : artifacts,
             };
         }
-        else if (data['alerts']) {
+        if (data['alerts']) {
             // Single artifact with alerts.
             return reshapeArtifact(data);
         }
@@ -261,3 +268,80 @@ function reshapeArtifactForPublicPolicy(data, isAuthenticated, actions) {
     return data;
     /* c8 ignore stop */
 }
+/**
+ * Retry helper for HTTP requests with exponential backoff.
+ * 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)
+ * @returns Result of the function call
+ * @throws {Error} Last error if all retries exhausted
+ */
+async function withRetry(fn, retries = 3, retryDelay = 1000) {
+    let lastError;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            // Last attempt - throw error with retry context.
+            if (attempt === retries) {
+                const enhancedError = new Error(`Request failed after ${retries + 1} attempts`, { cause: lastError });
+                throw enhancedError;
+            }
+            // Check if error is retryable (network errors, 5xx responses).
+            if (error instanceof ResponseError) {
+                const status = error.response.statusCode;
+                // Don't retry client errors (4xx).
+                if (status && status >= 400 && status < 500) {
+                    throw error;
+                }
+                (0, debug_1.debugLog)('withRetry', `Retrying after ${status} error (attempt ${attempt + 1}/${retries + 1})`);
+            }
+            else {
+                (0, debug_1.debugLog)('withRetry', `Retrying after network error (attempt ${attempt + 1}/${retries + 1})`);
+            }
+            // Exponential backoff.
+            const delayMs = retryDelay * 2 ** attempt;
+            (0, debug_1.debugLog)('withRetry', `Waiting ${delayMs}ms before retry`);
+            // eslint-disable-next-line no-await-in-loop
+            await new Promise(resolve => setTimeout(resolve, delayMs));
+        }
+    }
+    // Fallback error if lastError is somehow undefined.
+    /* c8 ignore next - Defensive fallback for undefined lastError */
+    throw lastError || new Error('Request failed after retries');
+}
+/**
+ * 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)
+ */
+async function createGetRequestWithRetry(baseUrl, urlPath, options, retries = 3, retryDelay = 1000) {
+    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)
+ */
+async function createDeleteRequestWithRetry(baseUrl, urlPath, options, retries = 3, retryDelay = 1000) {
+    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)
+ */
+async function createRequestWithJsonAndRetry(method, baseUrl, urlPath, json, options, retries = 3, retryDelay = 1000) {
+    return await withRetry(() => createRequestWithJson(method, baseUrl, urlPath, json, options), retries, retryDelay);
+}

package/dist/index.d.ts

@@ -4,11 +4,11 @@
  */
 import { DEFAULT_USER_AGENT, httpAgentNames, publicPolicy } from './constants';
 import { normalizeBaseUrl, promiseWithResolvers, queryToSearchParams, resolveAbsPaths, resolveBasePath } from './utils';
-export type * from './types';
-export { createUserAgentFromPkgJson } from './user-agent';
-export { createDeleteRequest, createGetRequest, createRequestWithJson, getErrorResponseBody, getHttpModule, getResponse, getResponseJson, isResponseOk, reshapeArtifactForPublicPolicy, ResponseError, } from './http-client';
 export { createRequestBodyForFilepaths, createRequestBodyForJson, createUploadRequest, } from './file-upload';
-export { SocketSdk } from './socket-sdk-class';
+export { createDeleteRequest, createGetRequest, createRequestWithJson, getErrorResponseBody, getHttpModule, getResponse, getResponseJson, isResponseOk, ResponseError, reshapeArtifactForPublicPolicy, } from './http-client';
 export { calculateTotalQuotaCost, getAllMethodRequirements, getMethodRequirements, getMethodsByPermissions, getMethodsByQuotaCost, getQuotaCost, getQuotaUsageSummary, getRequiredPermissions, hasQuotaForMethods, } from './quota-utils';
+export { SocketSdk } from './socket-sdk-class';
+export type * from './types';
+export { createUserAgentFromPkgJson } from './user-agent';
 export { normalizeBaseUrl, promiseWithResolvers, queryToSearchParams, resolveAbsPaths, resolveBasePath, };
 export { DEFAULT_USER_AGENT, httpAgentNames, publicPolicy };

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.publicPolicy = exports.httpAgentNames = exports.DEFAULT_USER_AGENT = exports.resolveBasePath = exports.resolveAbsPaths = exports.queryToSearchParams = exports.promiseWithResolvers = exports.normalizeBaseUrl = exports.hasQuotaForMethods = exports.getRequiredPermissions = exports.getQuotaUsageSummary = exports.getQuotaCost = exports.getMethodsByQuotaCost = exports.getMethodsByPermissions = exports.getMethodRequirements = exports.getAllMethodRequirements = exports.calculateTotalQuotaCost = exports.SocketSdk = exports.createUploadRequest = exports.createRequestBodyForJson = exports.createRequestBodyForFilepaths = exports.ResponseError = exports.reshapeArtifactForPublicPolicy = exports.isResponseOk = exports.getResponseJson = exports.getResponse = exports.getHttpModule = exports.getErrorResponseBody = exports.createRequestWithJson = exports.createGetRequest = exports.createDeleteRequest = exports.createUserAgentFromPkgJson = void 0;
+exports.publicPolicy = exports.httpAgentNames = exports.DEFAULT_USER_AGENT = exports.resolveBasePath = exports.resolveAbsPaths = exports.queryToSearchParams = exports.promiseWithResolvers = exports.normalizeBaseUrl = exports.createUserAgentFromPkgJson = exports.SocketSdk = exports.hasQuotaForMethods = exports.getRequiredPermissions = exports.getQuotaUsageSummary = exports.getQuotaCost = exports.getMethodsByQuotaCost = exports.getMethodsByPermissions = exports.getMethodRequirements = exports.getAllMethodRequirements = exports.calculateTotalQuotaCost = exports.reshapeArtifactForPublicPolicy = exports.ResponseError = exports.isResponseOk = exports.getResponseJson = exports.getResponse = exports.getHttpModule = exports.getErrorResponseBody = exports.createRequestWithJson = exports.createGetRequest = exports.createDeleteRequest = exports.createUploadRequest = exports.createRequestBodyForJson = exports.createRequestBodyForFilepaths = void 0;
 /**
  * @fileoverview Main entry point for the Socket SDK.
  * Provides the SocketSdk class and utility functions for Socket security analysis API interactions.
@@ -16,9 +16,11 @@ Object.defineProperty(exports, "promiseWithResolvers", { enumerable: true, get:
 Object.defineProperty(exports, "queryToSearchParams", { enumerable: true, get: function () { return utils_1.queryToSearchParams; } });
 Object.defineProperty(exports, "resolveAbsPaths", { enumerable: true, get: function () { return utils_1.resolveAbsPaths; } });
 Object.defineProperty(exports, "resolveBasePath", { enumerable: true, get: function () { return utils_1.resolveBasePath; } });
-// Re-export functions from modules
-const user_agent_1 = require("./user-agent");
-Object.defineProperty(exports, "createUserAgentFromPkgJson", { enumerable: true, get: function () { return user_agent_1.createUserAgentFromPkgJson; } });
+// Re-export file upload functions
+const file_upload_1 = require("./file-upload");
+Object.defineProperty(exports, "createRequestBodyForFilepaths", { enumerable: true, get: function () { return file_upload_1.createRequestBodyForFilepaths; } });
+Object.defineProperty(exports, "createRequestBodyForJson", { enumerable: true, get: function () { return file_upload_1.createRequestBodyForJson; } });
+Object.defineProperty(exports, "createUploadRequest", { enumerable: true, get: function () { return file_upload_1.createUploadRequest; } });
 // Re-export HTTP client functions
 const http_client_1 = require("./http-client");
 Object.defineProperty(exports, "createDeleteRequest", { enumerable: true, get: function () { return http_client_1.createDeleteRequest; } });
@@ -29,16 +31,8 @@ Object.defineProperty(exports, "getHttpModule", { enumerable: true, get: functio
 Object.defineProperty(exports, "getResponse", { enumerable: true, get: function () { return http_client_1.getResponse; } });
 Object.defineProperty(exports, "getResponseJson", { enumerable: true, get: function () { return http_client_1.getResponseJson; } });
 Object.defineProperty(exports, "isResponseOk", { enumerable: true, get: function () { return http_client_1.isResponseOk; } });
-Object.defineProperty(exports, "reshapeArtifactForPublicPolicy", { enumerable: true, get: function () { return http_client_1.reshapeArtifactForPublicPolicy; } });
 Object.defineProperty(exports, "ResponseError", { enumerable: true, get: function () { return http_client_1.ResponseError; } });
-// Re-export file upload functions
-const file_upload_1 = require("./file-upload");
-Object.defineProperty(exports, "createRequestBodyForFilepaths", { enumerable: true, get: function () { return file_upload_1.createRequestBodyForFilepaths; } });
-Object.defineProperty(exports, "createRequestBodyForJson", { enumerable: true, get: function () { return file_upload_1.createRequestBodyForJson; } });
-Object.defineProperty(exports, "createUploadRequest", { enumerable: true, get: function () { return file_upload_1.createUploadRequest; } });
-// Re-export the main SocketSdk class
-const socket_sdk_class_1 = require("./socket-sdk-class");
-Object.defineProperty(exports, "SocketSdk", { enumerable: true, get: function () { return socket_sdk_class_1.SocketSdk; } });
+Object.defineProperty(exports, "reshapeArtifactForPublicPolicy", { enumerable: true, get: function () { return http_client_1.reshapeArtifactForPublicPolicy; } });
 // Re-export quota utility functions
 const quota_utils_1 = require("./quota-utils");
 Object.defineProperty(exports, "calculateTotalQuotaCost", { enumerable: true, get: function () { return quota_utils_1.calculateTotalQuotaCost; } });
@@ -50,3 +44,9 @@ Object.defineProperty(exports, "getQuotaCost", { enumerable: true, get: function
 Object.defineProperty(exports, "getQuotaUsageSummary", { enumerable: true, get: function () { return quota_utils_1.getQuotaUsageSummary; } });
 Object.defineProperty(exports, "getRequiredPermissions", { enumerable: true, get: function () { return quota_utils_1.getRequiredPermissions; } });
 Object.defineProperty(exports, "hasQuotaForMethods", { enumerable: true, get: function () { return quota_utils_1.hasQuotaForMethods; } });
+// Re-export the main SocketSdk class
+const socket_sdk_class_1 = require("./socket-sdk-class");
+Object.defineProperty(exports, "SocketSdk", { enumerable: true, get: function () { return socket_sdk_class_1.SocketSdk; } });
+// Re-export functions from modules
+const user_agent_1 = require("./user-agent");
+Object.defineProperty(exports, "createUserAgentFromPkgJson", { enumerable: true, get: function () { return user_agent_1.createUserAgentFromPkgJson; } });

package/dist/promise-queue.d.ts

@@ -0,0 +1,35 @@
+export declare class PromiseQueue {
+    private queue;
+    private running;
+    private readonly maxConcurrency;
+    private readonly maxQueueLength;
+    /**
+     * Creates a new PromiseQueue
+     * @param maxConcurrency - Maximum number of promises that can run concurrently
+     * @param maxQueueLength - Maximum queue size (older tasks are dropped if exceeded)
+     */
+    constructor(maxConcurrency: number, maxQueueLength?: number | undefined);
+    /**
+     * Add a task to the queue
+     * @param fn - Async function to execute
+     * @returns Promise that resolves with the function's result
+     */
+    add<T>(fn: () => Promise<T>): Promise<T>;
+    private runNext;
+    /**
+     * Wait for all queued and running tasks to complete
+     */
+    onIdle(): Promise<void>;
+    /**
+     * Get the number of tasks currently running
+     */
+    get activeCount(): number;
+    /**
+     * Get the number of tasks waiting in the queue
+     */
+    get pendingCount(): number;
+    /**
+     * Clear all pending tasks from the queue (does not affect running tasks)
+     */
+    clear(): void;
+}

package/dist/promise-queue.js

@@ -0,0 +1,91 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromiseQueue = void 0;
+class PromiseQueue {
+    queue = [];
+    running = 0;
+    maxConcurrency;
+    maxQueueLength;
+    /**
+     * Creates a new PromiseQueue
+     * @param maxConcurrency - Maximum number of promises that can run concurrently
+     * @param maxQueueLength - Maximum queue size (older tasks are dropped if exceeded)
+     */
+    constructor(maxConcurrency, maxQueueLength) {
+        this.maxConcurrency = maxConcurrency;
+        this.maxQueueLength = maxQueueLength;
+        if (maxConcurrency < 1) {
+            throw new Error('maxConcurrency must be at least 1');
+        }
+    }
+    /**
+     * Add a task to the queue
+     * @param fn - Async function to execute
+     * @returns Promise that resolves with the function's result
+     */
+    async add(fn) {
+        return await new Promise((resolve, reject) => {
+            const task = { fn, resolve, reject };
+            if (this.maxQueueLength && this.queue.length >= this.maxQueueLength) {
+                // Drop oldest task to prevent memory buildup
+                this.queue.shift();
+            }
+            this.queue.push(task);
+            this.runNext();
+        });
+    }
+    runNext() {
+        if (this.running >= this.maxConcurrency || this.queue.length === 0) {
+            return;
+        }
+        const task = this.queue.shift();
+        /* c8 ignore next 3 - Defensive check; unreachable since we verify queue.length above */
+        if (!task) {
+            return;
+        }
+        this.running++;
+        task
+            .fn()
+            .then(task.resolve)
+            .catch(task.reject)
+            .finally(() => {
+            this.running--;
+            this.runNext();
+        });
+    }
+    /**
+     * Wait for all queued and running tasks to complete
+     */
+    async onIdle() {
+        return await new Promise(resolve => {
+            const check = () => {
+                if (this.running === 0 && this.queue.length === 0) {
+                    resolve();
+                }
+                else {
+                    setImmediate(check);
+                }
+            };
+            check();
+        });
+    }
+    /**
+     * Get the number of tasks currently running
+     */
+    get activeCount() {
+        return this.running;
+    }
+    /**
+     * Get the number of tasks waiting in the queue
+     */
+    get pendingCount() {
+        return this.queue.length;
+    }
+    /**
+     * Clear all pending tasks from the queue (does not affect running tasks)
+     */
+    clear() {
+        this.queue = [];
+    }
+}
+exports.PromiseQueue = PromiseQueue;

package/dist/quota-utils.d.ts

@@ -4,48 +4,48 @@ interface ApiRequirement {
     permissions: string[];
 }
 /**
- * Get quota cost for a specific SDK method.
- * Returns the number of quota units consumed by the method.
+ * Calculate total quota cost for multiple SDK method calls.
+ * Returns sum of quota units for all specified methods.
  */
-export declare function getQuotaCost(methodName: SocketSdkOperations | string): number;
+export declare function calculateTotalQuotaCost(methodNames: Array<SocketSdkOperations | string>): number;
 /**
- * Get required permissions for a specific SDK method.
- * Returns array of permission strings needed to call the method.
+ * Get all available SDK methods with their requirements.
+ * Returns complete mapping of methods to quota and permissions.
  */
-export declare function getRequiredPermissions(methodName: SocketSdkOperations | string): string[];
+export declare function getAllMethodRequirements(): Record<string, ApiRequirement>;
 /**
  * Get complete requirement information for a SDK method.
  * Returns both quota cost and required permissions.
  */
 export declare function getMethodRequirements(methodName: SocketSdkOperations | string): ApiRequirement;
 /**
- * Calculate total quota cost for multiple SDK method calls.
- * Returns sum of quota units for all specified methods.
+ * Get all methods that require specific permissions.
+ * Returns methods that need any of the specified permissions.
  */
-export declare function calculateTotalQuotaCost(methodNames: Array<SocketSdkOperations | string>): number;
+export declare function getMethodsByPermissions(permissions: string[]): string[];
 /**
  * Get all methods that consume a specific quota amount.
  * Useful for finding high-cost or free operations.
  */
 export declare function getMethodsByQuotaCost(quotaCost: number): string[];
 /**
- * Get all methods that require specific permissions.
- * Returns methods that need any of the specified permissions.
- */
-export declare function getMethodsByPermissions(permissions: string[]): string[];
-/**
- * Check if user has sufficient quota for method calls.
- * Returns true if available quota covers the total cost.
+ * Get quota cost for a specific SDK method.
+ * Returns the number of quota units consumed by the method.
  */
-export declare function hasQuotaForMethods(availableQuota: number, methodNames: Array<SocketSdkOperations | string>): boolean;
+export declare function getQuotaCost(methodName: SocketSdkOperations | string): number;
 /**
  * Get quota usage summary grouped by cost levels.
  * Returns methods categorized by their quota consumption.
  */
 export declare function getQuotaUsageSummary(): Record<string, string[]>;
 /**
- * Get all available SDK methods with their requirements.
- * Returns complete mapping of methods to quota and permissions.
+ * Get required permissions for a specific SDK method.
+ * Returns array of permission strings needed to call the method.
  */
-export declare function getAllMethodRequirements(): Record<string, ApiRequirement>;
+export declare function getRequiredPermissions(methodName: SocketSdkOperations | string): string[];
+/**
+ * Check if user has sufficient quota for method calls.
+ * Returns true if available quota covers the total cost.
+ */
+export declare function hasQuotaForMethods(availableQuota: number, methodNames: Array<SocketSdkOperations | string>): boolean;
 export {};