@socketsecurity/sdk 1.10.1 → 1.11.1

package/dist/testing.js

@@ -0,0 +1,387 @@
+'use strict';
+
+/**
+ * @fileoverview Testing utilities for Socket SDK.
+ * Provides mock factories, response builders, and test helpers for easier SDK testing.
+ */
+
+/**
+ * Create a successful SDK response.
+ *
+ * @template T - The data type
+ * @param data - The response data
+ * @param status - HTTP status code (default: 200)
+ * @returns A successful SDK result
+ *
+ * @example
+ * ```ts
+ * const response = mockSuccessResponse({ id: '123', name: 'test' })
+ * expect(response.success).toBe(true)
+ * ```
+ */
+function mockSuccessResponse(data, status = 200) {
+  return {
+    cause: undefined,
+    data,
+    error: undefined,
+    status,
+    success: true
+  };
+}
+
+/**
+ * Create an error SDK response.
+ *
+ * @template T - The data type (unused in error responses)
+ * @param error - The error message
+ * @param status - HTTP status code (default: 500)
+ * @param cause - Optional error cause
+ * @returns An error SDK result
+ *
+ * @example
+ * ```ts
+ * const response = mockErrorResponse('Not found', 404)
+ * expect(response.success).toBe(false)
+ * ```
+ */
+function mockErrorResponse(error, status = 500, cause) {
+  return {
+    cause,
+    data: undefined,
+    error,
+    status,
+    success: false
+  };
+}
+
+/**
+ * Create a mock Socket API error response body.
+ *
+ * @param message - Error message
+ * @param details - Optional error details
+ * @returns Socket API error response structure
+ *
+ * @example
+ * ```ts
+ * nock('https://api.socket.dev')
+ *   .get('/v0/repo/org/repo')
+ *   .reply(404, mockApiErrorBody('Repository not found'))
+ * ```
+ */
+function mockApiErrorBody(message, details) {
+  return {
+    error: {
+      message,
+      ...(details ? {
+        details
+      } : {})
+    }
+  };
+}
+
+/**
+ * Common fixture data for organization responses.
+ */
+const organizationFixtures = {
+  /**
+   * Basic organization with minimal data.
+   */
+  basic: {
+    id: 'org_123',
+    name: 'test-org',
+    plan: 'free'
+  },
+  /**
+   * Organization with full details.
+   */
+  full: {
+    id: 'org_123',
+    name: 'test-org',
+    plan: 'enterprise',
+    created_at: '2024-01-01T00:00:00Z',
+    updated_at: '2024-01-02T00:00:00Z'
+  }
+};
+
+/**
+ * Common fixture data for repository responses.
+ */
+const repositoryFixtures = {
+  /**
+   * Basic repository with minimal data.
+   */
+  basic: {
+    id: 'repo_123',
+    name: 'test-repo',
+    archived: false,
+    default_branch: 'main'
+  },
+  /**
+   * Archived repository.
+   */
+  archived: {
+    id: 'repo_456',
+    name: 'old-repo',
+    archived: true,
+    default_branch: 'master'
+  },
+  /**
+   * Repository with full details.
+   */
+  full: {
+    id: 'repo_123',
+    name: 'test-repo',
+    archived: false,
+    default_branch: 'main',
+    homepage: 'https://example.com',
+    visibility: 'public',
+    created_at: '2024-01-01T00:00:00Z',
+    updated_at: '2024-01-02T00:00:00Z'
+  }
+};
+
+/**
+ * Common fixture data for scan responses.
+ */
+const scanFixtures = {
+  /**
+   * Pending scan.
+   */
+  pending: {
+    id: 'scan_pending',
+    status: 'pending',
+    created_at: '2024-01-01T00:00:00Z'
+  },
+  /**
+   * Completed scan with no issues.
+   */
+  completed: {
+    id: 'scan_completed',
+    status: 'completed',
+    created_at: '2024-01-01T00:00:00Z',
+    completed_at: '2024-01-01T00:01:00Z',
+    issues_found: 0
+  },
+  /**
+   * Completed scan with issues.
+   */
+  withIssues: {
+    id: 'scan_with_issues',
+    status: 'completed',
+    created_at: '2024-01-01T00:00:00Z',
+    completed_at: '2024-01-01T00:01:00Z',
+    issues_found: 3
+  },
+  /**
+   * Failed scan.
+   */
+  failed: {
+    id: 'scan_failed',
+    status: 'failed',
+    created_at: '2024-01-01T00:00:00Z',
+    error: 'Scan timeout'
+  }
+};
+
+/**
+ * Common fixture data for package/artifact responses.
+ */
+const packageFixtures = {
+  /**
+   * Safe package with high score.
+   */
+  safe: {
+    id: 'pkg_safe',
+    name: 'safe-package',
+    version: '1.0.0',
+    score: 95
+  },
+  /**
+   * Package with vulnerabilities.
+   */
+  vulnerable: {
+    id: 'pkg_vuln',
+    name: 'vulnerable-package',
+    version: '2.0.0',
+    score: 45,
+    issues: ['vulnerability']
+  },
+  /**
+   * Package with malware alert.
+   */
+  malware: {
+    id: 'pkg_malware',
+    name: 'malware-package',
+    version: '3.0.0',
+    score: 0,
+    issues: ['malware']
+  }
+};
+
+/**
+ * Common fixture data for issue/alert responses.
+ */
+const issueFixtures = {
+  /**
+   * Vulnerability issue.
+   */
+  vulnerability: {
+    type: 'vulnerability',
+    severity: 'high',
+    key: 'CVE-2024-1234',
+    description: 'SQL Injection vulnerability'
+  },
+  /**
+   * Malware issue.
+   */
+  malware: {
+    type: 'malware',
+    severity: 'critical',
+    key: 'malware-detected',
+    description: 'Malicious code detected'
+  },
+  /**
+   * License issue.
+   */
+  license: {
+    type: 'license',
+    severity: 'medium',
+    key: 'license-incompatible',
+    description: 'License incompatible with project'
+  }
+};
+
+/**
+ * All fixture categories in one object.
+ */
+const fixtures = {
+  issues: issueFixtures,
+  organizations: organizationFixtures,
+  packages: packageFixtures,
+  repositories: repositoryFixtures,
+  scans: scanFixtures
+};
+
+/**
+ * Mock SDK method result with proper typing.
+ *
+ * @template T - The operation type
+ * @param success - Whether the operation succeeded
+ * @param data - Success data or error details
+ * @returns Properly typed SDK result
+ *
+ * @example
+ * ```ts
+ * const mockGet = vi.fn().mockResolvedValue(
+ *   mockSdkResult<'getRepo'>(true, { id: '123', name: 'repo' })
+ * )
+ * ```
+ */
+
+function mockSdkResult(success, dataOrError, status = success ? 200 : 500, cause) {
+  if (success) {
+    return {
+      cause: undefined,
+      data: dataOrError,
+      error: undefined,
+      status,
+      success: true
+    };
+  }
+  return {
+    cause,
+    data: undefined,
+    error: dataOrError,
+    status,
+    success: false
+  };
+}
+
+/**
+ * Create a mock SDK error with proper structure.
+ *
+ * @param type - Error type ('NOT_FOUND', 'UNAUTHORIZED', etc.)
+ * @param options - Error options
+ * @returns Error response matching SDK structure
+ *
+ * @example
+ * ```ts
+ * const mockMethod = vi.fn().mockRejectedValue(
+ *   mockSdkError('NOT_FOUND', { status: 404, message: 'Repository not found' })
+ * )
+ * ```
+ */
+function mockSdkError(type, options = {}) {
+  const statusMap = {
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    SERVER_ERROR: 500,
+    TIMEOUT: 408,
+    UNAUTHORIZED: 401
+  };
+  const messageMap = {
+    FORBIDDEN: 'Access forbidden',
+    NOT_FOUND: 'Resource not found',
+    SERVER_ERROR: 'Internal server error',
+    TIMEOUT: 'Request timeout',
+    UNAUTHORIZED: 'Unauthorized'
+  };
+  const status = options.status ?? statusMap[type];
+  const message = options.message ?? messageMap[type];
+  const error = new Error(message);
+  error.status = status;
+  if (options.cause) {
+    error.cause = options.cause;
+  }
+  return error;
+}
+
+/**
+ * Type guard to check if SDK result is successful.
+ *
+ * @param result - SDK result to check
+ * @returns True if result is successful
+ *
+ * @example
+ * ```ts
+ * const result = await sdk.getRepo('org', 'repo')
+ * if (isSuccessResult(result)) {
+ *   console.log(result.data.name) // Type-safe access
+ * }
+ * ```
+ */
+function isSuccessResult(result) {
+  return result.success === true;
+}
+
+/**
+ * Type guard to check if SDK result is an error.
+ *
+ * @param result - SDK result to check
+ * @returns True if result is an error
+ *
+ * @example
+ * ```ts
+ * const result = await sdk.getRepo('org', 'repo')
+ * if (isErrorResult(result)) {
+ *   console.error(result.error) // Type-safe access
+ * }
+ * ```
+ */
+function isErrorResult(result) {
+  return result.success === false;
+}
+
+exports.fixtures = fixtures;
+exports.isErrorResult = isErrorResult;
+exports.isSuccessResult = isSuccessResult;
+exports.issueFixtures = issueFixtures;
+exports.mockApiErrorBody = mockApiErrorBody;
+exports.mockErrorResponse = mockErrorResponse;
+exports.mockSdkError = mockSdkError;
+exports.mockSdkResult = mockSdkResult;
+exports.mockSuccessResponse = mockSuccessResponse;
+exports.organizationFixtures = organizationFixtures;
+exports.packageFixtures = packageFixtures;
+exports.repositoryFixtures = repositoryFixtures;
+exports.scanFixtures = scanFixtures;

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/dist/user-agent.js

