Stashbase Node SDK

The official SDK for Stashbase, a secrets management platform for developers.

Features:

• Manage projects, environments, and secrets from Node.js
• Inject secrets into your process environment
• Simple, promise-based API
• Zero non-development dependencies (security-focused runtime footprint)
• And more...

Table of Contents

• Installation
• Usage
• License

Installation

Install with npm or npm compatible package manager (bun, pnpm, etc.). We recommend using bun for the best experience.

Supported runtime: Node.js 18+.

npm install @stashbase/node-sdk

Usage

For full documentation, please visit Stashbase Node SDK.

Here are some common usage examples for the Stashbase Node SDK:

Secret values are validated by UTF-8 byte length. Maximum secret value size: 16 KB.

Auto client

Use createClient to create a client with explicit scope selection.

import { createClient } from '@stashbase/node-sdk'

const client = createClient({
  apiKey: process.env.STASHBASE_API_KEY,
  scope: 'workspace', // or "environment"
  timeoutMs: 5000, // optional, hard capped at 10000
  retries: 3, // optional, at most 3 total attempts (hard capped at 10)
  hooks: {
    beforeRequest: ({ method, url }) => console.log('[request]', method, url),
    afterResponse: ({ response }) => console.log('[response]', response.status),
    onError: ({ error }) => console.error('[error]', error),
  }, // optional
})
console.log(client.scope) // "workspace" or "environment"

Workspace client

Use workspace client to manage resources in a workspace, you can use Service Account or Personal API key.

import { createWorkspaceClient } from '@stashbase/node-sdk'

const client = createWorkspaceClient(process.env.STASHBASE_API_KEY)
console.log(client.scope) // "workspace"

const client = createWorkspaceClient(process.env.STASHBASE_API_KEY, {
  timeoutMs: 5000, // optional, hard capped at 10000
  retries: 3, // optional, at most 3 total attempts (hard capped at 10)
  hooks: {
    beforeRequest: ({ method, url }) => console.log('[request]', method, url),
  }, // optional
})

List project

const { data, error } = await client.projects.list()

Create environment

const { data, error } = await client.environments({ project: 'project-name' }).create({
  name: 'api-dev',
  isProduction: false,
})

Bind workspace context

const ctx = client.withContext({
  project: 'project-name',
  environment: 'dev',
})

const { data, error } = await ctx.secrets.list()

Get workspace secret metadata

const ctx = client.withContext({
  project: 'project-name',
  environment: 'dev',
})

const { data, error } = await ctx.secrets.getMetadata('HOST')

List workspace secrets metadata

const ctx = client.withContext({
  project: 'project-name',
  environment: 'dev',
})

const { data, error } = await ctx.secrets.listMetadata()

Load environment

This method will load the environment and inject the secrets into the process.

// using workspace client
const { error } = await client.environments({ project: 'project-name' }).load('api-dev')

Environment client

Use environment client to manage resources in a specific environment, using Environment Account API key.

import { createEnvironmentClient } from '@stashbase/node-sdk'

const client = createEnvironmentClient(process.env.STASHBASE_ENV_API_KEY)
console.log(client.scope) // "environment"

const client = createEnvironmentClient(process.env.STASHBASE_ENV_API_KEY, {
  timeoutMs: 5000, // optional, hard capped at 10000
  retries: 3, // optional, at most 3 total attempts (hard capped at 10)
  hooks: {
    beforeRequest: ({ method, url }) => console.log('[request]', method, url),
  }, // optional
})

Timeouts and retries

• Default request timeout is 5000 ms.
• Maximum request timeout is 10000 ms.
• Default maximum attempt count is 3.
• Maximum attempt count is 10.
• timeoutMs is applied per request attempt, not as a total wall-clock budget across all retries.
• Retries are automatic for idempotent requests (GET, PUT, and DELETE) and include rate-limited (429) responses. Mutating POST and PATCH requests are not retried automatically to avoid duplicate side effects.

The transport defaults are also exported from the package root:

import {
  DEFAULT_API_TIMEOUT_MS,
  MAX_API_TIMEOUT_MS,
  DEFAULT_API_RETRIES,
  MAX_API_RETRIES,
} from '@stashbase/node-sdk'

Transport hooks

Hooks can be configured at creation time and updated later at runtime through client.options.hooks.

const client = createWorkspaceClient(process.env.STASHBASE_API_KEY)

client.options.hooks = {
  beforeRequest: ({ method, url }) => console.log('[request]', method, url),
  afterResponse: ({ response }) => console.log('[response]', response.status),
  onError: ({ error }) => console.error('[error]', error),
}

Hook behavior contract:

• beforeRequest: runs before each request attempt.
• afterResponse: runs after receiving a response (including non-2xx).
• onError: runs when request processing throws.
• If beforeRequest or afterResponse throws, request fails with HookExecutionError in response.error.
• If onError throws, that error is ignored and the original request error is preserved.

Per-request options

Use withRequestOptions to apply a timeout or cancellation signal to one operation without changing the client defaults.

const controller = new AbortController()

const response = await client
  .withRequestOptions({ signal: controller.signal, timeoutMs: 2000 })
  .projects.list()

Cancelled and timed-out requests return the stable SDK error codes request.aborted and request.timed_out, respectively.

Error handling

Every SDK method returns an ApiResponse shape:

const response = await client.projects.get('project-name')

if (!response.ok) {
  console.error(response.error.code, response.error.message, response.status)
  return
}

console.log(response.data)

You can also branch on stable error codes:

const response = await client.projects.get('project-name')

if (!response.ok) {
  switch (response.error.code) {
    case 'resource.project_not_found':
      console.log('Project does not exist')
      break
    case 'auth.unauthorized':
      console.log('API key is invalid or missing permissions')
      break
    default:
      console.log(response.error.message)
  }
}

Get environment details

const { data, error } = await client.environment.get()

Load environment

This method will load the environment and inject the secrets into the process.

const { error } = await client.environment.load()

List secrets

const { data, error } = await client.secrets.list()

Get environment secret metadata

const { data, error } = await client.secrets.getMetadata('HOST')

List environment secrets metadata

const { data, error } = await client.secrets.listMetadata()

Type imports

All public SDK types are exported from the package root.

import type { Secret, ListSecretsResponse, GenericApiErrorCode, SecretErrors } from '@stashbase/node-sdk'

Contributing

Bug fixes, documentation improvements, and library improvements are always welcome.

See CONTRIBUTING.md for details.

License

Stashbase Node SDK is licensed under the MIT License. You can find the license in the LICENSE.txt file.