@socketsecurity/sdk 3.1.2 → 3.2.0

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

@@ -1,4 +1,4 @@
-import type { ArtifactPatches, BatchPackageFetchResultType, BatchPackageStreamOptions, CreateDependenciesSnapshotOptions, Entitlement, GetOptions, PatchViewResponse, QueryParams, SendOptions, SocketSdkGenericResult, SocketSdkOptions, SocketSdkResult, StreamOrgFullScanOptions, UploadManifestFilesError, UploadManifestFilesOptions, UploadManifestFilesReturnType } from './types';
+import type { ArtifactPatches, BatchPackageFetchResultType, BatchPackageStreamOptions, CreateDependenciesSnapshotOptions, Entitlement, GetOptions, PatchViewResponse, PostOrgTelemetryPayload, PostOrgTelemetryResponse, QueryParams, SendOptions, SocketSdkGenericResult, SocketSdkOptions, SocketSdkResult, StreamOrgFullScanOptions, UploadManifestFilesError, UploadManifestFilesOptions, UploadManifestFilesReturnType } from './types';
 import type { CreateFullScanOptions, DeleteRepositoryLabelResult, DeleteResult, FullScanListResult, FullScanResult, ListFullScansOptions, ListRepositoriesOptions, OrganizationsResult, RepositoriesListResult, RepositoryLabelResult, RepositoryLabelsListResult, RepositoryResult, StrictErrorResult } from './types-strict';
 import type { IncomingMessage } from 'node:http';
 /**
@@ -140,6 +140,32 @@ export declare class SocketSdk {
      * @throws {Error} When server returns 5xx status codes
      */
     createRepositoryLabel(orgSlug: string, labelData: QueryParams): Promise<RepositoryLabelResult | StrictErrorResult>;
+    /**
+     * Create a full scan from an archive file (.tar, .tar.gz/.tgz, or .zip).
+     * Uploads and scans a compressed archive of project files.
+     *
+     * @param orgSlug - Organization identifier
+     * @param archivePath - Path to the archive file to upload
+     * @param options - Scan configuration options including repo, branch, and metadata
+     * @returns Created full scan details with scan ID and status
+     *
+     * @throws {Error} When server returns 5xx status codes or file cannot be read
+     */
+    createOrgFullScanFromArchive(orgSlug: string, archivePath: string, options: {
+        branch?: string | undefined;
+        commit_hash?: string | undefined;
+        commit_message?: string | undefined;
+        committers?: string | undefined;
+        integration_org_slug?: string | undefined;
+        integration_type?: 'api' | 'azure' | 'bitbucket' | 'github' | 'gitlab' | 'web' | undefined;
+        make_default_branch?: boolean | undefined;
+        pull_request?: number | undefined;
+        repo: string;
+        scan_type?: string | undefined;
+        set_as_pending_head?: boolean | undefined;
+        tmp?: boolean | undefined;
+        workspace?: string | undefined;
+    }): Promise<SocketSdkResult<'CreateOrgFullScanArchive'>>;
     /**
      * Delete a diff scan from an organization.
      * Permanently removes diff scan data and results.
@@ -288,6 +314,59 @@ export declare class SocketSdk {
      * @throws {Error} When server returns 5xx status codes
      */
     getIssuesByNpmPackage(pkgName: string, version: string): Promise<SocketSdkResult<'getIssuesByNPMPackage'>>;
