@socketsecurity/sdk 1.10.1 → 1.11.1

package/dist/testing.d.ts

@@ -0,0 +1,453 @@
+/**
+ * @fileoverview Testing utilities for Socket SDK.
+ * Provides mock factories, response builders, and test helpers for easier SDK testing.
+ */
+import type { SocketSdkErrorResult, SocketSdkGenericResult, SocketSdkOperations, SocketSdkSuccessResult } from './types';
+/**
+ * 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)
+ * ```
+ */
+export declare function mockSuccessResponse<T>(data: T, status?: number): SocketSdkGenericResult<T>;
+/**
+ * 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)
+ * ```
+ */
+export declare function mockErrorResponse<T>(error: string, status?: number, cause?: string): SocketSdkGenericResult<T>;
+/**
+ * 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'))
+ * ```
+ */
+export declare function mockApiErrorBody(message: string, details?: Record<string, unknown>): {
+    error: {
+        message: string;
+        details?: Record<string, unknown>;
+    };
+};
+/**
+ * Common fixture data for organization responses.
+ */
+export declare const organizationFixtures: {
+    /**
+     * Basic organization with minimal data.
+     */
+    readonly basic: {
+        readonly id: "org_123";
+        readonly name: "test-org";
+        readonly plan: "free";
+    };
+    /**
+     * Organization with full details.
+     */
+    readonly full: {
+        readonly id: "org_123";
+        readonly name: "test-org";
+        readonly plan: "enterprise";
+        readonly created_at: "2024-01-01T00:00:00Z";
+        readonly updated_at: "2024-01-02T00:00:00Z";
+    };
+};
+/**
+ * Common fixture data for repository responses.
+ */
+export declare const repositoryFixtures: {
+    /**
+     * Basic repository with minimal data.
+     */
+    readonly basic: {
+        readonly id: "repo_123";
+        readonly name: "test-repo";
+        readonly archived: false;
+        readonly default_branch: "main";
+    };
+    /**
+     * Archived repository.
+     */
+    readonly archived: {
+        readonly id: "repo_456";
+        readonly name: "old-repo";
+        readonly archived: true;
+        readonly default_branch: "master";
+    };
+    /**
+     * Repository with full details.
+     */
+    readonly full: {
+        readonly id: "repo_123";
+        readonly name: "test-repo";
+        readonly archived: false;
+        readonly default_branch: "main";
+        readonly homepage: "https://example.com";
+        readonly visibility: "public";
+        readonly created_at: "2024-01-01T00:00:00Z";
+        readonly updated_at: "2024-01-02T00:00:00Z";
+    };
+};
+/**
+ * Common fixture data for scan responses.
+ */
+export declare const scanFixtures: {
+    /**
+     * Pending scan.
+     */
+    readonly pending: {
+        readonly id: "scan_pending";
+        readonly status: "pending";
+        readonly created_at: "2024-01-01T00:00:00Z";
+    };
+    /**
+     * Completed scan with no issues.
+     */
+    readonly completed: {
+        readonly id: "scan_completed";
+        readonly status: "completed";
+        readonly created_at: "2024-01-01T00:00:00Z";
+        readonly completed_at: "2024-01-01T00:01:00Z";
+        readonly issues_found: 0;
+    };
+    /**
+     * Completed scan with issues.
+     */
+    readonly withIssues: {
+        readonly id: "scan_with_issues";
+        readonly status: "completed";
+        readonly created_at: "2024-01-01T00:00:00Z";
+        readonly completed_at: "2024-01-01T00:01:00Z";
+        readonly issues_found: 3;
+    };
+    /**
+     * Failed scan.
+     */
+    readonly failed: {
+        readonly id: "scan_failed";
+        readonly status: "failed";
+        readonly created_at: "2024-01-01T00:00:00Z";
+        readonly error: "Scan timeout";
+    };
+};
+/**
+ * Common fixture data for package/artifact responses.
+ */
+export declare const packageFixtures: {
+    /**
+     * Safe package with high score.
+     */
+    readonly safe: {
+        readonly id: "pkg_safe";
+        readonly name: "safe-package";
+        readonly version: "1.0.0";
+        readonly score: 95;
+    };
+    /**
+     * Package with vulnerabilities.
+     */
+    readonly vulnerable: {
+        readonly id: "pkg_vuln";
+        readonly name: "vulnerable-package";
+        readonly version: "2.0.0";
+        readonly score: 45;
+        readonly issues: readonly ["vulnerability"];
+    };
+    /**
+     * Package with malware alert.
+     */
+    readonly malware: {
+        readonly id: "pkg_malware";
+        readonly name: "malware-package";
+        readonly version: "3.0.0";
+        readonly score: 0;
+        readonly issues: readonly ["malware"];
+    };
+};
+/**
+ * Common fixture data for issue/alert responses.
+ */
+export declare const issueFixtures: {
+    /**
+     * Vulnerability issue.
+     */
+    readonly vulnerability: {
+        readonly type: "vulnerability";
+        readonly severity: "high";
+        readonly key: "CVE-2024-1234";
+        readonly description: "SQL Injection vulnerability";
+    };
+    /**
+     * Malware issue.
+     */
+    readonly malware: {
+        readonly type: "malware";
+        readonly severity: "critical";
+        readonly key: "malware-detected";
+        readonly description: "Malicious code detected";
+    };
+    /**
+     * License issue.
+     */
+    readonly license: {
+        readonly type: "license";
+        readonly severity: "medium";
+        readonly key: "license-incompatible";
+        readonly description: "License incompatible with project";
+    };
+};
+/**
+ * All fixture categories in one object.
+ */
+export declare const fixtures: {
+    readonly issues: {
+        /**
+         * Vulnerability issue.
+         */
+        readonly vulnerability: {
+            readonly type: "vulnerability";
+            readonly severity: "high";
+            readonly key: "CVE-2024-1234";
+            readonly description: "SQL Injection vulnerability";
+        };
+        /**
+         * Malware issue.
+         */
+        readonly malware: {
+            readonly type: "malware";
+            readonly severity: "critical";
+            readonly key: "malware-detected";
+            readonly description: "Malicious code detected";
+        };
+        /**
+         * License issue.
+         */
+        readonly license: {
+            readonly type: "license";
+            readonly severity: "medium";
+            readonly key: "license-incompatible";
+            readonly description: "License incompatible with project";
+        };
+    };
+    readonly organizations: {
+        /**
+         * Basic organization with minimal data.
+         */
+        readonly basic: {
+            readonly id: "org_123";
+            readonly name: "test-org";
+            readonly plan: "free";
+        };
+        /**
+         * Organization with full details.
+         */
+        readonly full: {
+            readonly id: "org_123";
+            readonly name: "test-org";
+            readonly plan: "enterprise";
+            readonly created_at: "2024-01-01T00:00:00Z";
+            readonly updated_at: "2024-01-02T00:00:00Z";
+        };
+    };
+    readonly packages: {
+        /**
+         * Safe package with high score.
+         */
+        readonly safe: {
+            readonly id: "pkg_safe";
+            readonly name: "safe-package";
+            readonly version: "1.0.0";
+            readonly score: 95;
+        };
+        /**
+         * Package with vulnerabilities.
+         */
+        readonly vulnerable: {
+            readonly id: "pkg_vuln";
+            readonly name: "vulnerable-package";
+            readonly version: "2.0.0";
+            readonly score: 45;
+            readonly issues: readonly ["vulnerability"];
+        };
+        /**
+         * Package with malware alert.
+         */
+        readonly malware: {
+            readonly id: "pkg_malware";
+            readonly name: "malware-package";
+            readonly version: "3.0.0";
+            readonly score: 0;
+            readonly issues: readonly ["malware"];
+        };
+    };
+    readonly repositories: {
+        /**
+         * Basic repository with minimal data.
+         */
+        readonly basic: {
+            readonly id: "repo_123";
+            readonly name: "test-repo";
+            readonly archived: false;
+            readonly default_branch: "main";
+        };
+        /**
+         * Archived repository.
+         */
+        readonly archived: {
+            readonly id: "repo_456";
+            readonly name: "old-repo";
+            readonly archived: true;
+            readonly default_branch: "master";
+        };
+        /**
+         * Repository with full details.
+         */
+        readonly full: {
+            readonly id: "repo_123";
+            readonly name: "test-repo";
+            readonly archived: false;
+            readonly default_branch: "main";
+            readonly homepage: "https://example.com";
+            readonly visibility: "public";
+            readonly created_at: "2024-01-01T00:00:00Z";
+            readonly updated_at: "2024-01-02T00:00:00Z";
+        };
+    };
+    readonly scans: {
+        /**
+         * Pending scan.
+         */
+        readonly pending: {
+            readonly id: "scan_pending";
+            readonly status: "pending";
+            readonly created_at: "2024-01-01T00:00:00Z";
+        };
+        /**
+         * Completed scan with no issues.
+         */
+        readonly completed: {
+            readonly id: "scan_completed";
+            readonly status: "completed";
+            readonly created_at: "2024-01-01T00:00:00Z";
+            readonly completed_at: "2024-01-01T00:01:00Z";
+            readonly issues_found: 0;
+        };
+        /**
+         * Completed scan with issues.
+         */
+        readonly withIssues: {
+            readonly id: "scan_with_issues";
+            readonly status: "completed";
+            readonly created_at: "2024-01-01T00:00:00Z";
+            readonly completed_at: "2024-01-01T00:01:00Z";
+            readonly issues_found: 3;
+        };
+        /**
+         * Failed scan.
+         */
+        readonly failed: {
+            readonly id: "scan_failed";
+            readonly status: "failed";
+            readonly created_at: "2024-01-01T00:00:00Z";
+            readonly error: "Scan timeout";
+        };
+    };
+};
+/**
+ * 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' })
+ * )
+ * ```
+ */
+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>;
+/**
+ * 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' })
+ * )
+ * ```
+ */
+export declare function mockSdkError(type: 'NOT_FOUND' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'SERVER_ERROR' | 'TIMEOUT', options?: {
+    cause?: string;
+    message?: string;
+    status?: number;
+}): Error & {
+    status: number;
+    cause?: string;
+};
+/**
+ * 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
+ * }
+ * ```
+ */
+export declare function isSuccessResult<T>(result: SocketSdkGenericResult<T>): result is Extract<SocketSdkGenericResult<T>, {
+    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
+ * }
+ * ```
+ */
+export declare function isErrorResult<T>(result: SocketSdkGenericResult<T>): result is Extract<SocketSdkGenericResult<T>, {
+    success: false;
+}>;