@socketsecurity/sdk 3.1.3 → 3.2.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ 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/).
 
+## [3.2.0](https://github.com/SocketDev/socket-sdk-js/releases/tag/v3.2.0) - 2025-12-08
+
+### Added
+
+- New API methods:
+  - `getOrgTelemetryConfig()` - Get organization telemetry configuration
+  - `updateOrgTelemetryConfig()` - Update organization telemetry configuration
+  - `getOrgWebhooksList()` - List organization webhooks
+  - `createOrgWebhook()` - Create organization webhook
+  - `getOrgWebhook()` - Get organization webhook details
+  - `updateOrgWebhook()` - Update organization webhook
+  - `deleteOrgWebhook()` - Delete organization webhook
+  - `getOrgAlertsList()` - List organization alerts
+  - `getOrgFixes()` - Get available vulnerability fixes for repositories or scans
+  - `createOrgFullScanFromArchive()` - Create full scan from archive file (.tar, .tar.gz/.tgz, or .zip)
+  - `downloadOrgFullScanFilesAsTar()` - Download full scan files as tarball to local filesystem
+- Per-endpoint TTL configuration: `cacheTtl` option accepts object with endpoint-specific TTL values (e.g., `{ default: 300_000, getIssues: 600_000 }`)
+- Request/response logging: `hooks` option with `onRequest(info)` and `onResponse(info)` callbacks for debugging and monitoring
+- PURL batch processing: `cachedResultsOnly` query parameter (return only cached results, skip new scans) and `summary` query parameter (include summary with counts of malformed, resolved, and not found PURLs) in `batchPackageFetch()` and `batchPackageStream()`
+- UTF-8 filename support: `uploadManifestFiles()`, `createFullScan()`, `createDependenciesSnapshot()`, and `createOrgFullScanFromArchive()` automatically handle international filenames (Japanese, Cyrillic, emoji, and other UTF-8 characters)
+
+### Changed
+
+- Updated `@socketsecurity/lib` to v5.0.0
+- Synced with OpenAPI definition
+
 ## [3.1.3](https://github.com/SocketDev/socket-sdk-js/releases/tag/v3.1.3) - 2025-11-04
 
 ### Fixed
@@ -455,9 +481,9 @@ To migrate from v1.x to v2.0:
 
 ### Changed
 - Synced with OpenAPI definition
-  - Added new `/openapi.json` endpoint for retrieving API specification in JSON format
-  - Updated repo label filter descriptions to document empty string ("") usage for repositories with no labels
-  - Added 'dual' threat category type
+- Added new `/openapi.json` endpoint for retrieving API specification in JSON format
+- Updated repo label filter descriptions to document empty string ("") usage for repositories with no labels
+- Added 'dual' threat category type
 
 ## [1.8.4](https://github.com/SocketDev/socket-sdk-js/releases/tag/v1.8.4) - 2025-10-01
 

package/README.md