+    /**
+     * List latest alerts for an organization (Beta).
+     * Returns paginated alerts with comprehensive filtering options.
+     *
+     * @param orgSlug - Organization identifier
+     * @param options - Optional query parameters for pagination and filtering
+     * @returns Paginated list of alerts with cursor-based pagination
+     *
+     * @throws {Error} When server returns 5xx status codes
+     */
+    getOrgAlertsList(orgSlug: string, options?: {
+        'filters.alertAction'?: string | undefined;
+        'filters.alertAction.notIn'?: string | undefined;
+        'filters.alertCategory'?: string | undefined;
+        'filters.alertCategory.notIn'?: string | undefined;
+        'filters.alertCveId'?: string | undefined;
+        'filters.alertCveId.notIn'?: string | undefined;
+        'filters.alertCveTitle'?: string | undefined;
+        'filters.alertCveTitle.notIn'?: string | undefined;
+        'filters.alertCweId'?: string | undefined;
+        'filters.alertCweId.notIn'?: string | undefined;
+        'filters.alertCweName'?: string | undefined;
+        'filters.alertCweName.notIn'?: string | undefined;
+        'filters.alertEPSS'?: string | undefined;
+        'filters.alertEPSS.notIn'?: string | undefined;
+        'filters.alertFixType'?: string | undefined;
+        'filters.alertFixType.notIn'?: string | undefined;
+        'filters.alertKEV'?: boolean | undefined;
+        'filters.alertKEV.notIn'?: boolean | undefined;
+        'filters.alertPriority'?: string | undefined;
+        'filters.alertPriority.notIn'?: string | undefined;
+        'filters.alertReachabilityType'?: string | undefined;
+        'filters.alertReachabilityType.notIn'?: string | undefined;
+        'filters.alertSeverity'?: string | undefined;
+        'filters.alertSeverity.notIn'?: string | undefined;
+        'filters.alertStatus'?: string | undefined;
+        'filters.alertStatus.notIn'?: string | undefined;
+        'filters.alertType'?: string | undefined;
+        'filters.alertType.notIn'?: string | undefined;
+        'filters.alertUpdatedAt.eq'?: string | undefined;
+        'filters.alertUpdatedAt.gt'?: string | undefined;
+        'filters.alertUpdatedAt.gte'?: string | undefined;
+        'filters.alertUpdatedAt.lt'?: string | undefined;
+        'filters.alertUpdatedAt.lte'?: string | undefined;
+        'filters.repoFullName'?: string | undefined;
+        'filters.repoFullName.notIn'?: string | undefined;
+        'filters.repoLabels'?: string | undefined;
+        'filters.repoLabels.notIn'?: string | undefined;
+        'filters.repoSlug'?: string | undefined;
+        'filters.repoSlug.notIn'?: string | undefined;
+        per_page?: number | undefined;
+        startAfterCursor?: string | undefined;
+    }): Promise<SocketSdkResult<'alertsList'>>;
     /**
      * Get analytics data for organization usage patterns and security metrics.
      * Returns statistical analysis for specified time period.
@@ -405,6 +484,25 @@ export declare class SocketSdk {
      * @throws {Error} When server returns 5xx status codes
      */
     getFullScanMetadata(orgSlug: string, scanId: string): Promise<FullScanResult | StrictErrorResult>;
+    /**
+     * Fetch available fixes for vulnerabilities in a repository or scan.
+     * Returns fix recommendations including version upgrades and update types.
+     *
+     * @param orgSlug - Organization identifier
+     * @param options - Fix query options including repo_slug or full_scan_id, vulnerability IDs, and preferences
+     * @returns Fix details for requested vulnerabilities with upgrade recommendations
+     *
+     * @throws {Error} When server returns 5xx status codes
+     */
+    getOrgFixes(orgSlug: string, options: {
+        allow_major_updates: boolean;
+        full_scan_id?: string | undefined;
+        include_details?: boolean | undefined;
+        include_responsible_direct_dependencies?: boolean | undefined;
+        minimum_release_age?: string | undefined;
+        repo_slug?: string | undefined;
+        vulnerability_ids: string;
+    }): Promise<SocketSdkResult<'fetch-fixes'>>;
     /**
      * Get organization's license policy configuration.* Returns allowed, restricted, and monitored license types.
      *
@@ -781,7 +879,145 @@ export declare class SocketSdk {
      * const fileContent = await sdk.downloadPatch(patch.files['index.js'].socketBlob)
      * ```
      */