@@ -1,17 +1,21 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createUserAgentFromPkgJson = createUserAgentFromPkgJson;
+'use strict';
+
 /**
  * @fileoverview User-Agent string generation utilities.
  * Creates standardized User-Agent headers from package.json data for API requests.
  */
+
 /**
  * Generate a User-Agent string from package.json data.
  * Creates standardized User-Agent format with optional homepage URL.
  */
 function createUserAgentFromPkgJson(pkgData) {
-    const { homepage } = pkgData;
-    const name = pkgData.name.replace('@', '').replace('/', '-');
-    /* c8 ignore next - homepage URL is optional in package.json */
-    return `${name}/${pkgData.version}${homepage ? ` (${homepage})` : ''}`;
+  const {
+    homepage
+  } = pkgData;
+  const name = pkgData.name.replace('@', '').replace('/', '-');
+  /* c8 ignore next - homepage URL is optional in package.json */
+  return `${name}/${pkgData.version}${homepage ? ` (${homepage})` : ''}`;
 }
+
+exports.createUserAgentFromPkgJson = createUserAgentFromPkgJson;

package/dist/utils.d.ts

@@ -3,8 +3,9 @@ export { createUserAgentFromPkgJson } from './user-agent';
 /**
  * Normalize base URL by ensuring it ends with a trailing slash.
  * Required for proper URL joining with relative paths.
+ * Memoized for performance since base URLs are typically reused.
  */
