@socketsecurity/sdk 3.1.3 → 3.3.0

package/dist/testing.d.ts

@@ -33,7 +33,7 @@ export declare function mockSuccessResponse<T>(data: T, status?: number): Socket
  * expect(response.success).toBe(false)
  * ```
  */
-export declare function mockErrorResponse<T>(error: string, status?: number, cause?: string): SocketSdkGenericResult<T>;
+export declare function mockErrorResponse<T>(error: string, status?: number, cause?: string | undefined): SocketSdkGenericResult<T>;
 /**
  * Create a mock Socket API error response body.
  *
@@ -48,10 +48,10 @@ export declare function mockErrorResponse<T>(error: string, status?: number, cau
  *   .reply(404, mockApiErrorBody('Repository not found'))
  * ```
  */
-export declare function mockApiErrorBody(message: string, details?: Record<string, unknown>): {
+export declare function mockApiErrorBody(message: string, details?: Record<string, unknown> | undefined): {
     error: {
         message: string;
-        details?: Record<string, unknown>;
+        details?: Record<string, unknown> | undefined;
     };
 };
 /**
@@ -393,8 +393,8 @@ export declare const fixtures: {
  * )
  * ```
  */
-export declare function mockSdkResult<T extends SocketSdkOperations>(success: true, data: SocketSdkSuccessResult<T>['data'], status?: number): SocketSdkSuccessResult<T>;
-export declare function mockSdkResult<T extends SocketSdkOperations>(success: false, error: string, status?: number, cause?: string): SocketSdkErrorResult<T>;
+export declare function mockSdkResult<T extends SocketSdkOperations>(success: true, data: SocketSdkSuccessResult<T>['data'], status?: number | undefined): SocketSdkSuccessResult<T>;
+export declare function mockSdkResult<T extends SocketSdkOperations>(success: false, error: string, status?: number | undefined, cause?: string | undefined): SocketSdkErrorResult<T>;
 /**
  * Create a mock SDK error with proper structure.
  *
@@ -410,12 +410,12 @@ export declare function mockSdkResult<T extends SocketSdkOperations>(success: fa
  * ```
  */
 export declare function mockSdkError(type: 'NOT_FOUND' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'SERVER_ERROR' | 'TIMEOUT', options?: {
-    cause?: string;
-    message?: string;
-    status?: number;
+    cause?: string | undefined;
+    message?: string | undefined;
+    status?: number | undefined;
 }): Error & {
     status: number;
-    cause?: string;
+    cause?: string | undefined;
 };
 /**
  * Type guard to check if SDK result is successful.

package/dist/testing.js

@@ -1,4 +1,3 @@
-/* Socket SDK CJS - Built with esbuild */
 "use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;

package/dist/types-strict.d.ts

@@ -1,111 +1,183 @@
 /**
  * @fileoverview Strict type definitions for Socket SDK v3.
+ * AUTO-GENERATED from OpenAPI definitions using AST parsing - DO NOT EDIT MANUALLY.
  * These types provide better TypeScript DX by marking guaranteed fields as required
- * and only keeping truly optional fields as optional. This improves IntelliSense autocomplete.
+ * and only keeping truly optional fields as optional.
+ *
+ * Generated by: scripts/generate-strict-types.mjs
  */
 /**
- * Strict type for full scan metadata item.
- * Represents a single full scan with guaranteed fields marked as required.
+ * Options for create full scan.
+ */
+export type CreateFullScanOptions = {
+    branch?: string | undefined;
+    commit_hash?: string | undefined;
+    commit_message?: string | undefined;
+    committers?: string | undefined;
+    integration_org_slug?: string | undefined;
+    integration_type?: 'api' | 'github' | 'gitlab' | 'bitbucket' | 'azure' | 'web' | undefined;
+    make_default_branch?: boolean | undefined;
+    pathsRelativeTo?: string | undefined;
+    pull_request?: number | undefined;
+    repo: string;
+    scan_type?: string | undefined;
+    set_as_pending_head?: boolean | undefined;
+    tmp?: boolean | undefined;
+    workspace?: string | undefined;
+};
+/**
+ * Strict type for full scan item.
  */
 export type FullScanItem = {
-    id: string;
+    api_url: string | null;
+    branch?: string | null | undefined;
+    commit_hash?: string | null | undefined;
+    commit_message?: string | null | undefined;
+    committers?: string[] | undefined;
     created_at: string;
-    updated_at: string;
+    html_report_url: string;
+    html_url?: string | null | undefined;
+    id: string;
+    integration_branch_url?: string | null | undefined;
+    integration_commit_url?: string | null | undefined;
+    integration_pull_request_url?: string | null | undefined;
+    integration_repo_url: string;
+    integration_type: string | null;
     organization_id: string;
     organization_slug: string;
+    pull_request?: number | null | undefined;
+    repo: string;
     repository_id: string;
     repository_slug: string;
-    repo: string;
-    html_report_url: string;
-    api_url: string;
-    integration_type: string;
-    integration_repo_url: string;
-    branch: string | null;
-    commit_message: string | null;
-    commit_hash: string | null;
-    pull_request: number | null;
-    committers: string[];
-    html_url: string | null;
-    integration_branch_url: string | null;
-    integration_commit_url: string | null;
-    integration_pull_request_url: string | null;
-    scan_state: 'pending' | 'precrawl' | 'resolve' | 'scan' | null;
-    unmatchedFiles?: string[];
+    scan_state?: 'pending' | 'precrawl' | 'resolve' | 'scan' | null | undefined;
+    updated_at: string;
+    workspace?: string | undefined;
 };
 /**
- * Strict type for full scan list response.
+ * Strict type for full scan list data.
  */
 export type FullScanListData = {
+    nextPage?: number | null | undefined;
+    nextPageCursor?: string | null | undefined;
     results: FullScanItem[];
-    nextPageCursor: string | null;
-    nextPage: number | null;
 };
 /**
- * Strict type for full scan list result.
+ * Options for get repository.
  */
-export type FullScanListResult = {
-    cause?: undefined;
-    data: FullScanListData;
-    error?: undefined;
-    status: number;
-    success: true;
+export type GetRepositoryOptions = {
+    workspace?: string | undefined;
 };
 /**
- * Strict type for single full scan result.
+ * Options for list full scans.
  */
-export type FullScanResult = {
-    cause?: undefined;
-    data: FullScanItem;
-    error?: undefined;
-    status: number;
-    success: true;
+export type ListFullScansOptions = {
+    branch?: string | undefined;
+    commit_hash?: string | undefined;
+    direction?: 'asc' | 'desc' | undefined;
+    from?: string | undefined;
+    page?: number | undefined;
+    per_page?: number | undefined;
+    pull_request?: string | undefined;
+    repo?: string | undefined;
+    sort?: 'name' | 'created_at' | undefined;
+    startAfterCursor?: string | undefined;
+    use_cursor?: boolean | undefined;
+    workspace?: string | undefined;
 };
 /**
- * Options for listing full scans.
+ * Options for list repositories.
  */
-export type ListFullScansOptions = {
-    sort?: 'name' | 'created_at';
-    direction?: 'asc' | 'desc';
-    per_page?: number;
-    page?: number;
-    startAfterCursor?: string;
-    use_cursor?: boolean;
-    from?: string;
-    repo?: string;
-    branch?: string;
-    pull_request?: string;
-    commit_hash?: string;
+export type ListRepositoriesOptions = {
+    direction?: string | undefined;
+    include_archived?: boolean | undefined;
+    page?: number | undefined;
+    per_page?: number | undefined;
+    sort?: string | undefined;
 };
 /**
- * Options for creating a full scan.
+ * Strict type for organization item.
  */
-export type CreateFullScanOptions = {
-    pathsRelativeTo?: string;
-    repo: string;
-    branch?: string;
-    commit_message?: string;
-    commit_hash?: string;
-    pull_request?: number;
-    committers?: string;
-    integration_type?: 'api' | 'github' | 'gitlab' | 'bitbucket' | 'azure';
-    integration_org_slug?: string;
-    make_default_branch?: boolean;
-    set_as_pending_head?: boolean;
-    tmp?: boolean;
-    scan_type?: string;
+export type OrganizationItem = {
+    id: string;
+    image?: string | null | undefined;
+    name?: string | null | undefined;
+    plan: string;
+    slug: string;
 };
 /**
- * Options for streaming a full scan.
+ * Strict type for repositories list data.
  */
-export type StreamFullScanOptions = {
-    output?: boolean | string;
+export type RepositoriesListData = {
+    nextPage?: number | null | undefined;
+    results: RepositoryItem[];
+};
+/**
+ * Strict type for repository item.
+ */
+export type RepositoryItem = {
+    archived: boolean;
+    created_at: string;
+    default_branch: string | null;
+    description: string | null;
+    head_full_scan_id: string | null;
+    homepage: string | null;
+    id: string;
+    integration_meta: {
+        /** @enum {string} */
+        type?: 'github';
+        value?: {
+            /**
+             * @description The GitHub installation_id of the active associated Socket GitHub App
+             * @default
+             */
+            installation_id: string;
+            /**
+             * @description The GitHub login name that the active Socket GitHub App installation is installed to
+             * @default
+             */
+            installation_login: string;
+            /**
+             * @description The name of the associated GitHub repo.
+             * @default
+             */
+            repo_name: string | null;
+            /**
+             * @description The id of the associated GitHub repo.
+             * @default
+             */
+            repo_id: string | null;
+        };
+    } | null;
+    name: string;
+    slig?: string | undefined;
+    slug: string;
+    updated_at: string;
+    visibility: 'public' | 'private';
+    workspace: string;
+};
+/**
+ * Strict type for repository label item.
+ */
+export type RepositoryLabelItem = {
+    has_license_policy?: boolean | undefined;
+    has_security_policy?: boolean | undefined;
+    id: string;
+    name: string;
+    repository_ids?: string[] | undefined;
+};
+/**
+ * Strict type for repository labels list data.
+ */
+export type RepositoryLabelsListData = {
+    nextPage?: number | null | undefined;
+    results: RepositoryLabelItem[];
 };
 /**
  * Error result type for all SDK operations.
  */
 export type StrictErrorResult = {
     cause?: string | undefined;
-    data?: undefined;
+    data?: undefined | undefined;
     error: string;
     status: number;
     success: false;
@@ -114,88 +186,69 @@ export type StrictErrorResult = {
  * Generic strict result type combining success and error.
  */
 export type StrictResult<T> = {
-    cause?: undefined;
+    cause?: undefined | undefined;
     data: T;
-    error?: undefined;
+    error?: undefined | undefined;
     status: number;
     success: true;
 } | StrictErrorResult;
 /**
- * Strict type for organization item.
+ * Strict type for full scan list result.
  */
-export type OrganizationItem = {
-    id: string;
-    name: string;
-    slug: string;
-    created_at: string;
-    updated_at: string;
-    plan: string;
+export type FullScanListResult = {
+    cause?: undefined | undefined;
+    data: FullScanListData;
+    error?: undefined | undefined;
+    status: number;
+    success: true;
 };
 /**
- * Strict type for organizations list result.
+ * Strict type for single full scan result.
  */
-export type OrganizationsResult = {
-    cause?: undefined;
-    data: {
-        organizations: OrganizationItem[];
-    };
-    error?: undefined;
+export type FullScanResult = {
+    cause?: undefined | undefined;
+    data: FullScanItem;
+    error?: undefined | undefined;
     status: number;
     success: true;
 };
 /**
- * Strict type for repository item.
+ * Options for streaming a full scan.
  */
-export type RepositoryItem = {
-    id: string;
-    created_at: string;
-    updated_at: string;
-    name: string;
-    organization_id: string;
-    organization_slug: string;
-    default_branch: string | null;
-    homepage: string | null;
-    archived: boolean;
-    visibility: 'public' | 'private' | 'internal';
+export type StreamFullScanOptions = {
+    output?: boolean | string | undefined;
 };
 /**
- * Strict type for repositories list data.
+ * Strict type for organizations list result.
  */
-export type RepositoriesListData = {
-    results: RepositoryItem[];
-    nextPageCursor: string | null;
-    nextPage: number | null;
+export type OrganizationsResult = {
+    cause?: undefined | undefined;
+    data: {
+        organizations: OrganizationItem[];
+    };
+    error?: undefined | undefined;
+    status: number;
+    success: true;
 };
 /**
  * Strict type for repositories list result.
  */
 export type RepositoriesListResult = {
-    cause?: undefined;
+    cause?: undefined | undefined;
     data: RepositoriesListData;
-    error?: undefined;
+    error?: undefined | undefined;
     status: number;
     success: true;
 };
-/**
- * Options for listing repositories.
- */
-export type ListRepositoriesOptions = {
-    sort?: 'name' | 'created_at';
-    direction?: 'asc' | 'desc';
-    per_page?: number;
-    page?: number;
-    startAfterCursor?: string;
-    use_cursor?: boolean;
-};
 /**
  * Strict type for delete operation result.
  */
 export type DeleteResult = {
-    cause?: undefined;
+    cause?: undefined | undefined;
     data: {
         success: boolean;
     };
-    error?: undefined;
+    error?: undefined | undefined;
     status: number;
     success: true;
 };
@@ -203,36 +256,19 @@ export type DeleteResult = {
  * Strict type for single repository result.
  */
 export type RepositoryResult = {
-    cause?: undefined;
+    cause?: undefined | undefined;
     data: RepositoryItem;
-    error?: undefined;
+    error?: undefined | undefined;
     status: number;
     success: true;
 };
-/**
- * Strict type for repository label item.
- */
-export type RepositoryLabelItem = {
-    id: string;
-    name: string;
-    repository_ids?: string[];
-    has_security_policy?: boolean;
-    has_license_policy?: boolean;
-};
-/**
- * Strict type for repository labels list data.
- */
-export type RepositoryLabelsListData = {
-    results: RepositoryLabelItem[];
-    nextPage: number | null;
-};
 /**
  * Strict type for repository labels list result.
  */
 export type RepositoryLabelsListResult = {
-    cause?: undefined;
+    cause?: undefined | undefined;
     data: RepositoryLabelsListData;
-    error?: undefined;
+    error?: undefined | undefined;
     status: number;
     success: true;
 };
@@ -240,9 +276,9 @@ export type RepositoryLabelsListResult = {
  * Strict type for single repository label result.
  */
 export type RepositoryLabelResult = {
-    cause?: undefined;
+    cause?: undefined | undefined;
     data: RepositoryLabelItem;
-    error?: undefined;
+    error?: undefined | undefined;
     status: number;
     success: true;
 };
@@ -250,11 +286,11 @@ export type RepositoryLabelResult = {
  * Strict type for delete repository label result.
  */
 export type DeleteRepositoryLabelResult = {
-    cause?: undefined;
+    cause?: undefined | undefined;
     data: {
         status: string;
     };
-    error?: undefined;
+    error?: undefined | undefined;
     status: number;
     success: true;
 };

package/dist/types.d.ts

@@ -59,6 +59,21 @@ export type ArtifactPatches = {
     patches: PatchRecord[];
 };
 export type Agent = HttpsAgent | HttpAgent | ClientHttp2Session;
+export interface RequestInfo {
+    method: string;
+    url: string;
+    headers?: Record<string, string> | undefined;
+    timeout?: number | undefined;
+}
+export interface ResponseInfo {
+    method: string;
+    url: string;
+    duration: number;
+    status?: number | undefined;
+    statusText?: string | undefined;
+    headers?: Record<string, string> | undefined;
+    error?: Error | undefined;
+}
 export type CompactSocketArtifactAlert = Remap<Omit<SocketArtifactAlert, 'actionSource' | 'category' | 'end' | 'file' | 'start'>>;
 export type CompactSocketArtifact = Remap<Omit<SocketArtifact, 'alerts' | 'alertKeysToReachabilitySummaries' | 'alertKeysToReachabilityTypes' | 'artifact' | 'batchIndex' | 'dead' | 'dependencies' | 'dev' | 'direct' | 'inputPurl' | 'manifestFiles' | 'score' | 'size' | 'topLevelAncestors'> & {
     alerts: CompactSocketArtifactAlert[];
@@ -91,6 +106,12 @@ export type RequestOptions = ((HttpsRequestOptions & {
 })) & {
     timeout?: number | undefined;
 };
+export type RequestOptionsWithHooks = RequestOptions & {
+    hooks?: {
+        onRequest?: ((info: RequestInfo) => void) | undefined;
+        onResponse?: ((info: ResponseInfo) => void) | undefined;
+    } | undefined;
+};
 export type SendMethod = 'POST' | 'PUT';
 export type SendOptions = {
     body?: unknown | undefined;
@@ -107,19 +128,19 @@ export type SocketArtifactAlert = Remap<Omit<components['schemas']['SocketAlert'
 }>;
 export type SocketSdkOperations = keyof operations;
 export type SocketSdkSuccessResult<T extends SocketSdkOperations> = {
-    cause?: undefined;
+    cause?: undefined | undefined;
     data: OpReturnType<operations[T]>;
-    error?: undefined;
+    error?: undefined | undefined;
     status: number;
     success: true;
 };
 export type SocketSdkErrorResult<T extends SocketSdkOperations> = {
     cause?: string | undefined;
-    data?: undefined;
+    data?: undefined | undefined;
     error: string;
     status: number;
     success: false;
-    _operation?: T;
+    _operation?: T | undefined;
 };
 export type SocketSdkResult<T extends SocketSdkOperations> = SocketSdkSuccessResult<T> | SocketSdkErrorResult<T>;
 /**
@@ -136,14 +157,14 @@ export type SocketSdkData<T extends SocketSdkOperations> = OpReturnType<operatio
  */
 export type SocketSdkArrayElement<T extends SocketSdkOperations, K extends keyof SocketSdkData<T>> = SocketSdkData<T>[K] extends Array<infer U> ? U : never;
 export type SocketSdkGenericResult<T> = {
-    cause?: undefined;
+    cause?: undefined | undefined;
     data: T;
-    error?: undefined;
+    error?: undefined | undefined;
     status: number;
     success: true;
 } | {
     cause?: string | undefined;
-    data?: undefined;
+    data?: undefined | undefined;
     error: string;
     status: number;
     success: false;
@@ -196,14 +217,36 @@ 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:
@@ -219,6 +262,11 @@ export interface SocketSdkOptions {
      * @since v3.0.0
      */
     onFileValidation?: FileValidationCallback | undefined;
+    /** Request/response logging hooks */
+    hooks?: {
+        onRequest?: ((info: RequestInfo) => void) | undefined;
+        onResponse?: ((info: ResponseInfo) => void) | undefined;
+    } | undefined;
     /**
      * Number of retry attempts on failure (default: 0, retries disabled).
      * Retries are opt-in following Node.js fs.rm() pattern.
@@ -240,15 +288,15 @@ export type UploadManifestFilesResponse = {
     unmatchedFiles: string[];
 };
 export type UploadManifestFilesReturnType = {
-    cause?: undefined;
+    cause?: undefined | undefined;
     data: UploadManifestFilesResponse;
-    error?: undefined;
+    error?: undefined | undefined;
     status: 200;
     success: true;
 };
 export type UploadManifestFilesError = {
     cause?: string | undefined;
-    data?: undefined;
+    data?: undefined | undefined;
     error: string;
     status: number;
     success: false;
@@ -274,6 +322,17 @@ export type CreateScanFromFilepathsOptions = {
 export type StreamOrgFullScanOptions = {
     output?: boolean | string | undefined;
 };
+export type PostOrgTelemetryPayload = Record<string, unknown>;
+export type PostOrgTelemetryResponse = Record<string, never>;
+/**
+ * Configuration for telemetry collection.
+ * Controls whether telemetry is enabled and how events are collected.
+ */
+export interface TelemetryConfig {
+    telemetry: {
+        enabled: boolean;
+    };
+}
 export type UploadManifestFilesOptions = {
     pathsRelativeTo?: string | undefined;
 };