+    downloadOrgFullScanFilesAsTar(orgSlug: string, fullScanId: string, outputPath: string): Promise<SocketSdkResult<'downloadOrgFullScanFilesAsTar'>>;
+    /**
+     * Download patch file content from Socket blob storage.
+     * Retrieves patched file contents using SSRI hash or hex hash.
+     *
+     * This is a low-level utility method - you'll typically use this after calling
+     * `viewPatch()` to get patch metadata, then download individual patched files.
+     *
+     * @param hash - The blob hash in SSRI (sha256-base64) or hex format
+     * @param options - Optional configuration
+     * @param options.baseUrl - Override blob store URL (for testing)
+     * @returns Promise<string> - The patch file content as UTF-8 string
+     * @throws Error if blob not found (404) or download fails
+     *
+     * @example
+     * ```typescript
+     * const sdk = new SocketSdk('your-api-token')
+     * // First get patch metadata
+     * const patch = await sdk.viewPatch('my-org', 'patch-uuid')
+     * // Then download the actual patched file
+     * const fileContent = await sdk.downloadPatch(patch.files['index.js'].socketBlob)
+     * ```
+     */
     downloadPatch(hash: string, options?: {
         baseUrl?: string;
     }): Promise<string>;
+    /**
+     * Update organization's telemetry configuration.
+     * Enables or disables telemetry for the organization.
+     *
+     * @param orgSlug - Organization identifier
+     * @param telemetryData - Telemetry configuration with enabled flag
+     * @returns Updated telemetry configuration
+     *
+     * @throws {Error} When server returns 5xx status codes
+     */
+    updateOrgTelemetryConfig(orgSlug: string, telemetryData: {
+        enabled?: boolean | undefined;
+    }): Promise<SocketSdkResult<'updateOrgTelemetryConfig'>>;
+    /**
+     * Get organization's telemetry configuration.
+     * Returns whether telemetry is enabled for the organization.
+     *
+     * @param orgSlug - Organization identifier
+     * @returns Telemetry configuration with enabled status
+     *
+     * @throws {Error} When server returns 5xx status codes
+     */
+    getOrgTelemetryConfig(orgSlug: string): Promise<SocketSdkResult<'getOrgTelemetryConfig'>>;
+    /**
+     * Post telemetry data for an organization.
+     * Sends telemetry events and analytics data for monitoring and analysis.
+     *
+     * @param orgSlug - Organization identifier
+     * @param telemetryData - Telemetry payload containing events and metrics
+     * @returns Empty object on successful submission
+     *
+     * @throws {Error} When server returns 5xx status codes
+     */
+    postOrgTelemetry(orgSlug: string, telemetryData: PostOrgTelemetryPayload): Promise<SocketSdkGenericResult<PostOrgTelemetryResponse>>;
+    /**
+     * Create a new webhook for an organization.
+     * Webhooks allow you to receive HTTP POST notifications when specific events occur.
+     *
+     * @param orgSlug - Organization identifier
+     * @param webhookData - Webhook configuration including name, URL, secret, and events
+     * @returns Created webhook details including webhook ID
+     *
+     * @throws {Error} When server returns 5xx status codes
+     */
+    createOrgWebhook(orgSlug: string, webhookData: {
+        description?: null | string | undefined;
+        events: string[];
+        filters?: {
+            repositoryIds: null | string[];
+        } | null | undefined;
+        headers?: null | Record<string, unknown> | undefined;
+        name: string;
+        secret: string;
+        url: string;
+    }): Promise<SocketSdkResult<'createOrgWebhook'>>;
+    /**
+     * Delete a webhook from an organization.
+     * This will stop all future webhook deliveries to the webhook URL.
+     *
+     * @param orgSlug - Organization identifier
+     * @param webhookId - Webhook ID to delete
+     * @returns Success status
+     *
+     * @throws {Error} When server returns 5xx status codes
+     */
+    deleteOrgWebhook(orgSlug: string, webhookId: string): Promise<SocketSdkResult<'deleteOrgWebhook'>>;
+    /**
+     * Get details of a specific webhook.
+     * Returns webhook configuration including events, URL, and filters.
+     *
+     * @param orgSlug - Organization identifier
+     * @param webhookId - Webhook ID to retrieve
+     * @returns Webhook details
+     *
+     * @throws {Error} When server returns 5xx status codes
+     */
+    getOrgWebhook(orgSlug: string, webhookId: string): Promise<SocketSdkResult<'getOrgWebhook'>>;
+    /**
+     * List all webhooks for an organization.
+     * Supports pagination and sorting options.
+     *
+     * @param orgSlug - Organization identifier
+     * @param options - Optional query parameters for pagination and sorting
+     * @returns List of webhooks with pagination info
+     *
+     * @throws {Error} When server returns 5xx status codes
+     */
+    getOrgWebhooksList(orgSlug: string, options?: {
+        direction?: string | undefined;
+        page?: number | undefined;
+        per_page?: number | undefined;
+        sort?: string | undefined;
+    }): Promise<SocketSdkResult<'getOrgWebhooksList'>>;
+    /**
+     * Update an existing webhook's configuration.
+     * All fields are optional - only provided fields will be updated.
+     *
+     * @param orgSlug - Organization identifier
+     * @param webhookId - Webhook ID to update
+     * @param webhookData - Updated webhook configuration
+     * @returns Updated webhook details
+     *
+     * @throws {Error} When server returns 5xx status codes
+     */
+    updateOrgWebhook(orgSlug: string, webhookId: string, webhookData: {
+        description?: null | string | undefined;
+        events?: string[] | undefined;
+        filters?: {
+            repositoryIds: null | string[];
+        } | null | undefined;
+        headers?: null | Record<string, unknown> | undefined;
+        name?: string | undefined;
+        secret?: null | string | undefined;
+        url?: string | undefined;
+    }): Promise<SocketSdkResult<'updateOrgWebhook'>>;
 }

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.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;
+        onResponse?: (info: ResponseInfo) => void;
+    } | undefined;
+};
 export type SendMethod = 'POST' | 'PUT';
 export type SendOptions = {
     body?: unknown | undefined;
@@ -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;
+        onResponse?: (info: ResponseInfo) => void;
+    } | undefined;
     /**
      * Number of retry attempts on failure (default: 0, retries disabled).
      * Retries are opt-in following Node.js fs.rm() pattern.
@@ -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;
 };

package/dist/utils.d.ts

@@ -26,3 +26,64 @@ export declare function resolveAbsPaths(filepaths: string[], pathsRelativeTo?: s
  * Converts relative paths to absolute using current working directory as reference.
  */
 export declare function resolveBasePath(pathsRelativeTo?: string): string;
