SDK

@envlet/sdk fetches the values that your token identity can read. It has zero runtime dependencies and supports ESM and CommonJS. Use inject() in Node.js 18 or later. Use load() in edge runtimes that provide fetch.

Install

npm install @envlet/sdk

Set ENVLET_TOKEN in the host platform, or pass the token in the options object.

Public API

These are the public TypeScript declarations:

export interface EnvletOptions {
  token?: string;
  apiUrl?: string;
  retry?: boolean;
}

export interface InjectOptions extends EnvletOptions {
  override?: boolean;
}

export declare class EnvletError extends Error {
  readonly code: string;
  readonly status: number | null;
  constructor(code: string, message: string, status?: number | null);
}

export declare class EnvletAuthError extends EnvletError {
  constructor(code: string, message: string, status: number);
}

export declare class EnvletNotFoundError extends EnvletError {
  constructor(message: string);
}

export declare function load(
  options?: EnvletOptions,
): Promise<Record<string, string>>;

export declare function get(
  name: string,
  options?: EnvletOptions,
): Promise<string>;

export declare function inject(
  options?: InjectOptions,
): Promise<Record<string, string>>;

Configure requests

Every function accepts these request options:

• token uses the given token instead of ENVLET_TOKEN. If neither source has a token, the SDK throws EnvletError with code config_missing before it sends a request.
• apiUrl uses the given API base URL. The next source is ENVLET_API_URL. The final default is https://api.envlet.dev.
• retry enables the default retry policy when it is true or omitted. Set it to false to make one request attempt.

inject() also accepts override. This option controls writes to process.env and does not change which values Envlet resolves.

Inject values into Node.js

Use inject() before your application starts:

import { inject } from "@envlet/sdk";

const values = await inject();

The function fetches all resolved values, writes them to process.env, and returns the fetched Record<string, string>.

The host wins by default. If process.env already has a key, inject() does not replace it. An empty string also counts as an existing host value.

Use override: true when Envlet must replace host values:

import { inject } from "@envlet/sdk";

const values = await inject({ override: true });

inject() needs process.env. In an edge runtime, it throws EnvletError with code unsupported_runtime before it fetches values. Use load() there.

Load values in any fetch runtime

load() fetches all resolved values and returns them without changing global state:

import { load } from "@envlet/sdk";

const values = await load();

In an edge runtime, pass the token because process.env can be absent:

import { load } from "@envlet/sdk";

export async function loadConfig(
  envletToken: string,
): Promise<Record<string, string>> {
  return load({ token: envletToken });
}

The runtime must provide the global Fetch API. load() rejects the full operation if the response does not contain a values object. It does not return a partial record.

Get one value

get() fetches one resolved value:

import { get } from "@envlet/sdk";

const databaseUrl = await get("DATABASE_URL");

The name is URL-encoded before the request. If the value is absent or withheld by policy, get() throws EnvletNotFoundError. These two cases have the same result, so the caller cannot learn whether a withheld key exists.

Typed errors

All SDK error classes extend the built-in Error class. EnvletAuthError and EnvletNotFoundError also extend EnvletError, so one instanceof EnvletError check can handle all typed SDK failures.

EnvletError has a string code and a status that is an HTTP status or null. The SDK throws it directly for these cases:

• No token is available: code is config_missing and status is null.
• inject() has no process.env: code is unsupported_runtime and status is null.
• Network attempts fail: code is network_error and status is null.
• A retried 5xx response still fails: code and status describe the last response.
• Another HTTP error is not 401, 403, or 404: status is the response status.
• A successful load() or get() response has the wrong shape: code is invalid_response and status is null.

EnvletAuthError is thrown immediately for HTTP 401 and 403 responses. Its code, message, and status describe the authentication or authorization failure.

EnvletNotFoundError is thrown immediately for any HTTP 404 response. Its code is not_found and its status is 404.

Retry behavior

Retries are on by default. The SDK makes at most three attempts for network errors and HTTP 5xx responses. It waits 400 ms before the second attempt and 1600 ms before the third attempt.

The SDK does not retry 401, 403, 404, other 4xx responses, missing configuration, unsupported runtimes, or invalid successful response shapes. Set retry: false to disable retries for network and 5xx failures.

After the last attempt, the promise rejects with the last network or 5xx EnvletError. The SDK does not return stale values after a failed fetch.

Fetch values at boot

Call inject(), load(), or get() during application boot and let a failure stop startup. The SDK has no cache, snapshot, polling loop, or background refresh.

Each explicit function call starts a request. inject() uses the same all-values request as load(). If you fetch only at boot, restart the application to pick up Envlet changes.