@socketsecurity/lib 5.15.0 → 5.17.0

package/dist/env/socket-cli.d.ts

@@ -2,6 +2,15 @@
  * Whether to accept all Socket CLI risks (alternative name).
  *
  * @returns Whether to accept all risks
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliAcceptRisks } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * if (getSocketCliAcceptRisks()) {
+ *   console.log('All risks accepted')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliAcceptRisks(): boolean;
@@ -10,6 +19,14 @@ export declare function getSocketCliAcceptRisks(): boolean;
  * Checks SOCKET_CLI_API_BASE_URL first, then falls back to legacy SOCKET_SECURITY_API_BASE_URL.
  *
  * @returns API base URL or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliApiBaseUrl } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const baseUrl = getSocketCliApiBaseUrl()
+ * // e.g. 'https://api.socket.dev' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliApiBaseUrl(): string | undefined;
@@ -19,6 +36,14 @@ export declare function getSocketCliApiBaseUrl(): string | undefined;
  * Follows the same precedence as v1.x: HTTPS_PROXY → https_proxy → HTTP_PROXY → http_proxy.
  *
  * @returns API proxy URL or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliApiProxy } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const proxy = getSocketCliApiProxy()
+ * // e.g. 'http://proxy.example.com:8080' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliApiProxy(): string | undefined;
@@ -26,6 +51,14 @@ export declare function getSocketCliApiProxy(): string | undefined;
  * Timeout in milliseconds for Socket CLI API requests (alternative name).
  *
  * @returns API timeout in milliseconds
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliApiTimeout } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const timeout = getSocketCliApiTimeout()
+ * // e.g. 30000 or 0 if not set
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliApiTimeout(): number;
@@ -35,6 +68,14 @@ export declare function getSocketCliApiTimeout(): number;
  * Maintains full v1.x backward compatibility.
  *
  * @returns API token or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliApiToken } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const token = getSocketCliApiToken()
+ * // e.g. a Socket API token string or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliApiToken(): string | undefined;
@@ -43,6 +84,14 @@ export declare function getSocketCliApiToken(): string | undefined;
  * Set by bootstrap wrappers to pass dlx cache location to CLI.
  *
  * @returns Bootstrap cache directory or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliBootstrapCacheDir } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const cacheDir = getSocketCliBootstrapCacheDir()
+ * // e.g. '/tmp/.socket-cli-cache' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliBootstrapCacheDir(): string | undefined;
@@ -51,6 +100,14 @@ export declare function getSocketCliBootstrapCacheDir(): string | undefined;
  * Set by bootstrap wrappers (SEA/smol/npm) to pass package spec to CLI.
  *
  * @returns Bootstrap package spec or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliBootstrapSpec } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const spec = getSocketCliBootstrapSpec()
+ * // e.g. '@socketsecurity/cli@^2.0.11' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliBootstrapSpec(): string | undefined;
@@ -58,6 +115,14 @@ export declare function getSocketCliBootstrapSpec(): string | undefined;
  * Socket CLI configuration file path (alternative name).
  *
  * @returns Config file path or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliConfig } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const config = getSocketCliConfig()
+ * // e.g. '/tmp/project/socket.yml' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliConfig(): string | undefined;
@@ -65,6 +130,14 @@ export declare function getSocketCliConfig(): string | undefined;
  * Controls Socket CLI fix mode.
  *
  * @returns Fix mode value or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliFix } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const fix = getSocketCliFix()
+ * // e.g. 'true' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliFix(): string | undefined;
@@ -73,6 +146,14 @@ export declare function getSocketCliFix(): string | undefined;
  * Checks SOCKET_CLI_GITHUB_TOKEN, SOCKET_SECURITY_GITHUB_PAT, then falls back to GITHUB_TOKEN.
  *
  * @returns GitHub token or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliGithubToken } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const token = getSocketCliGithubToken()