-export declare function normalizeBaseUrl(baseUrl: string): string;
+export declare const normalizeBaseUrl: (baseUrl: string) => string;
 /**
  * Create a promise with externally accessible resolve/reject functions.
  * Polyfill for Promise.withResolvers() on older Node.js versions.

package/dist/utils.js

@@ -1,93 +1,99 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createUserAgentFromPkgJson = void 0;
-exports.normalizeBaseUrl = normalizeBaseUrl;
-exports.promiseWithResolvers = promiseWithResolvers;
-exports.queryToSearchParams = queryToSearchParams;
-exports.resolveAbsPaths = resolveAbsPaths;
-exports.resolveBasePath = resolveBasePath;
+'use strict';
+
+var path$1 = require('node:path');
+var memoization = require('@socketsecurity/registry/lib/memoization');
+var path = require('@socketsecurity/registry/lib/path');
+var userAgent = require('./user-agent.js');
+
 /**
  * @fileoverview Utility functions for Socket SDK operations.
  * Provides URL normalization, query parameter handling, and path resolution utilities.
  */
-const node_path_1 = __importDefault(require("node:path"));
-const path_1 = require("@socketsecurity/registry/lib/path");
-// Re-export user agent function for convenience
-const user_agent_1 = require("./user-agent");
-Object.defineProperty(exports, "createUserAgentFromPkgJson", { enumerable: true, get: function () { return user_agent_1.createUserAgentFromPkgJson; } });
+
 /**
  * Normalize base URL by ensuring it ends with a trailing slash.
  * Required for proper URL joining with relative paths.
+ * Memoized for performance since base URLs are typically reused.
  */
-function normalizeBaseUrl(baseUrl) {
-    return baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
-}
+const normalizeBaseUrl = memoization.memoize(baseUrl => {
+  return baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+}, {
+  name: 'normalizeBaseUrl'
+});
+
 /**
  * Create a promise with externally accessible resolve/reject functions.
  * Polyfill for Promise.withResolvers() on older Node.js versions.
  */
 function promiseWithResolvers() {
-    /* c8 ignore next 3 - polyfill for older Node versions without Promise.withResolvers */
-    if (Promise.withResolvers) {
-        return Promise.withResolvers();
-    }
-    /* c8 ignore next 7 - polyfill implementation for older Node versions */
-    const obj = {};
-    obj.promise = new Promise((resolver, reject) => {
-        obj.resolve = resolver;
-        obj.reject = reject;
-    });
-    return obj;
+  /* c8 ignore next 3 - polyfill for older Node versions without Promise.withResolvers */
+  if (Promise.withResolvers) {
+    return Promise.withResolvers();
+  }
+
+  /* c8 ignore next 7 - polyfill implementation for older Node versions */
+  const obj = {};
+  obj.promise = new Promise((resolver, reject) => {
+    obj.resolve = resolver;
+    obj.reject = reject;
+  });
+  return obj;
 }