@@ -2,42 +2,20 @@
 
 [![Socket Badge](https://socket.dev/api/badge/npm/package/@socketsecurity/sdk)](https://socket.dev/npm/package/@socketsecurity/sdk)
 [![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)
+![Coverage](https://img.shields.io/badge/coverage-79.95%25-green)
 
 [![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)
 
-JavaScript SDK for [Socket.dev](https://socket.dev/) API - Security analysis, vulnerability scanning, and compliance monitoring for software supply chains.
+JavaScript SDK for [Socket.dev](https://socket.dev/) API.
 
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [API Methods](#api-methods) - [Full API Reference](./docs/api-reference.md)
-- [Documentation](#documentation)
-- [Examples](#examples)
-
-## At a Glance
-
-| Feature | Description |
-|---------|-------------|
-| **Package Analysis** | Quick security checks for npm packages |
-| **Full Scans** | Deep analysis with SBOM support |
-| **Batch Operations** | Analyze multiple packages efficiently |
-| **Policy Management** | Configure security & license rules |
-| **Quota Utilities** | Cost calculation & planning helpers |
-| **TypeScript** | Full type safety with auto-generated types |
-
-**Requirements:** Node.js 18+ ·ESM only (v2.0+)
-
-## Installation
+## Install
 
 ```bash
 pnpm add @socketsecurity/sdk
 ```
 
-**Note:** Version 2.0+ is ESM-only. For CommonJS support, use version 1.x.
-
-## Quick Start
+## Usage
 
 ```typescript
 import { SocketSdk } from '@socketsecurity/sdk'
@@ -69,107 +47,13 @@ const batchResult = await client.batchPackageFetch({
 })
 ```
 
-**[→ Configuration](./docs/api-reference.md#configuration)**
-
-## API Methods
-
-### Package Analysis
-
-Quick security checks: `batchPackageFetch()` ·`batchPackageStream()` ·`getIssuesByNpmPackage()` ·`getScoreByNpmPackage()`
-
-[→ Documentation](./docs/api-reference.md#package-analysis)
-
-### Scanning & Analysis
-
-Project scanning: `createDependenciesSnapshot()` ·`createOrgFullScan()` ·`createScanFromFilepaths()` ·`getScan()` ·`getScanList()` ·`getSupportedScanFiles()`
-
-[→ Documentation](./docs/api-reference.md#scanning--analysis)
-
-### Organization Management
-
-Organizations and repositories: `getOrganizations()` ·`createOrgRepo()` ·`getOrgRepo()` ·`getOrgRepoList()` ·`updateOrgRepo()` ·`deleteOrgRepo()`
-
-[→ Documentation](./docs/api-reference.md#organization-management)
-
-### Policy & Settings
-
-Security configuration: `getOrgSecurityPolicy()` ·`updateOrgSecurityPolicy()` ·`getOrgLicensePolicy()` ·`updateOrgLicensePolicy()` ·`postSettings()`
-
-[→ Documentation](./docs/api-reference.md#policy--settings)
-
-### Full Scan Management
-
-Deep analysis: `getOrgFullScanList()` ·`getOrgFullScanMetadata()` ·`getOrgFullScanBuffered()` ·`streamOrgFullScan()` ·`deleteOrgFullScan()`
-
-[→ Documentation](./docs/api-reference.md#full-scan-management)
-
-### Diff Scans
-
-Scan comparison: `createOrgDiffScanFromIds()` ·`getDiffScanById()` ·`listOrgDiffScans()` ·`deleteOrgDiffScan()`
-
-[→ Documentation](./docs/api-reference.md#diff-scans)
-
-### Patches & Vulnerabilities
-
-Security fixes: `streamPatchesFromScan()` ·`viewPatch()`
-
-[→ Documentation](./docs/api-reference.md#patches--vulnerabilities)
-
-### Alert & Triage
-
-Alert management: `getOrgTriage()` ·`updateOrgAlertTriage()`
-
-[→ Documentation](./docs/api-reference.md#alert--triage)
-
-### Export & Integration
-
-SBOM export: `exportCDX()` ·`exportSPDX()` ·`searchDependencies()` ·`uploadManifestFiles()`
-
-[→ Documentation](./docs/api-reference.md#export--integration)
-
-### Repository Labels
-
-Categorization: `createOrgRepoLabel()` ·`getOrgRepoLabel()` ·`getOrgRepoLabelList()` ·`updateOrgRepoLabel()` ·`deleteOrgRepoLabel()`
-
-[→ Documentation](./docs/api-reference.md#repository-labels)
-
-### Analytics & Monitoring
-
-Usage metrics: `getQuota()` ·`getOrgAnalytics()` ·`getRepoAnalytics()` ·`getAuditLogEvents()`
-
-[→ Documentation](./docs/api-reference.md#analytics--monitoring)
-
-### Authentication & Access
-
-API tokens: `getAPITokens()` ·`postAPIToken()` ·`postAPITokensRotate()` ·`postAPITokensRevoke()` ·`postAPITokenUpdate()`
-
-[→ Documentation](./docs/api-reference.md#authentication--access)
-
-### Entitlements
-
-Feature access: `getEnabledEntitlements()` ·`getEntitlements()`
-
-[→ Documentation](./docs/api-reference.md#entitlements)
-
-### Quota Utilities
-
-Cost helpers: `getQuotaCost()` ·`getRequiredPermissions()` ·`calculateTotalQuotaCost()` ·`hasQuotaForMethods()` ·`getMethodsByQuotaCost()` ·`getMethodsByPermissions()` ·`getQuotaUsageSummary()` ·`getAllMethodRequirements()`
-
-[→ Documentation](./docs/quota-management.md)
-
-### Advanced Query Methods
-
-Raw API access: `getApi()` ·`sendApi()`
-
-[→ Documentation](./docs/api-reference.md#advanced-query-methods)
-
 ## Documentation
 
 | Guide | Description |
 |-------|-------------|
+| **[Getting Started](./docs/getting-started.md)** | Quick start for contributors (5 min setup) |
 | **[API Reference](./docs/api-reference.md)** | Complete API method documentation |
 | **[Usage Examples](./docs/usage-examples.md)** | Real-world patterns and code samples |
-| **[Getting Started](./docs/getting-started.md)** | Development setup and workflow |
 | **[Quota Management](./docs/quota-management.md)** | Cost tiers (0/10/100) and utilities |
 | **[Testing Guide](./docs/dev/testing.md)** | Test helpers, fixtures, and patterns |
 | **[Method Reference](./docs/when-to-use-what.md)** | Quick method selection guide |
@@ -183,14 +67,6 @@ See **[usage-examples.md](./docs/usage-examples.md)** for complete examples incl
 - Policy management
 - Quota planning
 
-## Related Projects
-
-| Project | Description |
-|---------|-------------|
-| [Socket.dev API](https://docs.socket.dev/reference) | Official REST API documentation |
-| [Socket CLI](https://github.com/SocketDev/socket-cli) | Command-line interface |
-| [Socket GitHub App](https://github.com/apps/socket-security) | Automated GitHub integration |
-
 ## License
 
 MIT

package/dist/constants.d.ts

@@ -4,6 +4,9 @@ export declare const DEFAULT_USER_AGENT: string;
 export declare const DEFAULT_HTTP_TIMEOUT = 30000;
 export declare const DEFAULT_RETRIES = 3;
 export declare const DEFAULT_RETRY_DELAY = 1000;
+export declare const DEFAULT_CACHE_TTL: number;
+export declare const RECOMMENDED_CACHE_TTL_ORGANIZATIONS: number;
+export declare const RECOMMENDED_CACHE_TTL_QUOTA: number;
 export declare const MAX_HTTP_TIMEOUT: number;
 export declare const MIN_HTTP_TIMEOUT = 5000;
 export declare const MAX_RESPONSE_SIZE: number;

package/dist/file-upload.d.ts

@@ -1,6 +1,5 @@
-import { Readable } from 'node:stream';
-import type { RequestOptions } from './types';
-import type { ReadStream } from 'node:fs';
+import FormData from 'form-data';
+import type { RequestOptionsWithHooks } from './types';
 import type { IncomingMessage } from 'node:http';
 /**
  * Create multipart form-data body parts for file uploads.
@@ -8,16 +7,16 @@ import type { IncomingMessage } from 'node:http';
  *
  * @throws {Error} When file cannot be read (ENOENT, EACCES, EISDIR, etc.)
  */
-export declare function createRequestBodyForFilepaths(filepaths: string[], basePath: string): Array<Array<string | ReadStream>>;
+export declare function createRequestBodyForFilepaths(filepaths: string[], basePath: string): FormData;
 /**
  * Create multipart form-data body part for JSON data.
  * Converts JSON object to readable stream with appropriate headers.
  */
-export declare function createRequestBodyForJson(jsonData: unknown, basename?: string): Array<string | Readable>;
+export declare function createRequestBodyForJson(jsonData: unknown, basename?: string): FormData;
 /**
- * Create and execute a multipart/form-data upload request.
- * Streams large files efficiently with backpressure handling and early server validation.
+ * Create and execute a multipart/form-data upload request using form-data library.
+ * Streams large files efficiently with automatic backpressure handling and early server validation.
  *
  * @throws {Error} When network errors occur or stream processing fails
  */
-export declare function createUploadRequest(baseUrl: string, urlPath: string, requestBodyNoBoundaries: Array<string | Readable | Array<string | Readable>>, options: RequestOptions): Promise<IncomingMessage>;
+export declare function createUploadRequest(baseUrl: string, urlPath: string, form: FormData, options?: RequestOptionsWithHooks | undefined): Promise<IncomingMessage>;

package/dist/http-client.d.ts

@@ -4,8 +4,12 @@
  */
 import http from 'node:http';
 import https from 'node:https';
-import type { RequestOptions, SendMethod } from './types';
+import type { RequestOptionsWithHooks, SendMethod } from './types';
+import type { JsonValue } from '@socketsecurity/lib/json/types';
 import type { ClientRequest, IncomingMessage } from 'node:http';
+/**
+ * Array of sensitive header names that should be redacted in logs
+ */
 /**
  * HTTP response error for Socket API requests.
  * Extends Error with response details for debugging failed API calls.
@@ -24,7 +28,7 @@ export declare class ResponseError extends Error {
  *
  * @throws {Error} When network or timeout errors occur
  */
-export declare function createDeleteRequest(baseUrl: string, urlPath: string, options: RequestOptions): Promise<IncomingMessage>;
+export declare function createDeleteRequest(baseUrl: string, urlPath: string, options?: RequestOptionsWithHooks | undefined): Promise<IncomingMessage>;
 /**
  * Create and execute an HTTP GET request.
  * Returns the response stream for further processing.
@@ -32,7 +36,7 @@ export declare function createDeleteRequest(baseUrl: string, urlPath: string, op
  *
  * @throws {Error} When network or timeout errors occur
  */
-export declare function createGetRequest(baseUrl: string, urlPath: string, options: RequestOptions): Promise<IncomingMessage>;
+export declare function createGetRequest(baseUrl: string, urlPath: string, options?: RequestOptionsWithHooks | undefined): Promise<IncomingMessage>;
 /**
  * Create and execute an HTTP request with JSON payload.
  * Automatically sets appropriate content headers and serializes the body.
@@ -40,7 +44,7 @@ export declare function createGetRequest(baseUrl: string, urlPath: string, optio
  *
  * @throws {Error} When network or timeout errors occur
  */
-export declare function createRequestWithJson(method: SendMethod, baseUrl: string, urlPath: string, json: unknown, options: RequestOptions): Promise<IncomingMessage>;
+export declare function createRequestWithJson(method: SendMethod, baseUrl: string, urlPath: string, json: unknown, options?: RequestOptionsWithHooks | undefined): Promise<IncomingMessage>;
 /**
  * Read the response body from an HTTP error response.
  * Accumulates all chunks into a complete string for error handling.
@@ -70,7 +74,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 | undefined): Promise<import("@socketsecurity/lib/json").JsonValue | undefined>;
+export declare function getResponseJson(response: IncomingMessage, method?: string | undefined): Promise<JsonValue | undefined>;
 /**
  * Check if HTTP response has a successful status code (2xx range).
  * Returns true for status codes between 200-299, false otherwise.
@@ -99,7 +103,7 @@ export declare function withRetry<T>(fn: () => Promise<T>, retries?: number, ret
  * @param retries - Number of retry attempts (default: 0, retries disabled)
  * @param retryDelay - Initial delay in ms (default: 100)
  */
-export declare function createGetRequestWithRetry(baseUrl: string, urlPath: string, options: RequestOptions, retries?: number, retryDelay?: number): Promise<IncomingMessage>;
+export declare function createGetRequestWithRetry(baseUrl: string, urlPath: string, options?: RequestOptionsWithHooks | undefined, retries?: number, retryDelay?: number): Promise<IncomingMessage>;
 /**
  * Create DELETE request with automatic retry logic.
  * Retries on network errors and 5xx responses.
@@ -107,7 +111,7 @@ export declare function createGetRequestWithRetry(baseUrl: string, urlPath: stri
  * @param retries - Number of retry attempts (default: 0, retries disabled)
  * @param retryDelay - Initial delay in ms (default: 100)
  */
-export declare function createDeleteRequestWithRetry(baseUrl: string, urlPath: string, options: RequestOptions, retries?: number, retryDelay?: number): Promise<IncomingMessage>;
+export declare function createDeleteRequestWithRetry(baseUrl: string, urlPath: string, options?: RequestOptionsWithHooks | undefined, retries?: number, retryDelay?: number): Promise<IncomingMessage>;
 /**
  * Create request with JSON payload and automatic retry logic.
  * Retries on network errors and 5xx responses.
@@ -115,4 +119,4 @@ export declare function createDeleteRequestWithRetry(baseUrl: string, urlPath: s
  * @param retries - Number of retry attempts (default: 0, retries disabled)
  * @param retryDelay - Initial delay in ms (default: 100)
  */
-export declare function createRequestWithJsonAndRetry(method: SendMethod, baseUrl: string, urlPath: string, json: unknown, options: RequestOptions, retries?: number, retryDelay?: number): Promise<IncomingMessage>;
+export declare function createRequestWithJsonAndRetry(method: SendMethod, baseUrl: string, urlPath: string, json: unknown, options?: RequestOptionsWithHooks | undefined, retries?: number, retryDelay?: number): Promise<IncomingMessage>;

package/dist/index.d.ts

@@ -3,13 +3,13 @@
  * Provides the SocketSdk class and utility functions for Socket security analysis API interactions.
  */
 import { DEFAULT_USER_AGENT, httpAgentNames, publicPolicy } from './constants';
-import { normalizeBaseUrl, promiseWithResolvers, queryToSearchParams, resolveAbsPaths, resolveBasePath } from './utils';
+import { calculateWordSetSimilarity, filterRedundantCause, normalizeBaseUrl, promiseWithResolvers, queryToSearchParams, resolveAbsPaths, resolveBasePath, shouldOmitReason } from './utils';
 export { createRequestBodyForFilepaths, createRequestBodyForJson, createUploadRequest, } from './file-upload';
 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 { ALERT_ACTION, ALERT_TYPE, Agent, ArtifactPatches, BatchPackageFetchResultType, BatchPackageStreamOptions, CompactSocketArtifact, CompactSocketArtifactAlert, CreateDependenciesSnapshotOptions, CreateOrgFullScanOptions, CreateScanFromFilepathsOptions, CustomResponseType, Entitlement, EntitlementsResponse, FileValidationCallback, FileValidationResult, GetOptions, GotOptions, HeadersRecord, PatchFile, PatchRecord, PatchViewResponse, QueryParams, RequestOptions, SecurityAlert, SendMethod, SendOptions, SocketArtifact, SocketArtifactAlert, SocketArtifactWithExtras, SocketId, SocketMetricSchema, SocketSdkArrayElement, SocketSdkData, SocketSdkErrorResult, SocketSdkGenericResult, SocketSdkOperations, SocketSdkOptions, SocketSdkResult, SocketSdkSuccessResult, StreamOrgFullScanOptions, UploadManifestFilesError, UploadManifestFilesOptions, UploadManifestFilesResponse, UploadManifestFilesReturnType, Vulnerability, } from './types';
+export type { ALERT_ACTION, ALERT_TYPE, Agent, ArtifactPatches, BatchPackageFetchResultType, BatchPackageStreamOptions, CompactSocketArtifact, CompactSocketArtifactAlert, CreateDependenciesSnapshotOptions, CreateOrgFullScanOptions, CreateScanFromFilepathsOptions, CustomResponseType, Entitlement, EntitlementsResponse, FileValidationCallback, FileValidationResult, GetOptions, GotOptions, HeadersRecord, PatchFile, PatchRecord, PatchViewResponse, TelemetryConfig, PostOrgTelemetryPayload, PostOrgTelemetryResponse, QueryParams, RequestInfo, RequestOptions, RequestOptionsWithHooks, ResponseInfo, SecurityAlert, SendMethod, SendOptions, SocketArtifact, SocketArtifactAlert, SocketArtifactWithExtras, SocketId, SocketMetricSchema, SocketSdkArrayElement, SocketSdkData, SocketSdkErrorResult, SocketSdkGenericResult, SocketSdkOperations, SocketSdkOptions, SocketSdkResult, SocketSdkSuccessResult, StreamOrgFullScanOptions, UploadManifestFilesError, UploadManifestFilesOptions, UploadManifestFilesResponse, UploadManifestFilesReturnType, Vulnerability, } from './types';
 export type { CreateFullScanOptions, DeleteRepositoryLabelResult, DeleteResult, FullScanItem, FullScanListData, FullScanListResult, FullScanResult, ListFullScansOptions, ListRepositoriesOptions, OrganizationItem, OrganizationsResult, RepositoriesListData, RepositoriesListResult, RepositoryItem, RepositoryLabelItem, RepositoryLabelResult, RepositoryLabelsListData, RepositoryLabelsListResult, RepositoryResult, StreamFullScanOptions, StrictErrorResult, StrictResult, } from './types-strict';
 export { createUserAgentFromPkgJson } from './user-agent';
-export { normalizeBaseUrl, promiseWithResolvers, queryToSearchParams, resolveAbsPaths, resolveBasePath, };
+export { calculateWordSetSimilarity, filterRedundantCause, normalizeBaseUrl, promiseWithResolvers, queryToSearchParams, resolveAbsPaths, resolveBasePath, shouldOmitReason, };
 export { DEFAULT_USER_AGENT, httpAgentNames, publicPolicy };