+ * // e.g. 'ghp_abc123...' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliGithubToken(): string | undefined;
@@ -80,6 +161,15 @@ export declare function getSocketCliGithubToken(): string | undefined;
  * Whether to skip Socket CLI API token requirement (alternative name).
  *
  * @returns Whether to skip API token requirement
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliNoApiToken } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * if (getSocketCliNoApiToken()) {
+ *   console.log('API token requirement skipped')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliNoApiToken(): boolean;
@@ -87,6 +177,15 @@ export declare function getSocketCliNoApiToken(): boolean;
  * Controls Socket CLI optimization mode.
  *
  * @returns Whether optimization mode is enabled
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliOptimize } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * if (getSocketCliOptimize()) {
+ *   console.log('Optimization mode enabled')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliOptimize(): boolean;
@@ -95,6 +194,14 @@ export declare function getSocketCliOptimize(): boolean;
  * Checks SOCKET_CLI_ORG_SLUG first, then falls back to SOCKET_ORG_SLUG.
  *
  * @returns Organization slug or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliOrgSlug } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const slug = getSocketCliOrgSlug()
+ * // e.g. 'my-org' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliOrgSlug(): string | undefined;
@@ -102,6 +209,15 @@ export declare function getSocketCliOrgSlug(): string | undefined;
  * Whether to view all Socket CLI risks (alternative name).
  *
  * @returns Whether to view all risks
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliViewAllRisks } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * if (getSocketCliViewAllRisks()) {
+ *   console.log('Viewing all risks')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCliViewAllRisks(): boolean;

package/dist/env/socket.d.ts

@@ -1,90 +1,243 @@
 /**
  * SOCKET_ACCEPT_RISKS environment variable getter.
  * Whether to accept all Socket Security risks.
+ *
+ * @returns `true` if risks are accepted, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getSocketAcceptRisks } from '@socketsecurity/lib/env/socket'
+ *
+ * if (getSocketAcceptRisks()) {
+ *   console.log('All risks accepted')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketAcceptRisks(): boolean;
 /**
  * SOCKET_API_BASE_URL environment variable getter.
  * Socket Security API base URL.
+ *
+ * @returns The API base URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketApiBaseUrl } from '@socketsecurity/lib/env/socket'
+ *
+ * const baseUrl = getSocketApiBaseUrl()
+ * // e.g. 'https://api.socket.dev' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketApiBaseUrl(): string | undefined;
 /**
  * SOCKET_API_PROXY environment variable getter.
  * Proxy URL for Socket Security API requests.
+ *
+ * @returns The API proxy URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketApiProxy } from '@socketsecurity/lib/env/socket'
+ *
+ * const proxy = getSocketApiProxy()
+ * // e.g. 'http://proxy.example.com:8080' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketApiProxy(): string | undefined;
 /**
  * SOCKET_API_TIMEOUT environment variable getter.
  * Timeout in milliseconds for Socket Security API requests.
+ *
+ * @returns The timeout in milliseconds, or `0` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketApiTimeout } from '@socketsecurity/lib/env/socket'
+ *
+ * const timeout = getSocketApiTimeout()
+ * // e.g. 30000 or 0 if not set
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketApiTimeout(): number;
 /**
  * SOCKET_API_TOKEN environment variable getter.
  * Socket Security API authentication token.
+ *
+ * @returns The API token, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketApiToken } from '@socketsecurity/lib/env/socket'
+ *
+ * const token = getSocketApiToken()
+ * // e.g. a Socket API token string or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketApiToken(): string | undefined;
 /**
  * SOCKET_CACACHE_DIR environment variable getter.
  * Overrides the default Socket cacache directory location.
+ *
+ * @returns The cacache directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCacacheDir } from '@socketsecurity/lib/env/socket'
+ *
+ * const dir = getSocketCacacheDir()
+ * // e.g. '/tmp/.socket-cache' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketCacacheDir(): string | undefined;
 /**
  * SOCKET_CONFIG environment variable getter.
  * Socket Security configuration file path.
+ *
+ * @returns The config file path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketConfig } from '@socketsecurity/lib/env/socket'
+ *
+ * const config = getSocketConfig()
+ * // e.g. '/tmp/project/socket.yml' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketConfig(): string | undefined;
 /**
  * SOCKET_DEBUG environment variable getter.
  * Controls Socket-specific debug output.
+ *
+ * @returns The Socket debug filter, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketDebug } from '@socketsecurity/lib/env/socket'
+ *
+ * const debug = getSocketDebug()
+ * // e.g. '*' or 'api' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketDebug(): string | undefined;
 /**
  * SOCKET_DLX_DIR environment variable getter.
  * Overrides the default Socket DLX directory location.
+ *
+ * @returns The DLX directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketDlxDirEnv } from '@socketsecurity/lib/env/socket'
+ *
+ * const dlxDir = getSocketDlxDirEnv()
+ * // e.g. '/tmp/.socket-dlx' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketDlxDirEnv(): string | undefined;
 /**
  * SOCKET_HOME environment variable getter.
  * Socket Security home directory path.
+ *
+ * @returns The Socket home directory, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketHome } from '@socketsecurity/lib/env/socket'
+ *
+ * const home = getSocketHome()
+ * // e.g. '/tmp/.socket' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketHome(): string | undefined;
 /**
  * SOCKET_NO_API_TOKEN environment variable getter.
  * Whether to skip Socket Security API token requirement.
+ *
+ * @returns `true` if the API token requirement is skipped, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getSocketNoApiToken } from '@socketsecurity/lib/env/socket'
+ *
+ * if (getSocketNoApiToken()) {
+ *   console.log('API token requirement skipped')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketNoApiToken(): boolean;
 /**
  * SOCKET_NPM_REGISTRY environment variable getter.
  * Socket NPM registry URL (alternative name).
+ *
+ * @returns The Socket NPM registry URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketNpmRegistry } from '@socketsecurity/lib/env/socket'
+ *
+ * const registry = getSocketNpmRegistry()
+ * // e.g. 'https://npm.socket.dev/' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketNpmRegistry(): string | undefined;
 /**
  * SOCKET_ORG_SLUG environment variable getter.
  * Socket Security organization slug identifier.
+ *
+ * @returns The organization slug, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketOrgSlug } from '@socketsecurity/lib/env/socket'
+ *
+ * const slug = getSocketOrgSlug()
+ * // e.g. 'my-org' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketOrgSlug(): string | undefined;
 /**
  * SOCKET_REGISTRY_URL environment variable getter.
  * Socket Registry URL for package installation.
+ *
+ * @returns The Socket registry URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketRegistryUrl } from '@socketsecurity/lib/env/socket'
+ *
+ * const registryUrl = getSocketRegistryUrl()
+ * // e.g. 'https://registry.socket.dev/' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketRegistryUrl(): string | undefined;
 /**
  * SOCKET_VIEW_ALL_RISKS environment variable getter.
  * Whether to view all Socket Security risks.
+ *
+ * @returns `true` if viewing all risks, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getSocketViewAllRisks } from '@socketsecurity/lib/env/socket'
+ *
+ * if (getSocketViewAllRisks()) {
+ *   console.log('Viewing all risks')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getSocketViewAllRisks(): boolean;

package/dist/env/temp-dir.d.ts

@@ -1,18 +1,48 @@
 /**
  * TEMP environment variable.
  * Windows temporary directory path.
+ *
+ * @returns The Windows temp directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getTemp } from '@socketsecurity/lib/env/temp-dir'
+ *
+ * const temp = getTemp()
+ * // e.g. 'C:\\Windows\\Temp' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getTemp(): string | undefined;
 /**
  * TMP environment variable.
  * Alternative temporary directory path.
+ *
+ * @returns The alternative temp directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getTmp } from '@socketsecurity/lib/env/temp-dir'
+ *
+ * const tmp = getTmp()
+ * // e.g. '/tmp' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getTmp(): string | undefined;
 /**
  * TMPDIR environment variable.
  * Unix/macOS temporary directory path.
+ *
+ * @returns The Unix/macOS temp directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getTmpdir } from '@socketsecurity/lib/env/temp-dir'
+ *
+ * const tmpdir = getTmpdir()
+ * // e.g. '/tmp' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getTmpdir(): string | undefined;

package/dist/env/term.d.ts

@@ -1,2 +1,15 @@
+/**
+ * Returns the value of the TERM environment variable.
+ *
+ * @returns The terminal type identifier, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getTerm } from '@socketsecurity/lib/env/term'
+ *
+ * const term = getTerm()
+ * // e.g. 'xterm-256color' or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getTerm(): string | undefined;

package/dist/env/test.d.ts

@@ -1,18 +1,50 @@
 /**
  * JEST_WORKER_ID environment variable.
  * Set when running tests with Jest.
+ *
+ * @returns The Jest worker ID string, or empty string if not set
+ *
+ * @example
+ * ```typescript
+ * import { getJestWorkerId } from '@socketsecurity/lib/env/test'
+ *
+ * const workerId = getJestWorkerId()
+ * // e.g. '1' when running in Jest, or ''
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getJestWorkerId(): string;
 /**
  * VITEST environment variable.
  * Set when running tests with Vitest.
+ *
+ * @returns `true` if running in Vitest, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getVitest } from '@socketsecurity/lib/env/test'
+ *
+ * if (getVitest()) {
+ *   console.log('Running in Vitest')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getVitest(): boolean;
 /**
  * Check if code is running in a test environment.
  * Checks NODE_ENV, VITEST, and JEST_WORKER_ID.
+ *
+ * @returns `true` if running in a test environment, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isTest } from '@socketsecurity/lib/env/test'
+ *
+ * if (isTest()) {
+ *   console.log('Running in test environment')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isTest(): boolean;

package/dist/env/windows.d.ts

@@ -1,24 +1,64 @@
 /**
  * APPDATA environment variable.
  * Points to the Application Data directory on Windows.
+ *
+ * @returns The Windows AppData roaming directory, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getAppdata } from '@socketsecurity/lib/env/windows'
+ *
+ * const appdata = getAppdata()
+ * // e.g. 'C:\\Users\\Public\\AppData\\Roaming' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getAppdata(): string | undefined;
 /**
  * COMSPEC environment variable.
  * Points to the Windows command processor (typically cmd.exe).
+ *
+ * @returns The path to the command processor, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getComspec } from '@socketsecurity/lib/env/windows'
+ *
+ * const comspec = getComspec()
+ * // e.g. 'C:\\Windows\\system32\\cmd.exe' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getComspec(): string | undefined;
 /**
  * LOCALAPPDATA environment variable.
  * Points to the Local Application Data directory on Windows.
+ *
+ * @returns The Windows local AppData directory, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getLocalappdata } from '@socketsecurity/lib/env/windows'
+ *
+ * const localAppdata = getLocalappdata()
+ * // e.g. 'C:\\Users\\Public\\AppData\\Local' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getLocalappdata(): string | undefined;
 /**
  * USERPROFILE environment variable.
  * Windows user home directory path.
+ *
+ * @returns The Windows user profile directory, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getUserprofile } from '@socketsecurity/lib/env/windows'
+ *
+ * const userprofile = getUserprofile()
+ * // e.g. 'C:\\Users\\Public' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getUserprofile(): string | undefined;

package/dist/env/xdg.d.ts

@@ -1,18 +1,48 @@
 /**
  * XDG_CACHE_HOME environment variable.
  * XDG Base Directory specification cache directory.
+ *
+ * @returns The XDG cache directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getXdgCacheHome } from '@socketsecurity/lib/env/xdg'
+ *
+ * const cacheDir = getXdgCacheHome()
+ * // e.g. '/tmp/.cache' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getXdgCacheHome(): string | undefined;
 /**
  * XDG_CONFIG_HOME environment variable.
  * XDG Base Directory specification config directory.
+ *
+ * @returns The XDG config directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getXdgConfigHome } from '@socketsecurity/lib/env/xdg'
+ *
+ * const configDir = getXdgConfigHome()
+ * // e.g. '/tmp/.config' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getXdgConfigHome(): string | undefined;
 /**
  * XDG_DATA_HOME environment variable.
  * Points to the user's data directory on Unix systems.
+ *
+ * @returns The XDG data directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getXdgDataHome } from '@socketsecurity/lib/env/xdg'
+ *
+ * const dataDir = getXdgDataHome()
+ * // e.g. '/tmp/.local/share' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function getXdgDataHome(): string | undefined;