+
 /**
  * Convert query parameters to URLSearchParams with API-compatible key normalization.
  * Transforms camelCase keys to snake_case and filters out empty values.
  */
 function queryToSearchParams(init) {
-    const params = new URLSearchParams(init);
-    const normalized = Object.create(null);
-    const entries = params.entries();
-    for (const entry of entries) {
-        let key = entry[0];
-        const value = entry[1];
-        if (key === 'defaultBranch') {
-            /* c8 ignore next - query parameter normalization for API compatibility */
-            key = 'default_branch';
-        }
-        else if (key === 'perPage') {
-            /* c8 ignore next 2 - query parameter normalization for API compatibility */
-            key = 'per_page';
-        }
-        /* c8 ignore next - skip empty string values in params */
-        if (value) {
-            normalized[key] = value;
-        }
+  const params = new URLSearchParams(init);
+  const normalized = Object.create(null);
+  const entries = params.entries();
+  for (const entry of entries) {
+    let key = entry[0];
+    const value = entry[1];
+    if (key === 'defaultBranch') {
+      /* c8 ignore next - query parameter normalization for API compatibility */
+      key = 'default_branch';
+    } else if (key === 'perPage') {
+      /* c8 ignore next 2 - query parameter normalization for API compatibility */
+      key = 'per_page';
     }
-    return new URLSearchParams(normalized);
+    /* c8 ignore next - skip empty string values in params */
+    if (value) {
+      normalized[key] = value;
+    }
+  }
+  return new URLSearchParams(normalized);
 }
+
 /**
  * Convert relative file paths to absolute paths.
  * Resolves paths relative to specified base directory or current working directory.
  */
 function resolveAbsPaths(filepaths, pathsRelativeTo) {
-    const basePath = resolveBasePath(pathsRelativeTo);
-    // Node's path.resolve will process path segments from right to left until
-    // it creates a valid absolute path. So if `pathsRelativeTo` is an absolute
-    // path, process.cwd() is not used, which is the common expectation. If none
-    // of the paths resolve then it defaults to process.cwd().
-    return filepaths.map(p => (0, path_1.normalizePath)(node_path_1.default.resolve(basePath, p)));
+  const basePath = resolveBasePath(pathsRelativeTo);
+  // Node's path.resolve will process path segments from right to left until
+  // it creates a valid absolute path. So if `pathsRelativeTo` is an absolute
+  // path, process.cwd() is not used, which is the common expectation. If none
+  // of the paths resolve then it defaults to process.cwd().
+  return filepaths.map(p => path.normalizePath(path$1.resolve(basePath, p)));
 }
+
 /**
  * Resolve base path to an absolute directory path.
  * Converts relative paths to absolute using current working directory as reference.
  */
 function resolveBasePath(pathsRelativeTo = '.') {
-    // Node's path.resolve will process path segments from right to left until
-    // it creates a valid absolute path. So if `pathsRelativeTo` is an absolute
-    // path, process.cwd() is not used, which is the common expectation. If none
-    // of the paths resolve then it defaults to process.cwd().
-    return (0, path_1.normalizePath)(node_path_1.default.resolve(process.cwd(), pathsRelativeTo));
+  // Node's path.resolve will process path segments from right to left until
+  // it creates a valid absolute path. So if `pathsRelativeTo` is an absolute
+  // path, process.cwd() is not used, which is the common expectation. If none
+  // of the paths resolve then it defaults to process.cwd().
+  return path.normalizePath(path$1.resolve(process.cwd(), pathsRelativeTo));
 }
+
+exports.createUserAgentFromPkgJson = userAgent.createUserAgentFromPkgJson;
+exports.normalizeBaseUrl = normalizeBaseUrl;
+exports.promiseWithResolvers = promiseWithResolvers;
+exports.queryToSearchParams = queryToSearchParams;
+exports.resolveAbsPaths = resolveAbsPaths;
+exports.resolveBasePath = resolveBasePath;