+/**
+ * Calculate Jaccard similarity coefficient between two strings based on word sets.
+ * Returns a value between 0 (no overlap) and 1 (identical word sets).
+ *
+ * Formula: |A ∩ B| / |A ∪ B|
+ *
+ * @param str1 - First string to compare
+ * @param str2 - Second string to compare
+ * @returns Similarity coefficient (0-1)
+ *
+ * @example
+ * ```typescript
+ * calculateWordSetSimilarity('hello world', 'world hello') // 1.0 (same words)
+ * calculateWordSetSimilarity('hello world', 'goodbye world') // 0.33 (1/3 overlap)
+ * calculateWordSetSimilarity('hello', 'goodbye') // 0 (no overlap)
+ * ```
+ */
+export declare function calculateWordSetSimilarity(str1: string, str2: string): number;
+/**
+ * Determine if a "reason" string should be omitted due to high similarity with error message.
+ * Uses Jaccard similarity to detect redundant phrasing.
+ *
+ * @param errorMessage - Main error message
+ * @param reason - Detailed reason/cause string
+ * @param threshold - Similarity threshold (0-1), defaults to 0.6
+ * @returns true if reason should be omitted (too similar)
+ *
+ * @example
+ * ```typescript
+ * shouldOmitReason('Invalid token', 'The token is invalid') // true (high overlap)
+ * shouldOmitReason('Request failed', 'Rate limit exceeded') // false (low overlap)
+ * ```
+ */
+export declare function shouldOmitReason(errorMessage: string, reason: string | undefined, threshold?: number): boolean;
+/**
+ * Filter error cause based on similarity to error message.
+ * Returns undefined if the cause should be omitted due to redundancy.
+ *
+ * Intelligently handles common error message patterns by:
+ * - Comparing full messages
+ * - Splitting on colons and comparing each part
+ * - Finding the highest similarity among all parts
+ *
+ * Examples:
+ * - "Socket API Request failed (400): Bad Request" vs "Bad Request"
+ * - "Error: Authentication: Token expired" vs "Token expired"
+ *
+ * @param errorMessage - Main error message
+ * @param errorCause - Detailed error cause/reason
+ * @param threshold - Similarity threshold (0-1), defaults to 0.6
+ * @returns The error cause if it should be kept, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * filterRedundantCause('Invalid token', 'The token is invalid') // undefined
+ * filterRedundantCause('Request failed', 'Rate limit exceeded') // 'Rate limit exceeded'
+ * filterRedundantCause('API Request failed (400): Bad Request', 'Bad Request') // undefined
+ * filterRedundantCause('Error: Auth: Token expired', 'Token expired') // undefined
+ * ```
+ */
+export declare function filterRedundantCause(errorMessage: string, errorCause: string | undefined, threshold?: number): string | undefined;

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@socketsecurity/sdk",
-  "version": "3.1.2",
+  "version": "3.2.0",
+  "packageManager": "pnpm@10.25.0",
   "license": "MIT",
   "description": "SDK for the Socket API client",
   "author": {
@@ -45,24 +46,29 @@
     "lint": "node scripts/lint.mjs",
     "precommit": "pnpm run check --lint --staged",
     "prepare": "husky",
+    "ci:validate": "node scripts/ci-validate.mjs",
     "prepublishOnly": "echo 'ERROR: Use GitHub Actions workflow for publishing' && exit 1",
     "publish": "node scripts/publish.mjs",
+    "publish:ci": "node scripts/publish.mjs --skip-git --skip-build --tag ${DIST_TAG:-latest}",
     "claude": "node scripts/claude.mjs",
     "test": "node scripts/test.mjs",
     "type": "tsgo --noEmit -p .config/tsconfig.check.json",
     "update": "node scripts/update.mjs"
   },
