@socketsecurity/sdk 1.10.1 → 1.11.1

package/CHANGELOG.md

@@ -4,6 +4,25 @@ 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/).
 
+## [1.11.1](https://github.com/SocketDev/socket-sdk-js/releases/tag/v1.11.1) - 2025-10-06
+
+### Added
+- Performance optimizations with memoization for `normalizeBaseUrl` and quota utility functions
+- Performance tracking to HTTP client functions
+- Comprehensive error handling tests for SDK methods across organization, scanning, and batch APIs
+- Reusable assertion helpers for SDK tests
+
+### Changed
+- Improved test coverage and reliability with additional test cases
+- Streamlined documentation (README, TESTING.md, QUOTA.md, EXAMPLES.md) for better clarity and discoverability
+
+## [1.11.0](https://github.com/SocketDev/socket-sdk-js/releases/tag/v1.11.0) - 2025-10-04
+
+### Added
+- Optional TTL caching for API responses with configurable cache duration
+- New `cache` option (default: false) to enable response caching
+- New `cacheTtl` option (default: 5 minutes) to customize cache duration
+
 ## [1.10.1](https://github.com/SocketDev/socket-sdk-js/releases/tag/v1.10.1) - 2025-10-04
 
 ### Added

package/README.md

@@ -6,342 +6,184 @@
 [![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)
 
-Official SDK for Socket.dev - Programmatic access to security analysis, vulnerability scanning, and compliance monitoring for your software supply chain.
+Official SDK for [Socket.dev](https://socket.dev/) - Programmatic access to security analysis, vulnerability scanning, and compliance monitoring for your software supply chain.
 
-## Usage
+## Installation
 
 ```bash
 pnpm add @socketsecurity/sdk
 ```
 
-### ESM / TypeScript
+## Quick Start
 
-```javascript
+```typescript
 import { SocketSdk } from '@socketsecurity/sdk'
 
-const client = new SocketSdk('yourApiKeyHere', {
-  retries: 3,        // Retry failed requests up to 3 times (default: 3)
-  retryDelay: 1000,  // Start with 1s delay, exponential backoff (default: 1000ms)
-  timeout: 30000,    // Request timeout in milliseconds (optional)
+const client = new SocketSdk('your-api-key', {
+  retries: 3,        // Retry failed requests up to 3 times
+  retryDelay: 1000,  // Start with 1s delay, exponential backoff
+  timeout: 30000,    // 30 second timeout
 })
 
-const res = await client.getQuota()
+// Check your quota
+const quota = await client.getQuota()
+if (quota.success) {
+  console.log(`Available quota: ${quota.data.quota} units`)
+}
 
-if (res.success) {
-  // Will output { quota: 123 } if the quota you have left is 123
-  console.log(res.data)
+// Analyze a package
+const result = await client.getScoreByNpmPackage('express', '4.18.0')
+if (result.success) {
+  console.log(`Security Score: ${result.data.score}/100`)
 }
+
+// Batch analyze multiple packages
+const batchResult = await client.batchPackageFetch({
+  components: [
+    { purl: 'pkg:npm/express@4.18.0' },
+    { purl: 'pkg:npm/react@18.0.0' }
+  ]
+})
 ```
 
-### Configuration Options
+**[→ Configuration Options](./docs/API.md#configuration)**
 
-The SDK constructor accepts the following options:
+## API Methods
 
-```typescript
-interface SocketSdkOptions {
-  baseUrl?: string          // API base URL (default: 'https://api.socket.dev/v0/')
-  timeout?: number          // Request timeout in milliseconds
-  retries?: number          // Number of retry attempts for failed requests (default: 3)
-  retryDelay?: number       // Initial retry delay in ms, with exponential backoff (default: 1000)
-  userAgent?: string        // Custom user agent string
-  agent?: Agent             // Custom HTTP agent for advanced networking
-}
-```
+<details>
+<summary><strong>Package Analysis</strong> - Quick security checks</summary>
 
-**Retry Logic:**
-- Automatically retries transient network errors and 5xx server responses
-- Uses exponential backoff: 1s, 2s, 4s, 8s... (configurable via `retryDelay`)
-- Does NOT retry 401/403 authentication errors (immediate failure)
-- Set `retries: 0` to disable retry logic entirely
-
-### Quota Management Example
-
-```javascript
-import {
-  SocketSdk,
-  getQuotaCost,
-  calculateTotalQuotaCost,
-  hasQuotaForMethods
-} from '@socketsecurity/sdk'
-
-const client = new SocketSdk('your-api-key')
-
-// Check quota cost before making API calls
-const batchCost = getQuotaCost('batchPackageFetch') // Returns: 100
-const analyticsCost = getQuotaCost('getOrgAnalytics') // Returns: 10
-
-// Calculate total cost for multiple operations
-const operations = ['batchPackageFetch', 'getOrgAnalytics', 'uploadManifestFiles']
-const totalCost = calculateTotalQuotaCost(operations) // Returns: 210
-
-// Check if you have sufficient quota
-const quotaRes = await client.getQuota()
-if (quotaRes.success && hasQuotaForMethods(quotaRes.data.quota, operations)) {
-  // Proceed with API calls
-  console.log(`Sufficient quota available: ${quotaRes.data.quota} units`)
-} else {
-  console.log('Insufficient quota - consider using free alternatives')
-}
-```
+`batchPackageFetch()` • `batchPackageStream()` • `getIssuesByNpmPackage()` • `getScoreByNpmPackage()`
 
-### CommonJS
+[→ Documentation](./docs/API.md#package-analysis)
+</details>
 
-```javascript
-const { SocketSdk } = require('@socketsecurity/sdk')
-```
+<details>
+<summary><strong>Scanning & Analysis</strong> - Project scanning</summary>
 
-## API Overview
-
-The Socket SDK provides programmatic access to Socket.dev's security analysis platform through 60+ API methods organized into functional categories:
-
-### Package Analysis
-- **Package Security**: Get vulnerability reports, security scores, and issue details for npm packages
-- **Batch Processing**: Analyze multiple packages efficiently with streaming and concurrent processing
-- **PURL Support**: Process Package URLs for comprehensive package identification
-
-### Organization Management
-- **Organizations**: List, manage, and configure organization settings
-- **Repositories**: Create, update, and delete organization repositories
-- **Labels**: Manage repository categorization and tagging systems
-
-### Security Scanning & Analysis
-- **Full Scans**: Create comprehensive security scans from manifest files
-- **Diff Scans**: Compare scans to identify changes and new vulnerabilities
-- **Dependencies**: Upload and analyze project dependency files
-- **Reports**: Generate, retrieve, and manage detailed security reports
-
-### Policy & Compliance
-- **Security Policies**: Configure and update organization security policies
-- **License Policies**: Manage allowed/restricted license types
-- **Alert Triage**: Review and manage security alert statuses
-- **Audit Logs**: Access chronological security and administrative events
-
-### Data Export & Integration
-- **SBOM Export**: Generate CycloneDX and SPDX Software Bill of Materials
-- **Streaming**: Efficient data streaming for large datasets
-- **Analytics**: Access usage metrics and security trend data
-
-### Authentication & Access
-- **API Tokens**: Create, rotate, update, and revoke organization API tokens
-- **Entitlements**: View enabled Socket products and features
-- **Quota Management**: Monitor API usage limits, quotas, and plan method calls
-- **Quota Utilities**: Pre-calculate costs, check permissions, and optimize API usage
-
-### Advanced Features
-- **Patches**: View and stream security patches for vulnerabilities
-- **Custom Queries**: Raw API access with configurable response handling
-- **Cross-platform**: Full Windows, macOS, and Linux compatibility
-
-## SocketSdk Methods
-
-### Package Analysis Methods
-
-* `batchPackageFetch(componentsObj, queryParams?)` - Analyze multiple packages in batch
-  * Returns all results at once after processing is complete
-* `batchPackageStream(componentsObj, options?)` - Stream package analysis with concurrency control
-  * Returns results as they become available via async generator
-* `getIssuesByNpmPackage(packageName, version)` - Get security issues for a specific npm package
-  * Returns detailed vulnerability and security alert information
-* `getScoreByNpmPackage(packageName, version)` - Get security score for a package
-  * Returns numerical security rating and scoring breakdown
-
-### Scanning & Analysis Methods
-
-* `createDependenciesSnapshot(filepaths, pathsRelativeTo='.', queryParams?)` - Create dependency snapshot
-  * Analyzes dependency files to generate comprehensive security report
-* `createOrgFullScan(orgSlug, filepaths, pathsRelativeTo='.', queryParams?)` - Create full organization scan
-  * Uploads project files and initiates complete security analysis
-* `createScanFromFilepaths(filePaths, pathsRelativeTo='.', issueRules?)` - Create security scan from files
-  * Analyzes uploaded files for security vulnerabilities and policy violations
-* `getScan(id)` - Get detailed scan results
-  * Returns complete scan analysis including vulnerabilities and alerts
-* `getScanList()` - List all accessible scans
-  * Returns paginated list of scan metadata and status
-* `getSupportedScanFiles()` - Get supported file formats
-  * Returns supported manifest files, lockfiles, and configuration formats
-
-### Organization Management Methods
-
-* `createOrgRepo(orgSlug, queryParams?)` - Create new repository
-  * Registers repository for monitoring and security scanning
-* `deleteOrgRepo(orgSlug, repoSlug)` - Delete repository
-  * Removes repository monitoring and associated scan data
-* `getOrganizations()` - List accessible organizations
-  * Returns organization details and access permissions
-* `getOrgRepo(orgSlug, repoSlug)` - Get repository details
-  * Returns repository configuration, monitoring status, and metadata
-* `getOrgRepoList(orgSlug, queryParams?)` - List organization repositories
-  * Returns paginated list of repository metadata and status
-* `updateOrgRepo(orgSlug, repoSlug, queryParams?)` - Update repository configuration
-  * Modifies monitoring settings, branch configuration, and scan preferences
-
-### Full Scan Management Methods
-
-* `deleteOrgFullScan(orgSlug, fullScanId)` - Delete full scan
-  * Permanently removes scan data and results
-* `getOrgFullScanBuffered(orgSlug, fullScanId)` - Get complete scan results in memory
-  * Returns entire scan data as JSON for programmatic processing
-* `getOrgFullScanList(orgSlug, queryParams?)` - List organization full scans
-  * Returns paginated list of scan metadata and status
-* `getOrgFullScanMetadata(orgSlug, fullScanId)` - Get scan metadata
-  * Returns scan configuration, status, and summary information
-* `streamOrgFullScan(orgSlug, fullScanId, output?)` - Stream scan results
-  * Provides efficient streaming for large scan datasets to file or stdout
-
-### Policy & Settings Methods
-
-* `getOrgLicensePolicy(orgSlug)` - Get license policy configuration
-  * Returns allowed, restricted, and monitored license types
-* `getOrgSecurityPolicy(orgSlug)` - Get organization security policy
-  * Returns alert rules, severity thresholds, and enforcement settings
-* `postSettings(selectors)` - Update user or organization settings
-  * Configures preferences, notifications, and security policies
-* `updateOrgLicensePolicy(orgSlug, policyData, queryParams?)` - Update license policy
-  * Modifies allowed, restricted, and monitored license types
-* `updateOrgSecurityPolicy(orgSlug, policyData)` - Update security policy
-  * Modifies alert rules, severity thresholds, and enforcement settings
-
-### Analytics & Monitoring Methods
-
-* `getAuditLogEvents(orgSlug, queryParams?)` - Get audit log events
-  * Returns chronological log of security and administrative actions
-* `getOrgAnalytics(time)` - Get organization analytics
-  * Returns statistical analysis for specified time period
-* `getQuota()` - Get current API quota usage
-  * Returns remaining requests, rate limits, and quota reset times
-
-### Quota Utility Functions
-* `getQuotaCost(methodName)` - Get quota cost for any SDK method
-* `getRequiredPermissions(methodName)` - Get required permissions for SDK method
-* `calculateTotalQuotaCost(methodNames[])` - Calculate total cost for multiple methods
-* `hasQuotaForMethods(availableQuota, methodNames[])` - Check if quota is sufficient
-* `getMethodsByQuotaCost(cost)` - Find methods by quota cost (0, 10, 100 units)
-* `getMethodsByPermissions(permissions[])` - Find methods requiring specific permissions
-* `getQuotaUsageSummary()` - Get summary of all methods grouped by quota cost
-* `getAllMethodRequirements()` - Get complete mapping of methods to costs and permissions
-* `getRepoAnalytics(repo, time)` - Get repository analytics
-  * Returns security metrics, dependency trends, and vulnerability statistics
-
-### Authentication & Access Methods
-
-* `getAPITokens(orgSlug)` - List organization API tokens
-  * Returns organization API tokens with metadata and permissions
-* `postAPIToken(orgSlug, tokenData)` - Create new API token
-  * Generates API token with specified scopes and metadata
-* `postAPITokensRevoke(orgSlug, tokenId)` - Revoke API token
-  * Permanently disables the token and removes access
-* `postAPITokensRotate(orgSlug, tokenId)` - Rotate API token
-  * Generates new token value while preserving token metadata
-* `postAPITokenUpdate(orgSlug, tokenId, updateData)` - Update API token
-  * Modifies token metadata, scopes, or other properties
-
-### Export & Integration Methods
-
-* `exportCDX(orgSlug, fullScanId)` - Export CycloneDX SBOM
-  * Returns Software Bill of Materials compliant with CycloneDX standard
-* `exportSPDX(orgSlug, fullScanId)` - Export SPDX SBOM
-  * Returns Software Bill of Materials compliant with SPDX standard
-* `searchDependencies(queryParams?)` - Search monitored dependencies
-  * Returns matching packages with security information and usage patterns
-* `uploadManifestFiles(orgSlug, filepaths, pathsRelativeTo='.')` - Upload manifest files
-  * Processes package files to create dependency snapshots and security analysis
-
-### Alert & Triage Methods
-
-* `getOrgTriage(orgSlug)` - Get organization triage settings
-  * Returns alert triage configuration and current state
-* `updateOrgAlertTriage(orgSlug, alertId, triageData)` - Update alert triage
-  * Modifies alert resolution status and triage decisions
-
-### Repository Label Methods
-
-* `createOrgRepoLabel(orgSlug, repoSlug, labelData)` - Create repository label
-  * Adds label for repository categorization and management
-* `deleteOrgRepoLabel(orgSlug, repoSlug, labelSlug)` - Delete repository label
-  * Removes label and associated configuration
-* `getOrgRepoLabel(orgSlug, repoSlug, labelSlug)` - Get label details
-  * Returns label configuration and metadata
-* `getOrgRepoLabelList(orgSlug, repoSlug)` - List repository labels
-  * Returns all labels configured for repository management
-* `updateOrgRepoLabel(orgSlug, repoSlug, labelSlug, labelData)` - Update repository label
-  * Modifies label properties and configuration
-
-### Diff Scan Methods
-
-* `createOrgDiffScanFromIds(orgSlug, queryParams?)` - Create diff scan from IDs
-  * Compares two existing full scans to identify changes
-* `deleteOrgDiffScan(orgSlug, diffScanId)` - Delete diff scan
-  * Permanently removes diff scan data and results
-* `getDiffScanById(orgSlug, diffScanId)` - Get diff scan details
-  * Returns comparison between two full scans with artifact changes
-* `listOrgDiffScans(orgSlug)` - List organization diff scans
-  * Returns paginated list of diff scan metadata and status
-
-### Patch & Vulnerability Methods
-
-* `streamPatchesFromScan(orgSlug, scanId)` - Stream patches from scan
-  * Returns ReadableStream for processing large patch datasets
-* `viewPatch(orgSlug, uuid)` - View patch details
-  * Retrieves comprehensive patch information including files and vulnerabilities
-
-### Entitlement Methods
-
-* `getEnabledEntitlements(orgSlug)` - Get enabled entitlements
-  * Returns array of enabled Socket product keys
-* `getEntitlements(orgSlug)` - Get all organization entitlements
-  * Returns complete list of entitlements with their status
-
-### Advanced Query Methods
-
-* `getApi<T>(urlPath, options?)` - Execute raw GET request
-  * Direct API access with configurable response type (response, json, text)
-* `sendApi<T>(urlPath, options?)` - Send POST/PUT with JSON body
-  * Direct API access for POST/PUT operations with JSON responses
-
-### Legacy Methods (Deprecated Names)
-
-* `createReportFromFilepaths()` → Use `createScanFromFilepaths()`
-* `deleteReport(reportId)` → Use scan-specific delete methods
-* `getReport(id)` → Use `getScan(id)`
-* `getReportList()` → Use `getScanList()`
-* `getReportSupportedFiles()` → Use `getSupportedScanFiles()`
-
-## Additional exports
-
-* `createUserAgentFromPkgJson(pkgJson)`
-  * `pkgJson`: The content of the `package.json` you want to create a `User-Agent` string for
-
-## Advanced
-
-### Specifying custom user agent
-
-The `SocketSdk` constructor accepts an `options` object as its second argument and there a `userAgent` key with a string value can be specified. If specified then that user agent will be prepended to the SDK user agent. See this example:
-
-```js
-const client = new SocketSdk('yourApiKeyHere', {
-  userAgent: 'example/1.2.3 (http://example.com/)'
-})
-```
+`createDependenciesSnapshot()` • `createOrgFullScan()` • `createScanFromFilepaths()` • `getScan()` • `getScanList()` • `getSupportedScanFiles()`
 
-Which results in the [HTTP `User-Agent` header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/User-Agent):
+[→ Documentation](./docs/API.md#scanning--analysis)
+</details>
 
-```
-User-Agent: example/1.2.3 (http://example.com/) socketsecurity-sdk/0.5.2 (https://github.com/SocketDev/socket-sdk-js)
-```
+<details>
+<summary><strong>Organization Management</strong> - Orgs and repos</summary>
 
-To easily create a user agent for your code you can use the additional export `createUserAgentFromPkgJson()` like this, assuming `pkgJson` contains your parsed `package.json`:
+`getOrganizations()` • `createOrgRepo()` • `getOrgRepo()` • `getOrgRepoList()` • `updateOrgRepo()` • `deleteOrgRepo()`
 
-```js
-const client = new SocketSdk('yourApiKeyHere', {
-  userAgent: createUserAgentFromPkgJson(pkgJson)
-})
-```
+[→ Documentation](./docs/API.md#organization-management)
+</details>
+
+<details>
+<summary><strong>Policy & Settings</strong> - Security configuration</summary>
+
+`getOrgSecurityPolicy()` • `updateOrgSecurityPolicy()` • `getOrgLicensePolicy()` • `updateOrgLicensePolicy()` • `postSettings()`
+
+[→ Documentation](./docs/API.md#policy--settings)
+</details>
+
+<details>
+<summary><strong>Full Scan Management</strong> - Deep analysis</summary>
+
+`getOrgFullScanList()` • `getOrgFullScanMetadata()` • `getOrgFullScanBuffered()` • `streamOrgFullScan()` • `deleteOrgFullScan()`
+
+[→ Documentation](./docs/API.md#full-scan-management)
+</details>
+
+<details>
+<summary><strong>Diff Scans</strong> - Compare scans</summary>
+
+`createOrgDiffScanFromIds()` • `getDiffScanById()` • `listOrgDiffScans()` • `deleteOrgDiffScan()`
+
+[→ Documentation](./docs/API.md#diff-scans)
+</details>
+
+<details>
+<summary><strong>Patches & Vulnerabilities</strong> - Security fixes</summary>
+
+`streamPatchesFromScan()` • `viewPatch()`
+
+[→ Documentation](./docs/API.md#patches--vulnerabilities)
+</details>
+
+<details>
+<summary><strong>Alert & Triage</strong> - Alert management</summary>
+
+`getOrgTriage()` • `updateOrgAlertTriage()`
+
+[→ Documentation](./docs/API.md#alert--triage)
+</details>
+
+<details>
+<summary><strong>Export & Integration</strong> - SBOM export</summary>
+
+`exportCDX()` • `exportSPDX()` • `searchDependencies()` • `uploadManifestFiles()`
+
+[→ Documentation](./docs/API.md#export--integration)
+</details>
+
+<details>
+<summary><strong>Repository Labels</strong> - Categorization</summary>
+
+`createOrgRepoLabel()` • `getOrgRepoLabel()` • `getOrgRepoLabelList()` • `updateOrgRepoLabel()` • `deleteOrgRepoLabel()`
+
+[→ Documentation](./docs/API.md#repository-labels)
+</details>
+
+<details>
+<summary><strong>Analytics & Monitoring</strong> - Usage metrics</summary>
+
+`getQuota()` • `getOrgAnalytics()` • `getRepoAnalytics()` • `getAuditLogEvents()`
+
+[→ Documentation](./docs/API.md#analytics--monitoring)
+</details>
+
+<details>
+<summary><strong>Authentication & Access</strong> - API tokens</summary>
+
+`getAPITokens()` • `postAPIToken()` • `postAPITokensRotate()` • `postAPITokensRevoke()` • `postAPITokenUpdate()`
+
+[→ Documentation](./docs/API.md#authentication--access)
+</details>
+
+<details>
+<summary><strong>Entitlements</strong> - Feature access</summary>
+
+`getEnabledEntitlements()` • `getEntitlements()`
+
+[→ Documentation](./docs/API.md#entitlements)
+</details>
+
+<details>
+<summary><strong>Quota Utilities</strong> - Cost helpers</summary>
+
+`getQuotaCost()` • `getRequiredPermissions()` • `calculateTotalQuotaCost()` • `hasQuotaForMethods()` • `getMethodsByQuotaCost()` • `getMethodsByPermissions()` • `getQuotaUsageSummary()` • `getAllMethodRequirements()`
+
+[→ Documentation](./docs/QUOTA.md)
+</details>
+
+<details>
+<summary><strong>Advanced Query Methods</strong> - Raw API</summary>
+
+`getApi()` • `sendApi()`
+
+[→ Documentation](./docs/API.md#advanced-query-methods)
+</details>
+
+**[→ Complete API Reference](./docs/API.md)**
+
+**[→ Usage Examples](./docs/EXAMPLES.md)**
+
+**[→ Quota Management](./docs/QUOTA.md)** - Cost tiers: 0 units (free), 10 units (standard), 100 units (batch/uploads)
+
+**[→ Testing Utilities](./docs/TESTING.md)** - Mock factories, fixtures, and type guards for SDK testing
+
+## See Also
 
-Specifying a custom user agent is good practice when shipping a piece of code that others can use to make requests. Eg. [our CLI](https://github.com/SocketDev/socket-cli-js) uses this option to identify requests coming from it + mentioning which version of it that is used.
+- [Socket.dev API Reference](https://docs.socket.dev/reference) - Official API documentation
+- [Socket CLI](https://github.com/SocketDev/socket-cli) - Command-line interface
+- [Socket GitHub App](https://github.com/apps/socket-security) - GitHub integration
 
-## See also
+## License
 
-* [Socket API Reference](https://docs.socket.dev/reference)
-* [Socket.dev](https://socket.dev/)
-* [Socket GitHub App](https://github.com/apps/socket-security)
-* [Socket CLI](https://github.com/SocketDev/socket-cli-js)
+MIT