Create a client

Configure the SDK once, at startup, then use it anywhere without passing the key again.

import { init } from '@goenvless/sdk'

init({ token: process.env.ENVLESS_TOKEN })

import { envless } from '@goenvless/sdk'

const workspace = await envless.workspace.get()

envless is a live handle on whatever init installed. Importing it does not read the token, and nothing is resolved until you touch a property on it, so import order between your entrypoint and your modules does not matter.

Three ways to build it#

They differ only in who holds the instance and where the token comes from. Mix them freely; they do not interfere.

import { envless, init } from '@goenvless/sdk'

init({ token: process.env.ENVLESS_TOKEN })

await envless.products.list()

import { createClient } from '@goenvless/sdk'

const envless = createClient()

await envless.products.list()

import { Envless } from '@goenvless/sdk'

const envless = new Envless({ token: 'ev_sk_...' })

await envless.products.list()

init and createClient both fall back to ENVLESS_TOKEN and ENVLESS_API_ENDPOINT when process exists, and throw An Envless API key is required. Pass { token } or set ENVLESS_TOKEN. when no token can be found. new Envless() has no environment fallback for either one, so it throws that same message unless you pass token yourself.

Working with more than one workspace#

A key is bound to one workspace, so reaching two means two clients. init holds exactly one, so use createClient for the rest, or for all of them.

import { createClient, envless, init } from '@goenvless/sdk'

init({ token: process.env.ENVLESS_TOKEN })

const staging = createClient({ token: process.env.ENVLESS_STAGING_TOKEN })

const [live, preview] = await Promise.all([
    envless.variables.listAll('api', 'production'),
    staging.variables.listAll('api', 'production')
])

Two escape hatches for the default client#

import { getClient, rotateWorkspacePassphrase } from '@goenvless/sdk'

await rotateWorkspacePassphrase({
    client: getClient(),
    workspaceUniqueId,
    from: oldPassphrase,
    to: newPassphrase,
    project: 'billing',
    environment: 'production'
})

In tests, init with an injected fetch and tear it down afterwards, so no suite leaks a client into the next one:

import { envless, init, resetClient } from '@goenvless/sdk'

beforeEach(() => init({ token: 'ev_sk_test', baseUrl: 'https://api.test', fetch: stub }))
afterEach(() => resetClient())

test('lists products', async () => {
    await envless.products.list()
})

Options#

const envless = createClient({
    token: process.env.ENVLESS_TOKEN,
    baseUrl: 'http://localhost:2222',
    maxRetries: 5,
    timeoutMs: 60_000,
    userAgent: 'acme-provisioner/2.1'
})

Retries#

The client retries only when retrying is safe. Two conditions must both hold:

Backoff doubles off a 250ms base, so the first retry waits 500ms, then 1s, then 2s, and every delay is capped at 30 seconds. A Retry-After header is read as a number of seconds and replaces the computed delay whenever it parses above zero, under that same 30 second cap. A date-form Retry-After does not parse and is ignored.

A request that produced no response at all, a refused connection or a DNS failure, throws EnvlessNetworkError on the spot. There is no status to classify, so it is never retried.

Cancellation#

Every method takes an options.signal. It is combined with the per-request timeout rather than replacing it, so whichever fires first wins. Raise timeoutMs if a single request needs longer than 30 seconds.

const controller = new AbortController()

setTimeout(() => controller.abort(), 5_000)

const products = await envless.products.listAll({ signal: controller.signal })

const signal = AbortSignal.any([
    controller.signal,
    AbortSignal.timeout(10_000)
])

await envless.products.listAll({ signal })

An aborted request throws EnvlessNetworkError, not EnvlessApiError, because nothing came back from the server to classify.

Injecting fetch#

The fetch option takes any function with the standard signature, which makes the whole client trivially testable with no network and no mocking framework.

const calls: Array<string> = []

const envless = new Envless({
    token: 'ev_sk_test',
    baseUrl: 'https://api.test',
    fetch: async (url, init) => {
        calls.push(`${init?.method ?? 'GET'} ${url}`)

        return new Response(JSON.stringify({
            success: true,
            code: 200,
            message: 'OK',
            error: null,
            data: { products: [], pagination: { limit: 25, offset: 0, totalCount: 0, hasMore: false } }
        }), { status: 200 })
    }
})

await envless.products.list()

calls   // ['GET https://api.test/products']

A bare list() sends no query string at all: limit, offset, search and order are only appended when you pass them, and the API applies its own default of 25. Ask for list({ limit: 25 }) and the call becomes GET https://api.test/products?limit=25.

It is also the seam for a proxy, a request logger, or an outbound rate limiter shared with the rest of your service.

The raw escape hatch#

envless.raw is the underlying transport. It unwraps the response envelope, applies the same retry policy, and throws the same typed errors, so you keep every guarantee while reaching something the typed namespaces do not cover yet.

const payload = await envless.raw.request<{ products: Array<unknown> }>('/products', {
    method: 'GET',
    query: { limit: 5, order: 'desc' }
})

Reuse one client#

A client holds no connection state and no cursor, just configuration. Build one per process and share it. Building one per request costs nothing but buys nothing either.