+  "dependencies": {
+    "@socketregistry/packageurl-js": "1.3.5",
+    "@socketsecurity/lib": "5.0.0",
+    "form-data": "4.0.5"
+  },
   "devDependencies": {
     "@babel/generator": "7.28.5",
     "@babel/parser": "7.26.3",
     "@babel/traverse": "7.26.4",
     "@babel/types": "7.26.3",
     "@biomejs/biome": "2.2.4",
-    "@dotenvx/dotenvx": "1.49.0",
+    "@dotenvx/dotenvx": "^1.51.1",
     "@eslint/compat": "1.3.2",
     "@eslint/js": "9.35.0",
-    "@socketregistry/packageurl-js": "1.3.5",
-    "@socketsecurity/lib": "3.1.3",
     "@types/babel__traverse": "7.28.0",
     "@types/node": "24.9.2",
     "@typescript/native-preview": "7.0.0-dev.20250926.1",
@@ -83,10 +89,9 @@
     "husky": "9.1.7",
     "magic-string": "0.30.14",
     "nock": "14.0.10",
-    "npm-run-all2": "8.0.4",
     "openapi-typescript": "6.7.6",
     "semver": "7.7.2",
-    "taze": "19.6.0",
+    "taze": "19.9.2",
     "type-coverage": "2.29.7",
     "typescript-eslint": "8.44.1",
     "vitest": "4.0.3",
@@ -103,7 +108,7 @@
   },
   "engines": {
     "node": ">=18",
-    "pnpm": ">=10.16.0"
+    "pnpm": ">=10.25.0"
   },
   "files": [
     "CHANGELOG.md",