Overview

if you are using Node.js, you can use our official Node.js SDK with first-class Typescript support. This is the easiest way to get started with Stashbase in your Node.js projects.

Installation

You can install the SDK with your preferred package manager.

Usage

As stated in the Getting started section, each SDK has two APIs: Environment and Worspace.

Scope-based client constructor

You can also use createClient to construct the correct client type from the provided scope.

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

const client = createClient({ apiKey: 'test-key', scope: 'workspace' })

Environment Client

Using the Environment Client you can create the SDK client with the createEnvClient function or EnvironmentClient constructor. The function/constructor takes an Environment Account API key as an argument. This account and its API key can be created in your Stashbase dashboard in the selected environment. The API_KEY should be provided as an environment variable.

import { createEnvClient } from '@stashbase/node-sdk'
const stashbase = createEnvClient(process.env.SB_ENVIRONMENT_API_KEY)

Workspace Clien

Using the Workspace Clien you can create the SDK client with the createWorkspaceClient function or WorkspaceClient constructor. The function/constructor takes an API key (personal or service) as an argument. This key can be created in your Stashbase dashboard. The API_KEY should be provided as an environment variable.

import { createWorkspaceClient } from '@stashbase/node-sdk'
const stashbase = createWorkspaceClient(process.env.SB_API_KEY)

// project-scoped search (no environment required)
const { data, error } = await stashbase.searchSecrets({
  project: 'my-project',
  name: 'JWT_KEY',
  returnValues: true,
})

withContext

Use withContext to create a context-bound client that automatically applies project and environment to all subsequent calls, so you don't need to pass them in each request.

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

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

HTTP hooks

You can attach HTTP lifecycle hooks to both transport-level options (ClientTransportOptions) and runtime options (ClientRuntimeOptions).

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

const client = createWorkspaceClient(process.env.SB_API_KEY, {
  hooks: {
    beforeRequest: async ({ method, url, headers }) => {
      headers['x-trace-id'] = 'trace-123'
      console.log(`[request] ${method} ${url}`)
    },
    afterResponse: async ({ method, path, response }) => {
      console.log(`[response] ${method} ${path} -> ${response.status}`)
    },
    onError: async ({ method, path, error }) => {
      console.error(`[error] ${method} ${path}`, error)
    },
  },
})

Available hooks:

• beforeRequest(context)
• afterResponse(context)
• onError(context)

Hook context includes request details like method, path, url, headers, optional timeoutMs, signal, query, data, and either response (afterResponse) or error (onError).

Error handling

Let's face it, JavaScript error handling sucks. There are several issues with JavaScript error handling. Does it throw error? Who handles it? What is the type of the error?

To make the developer experience better, Stashbase Node.JS SDK (as well as SDKs for other languages) returns object with data and error property. Api Errors are categorized into 7 basic error types and those types are used as prefix for the error.code property:

• unexpected - for unexpected errors (eg. internal server error)
• rate_limit - for rate limit errors (eg. too many requests)
• auth - for authentication errors (eg. invalid API key)
• access - for access errors (eg. insufficient permissions)
• validation - for other validation errors (eg. invalid format of property)
• resource - for resource errors (eg. resource not found)
• quota - for subscription limit errors (eg. project limit reached)

The error property is object with code property (e.g. auth.unauthorized, access.missing_permission etc.), property message and details property and methods to check the type of the error.

Each SDK method returns ResponseSuccess or ResponseFailure object.

interface ResponseSuccess<T> {
  ok: true
  error: null
  data: T
}

interface ResponseFailure<K> {
  ok: false
  error: K
  data: null
}

This way you can easily check for errors in a type-safe manner and handle them without the need of using try/catch.

const stashbase = createEnvClient(process.env.SB_ENVIRONMENT_API_KEY)

// Example: list environment secrets
const { data, error } = stashbase.secrets.list()

// check for errors
if (error) {
  // handle error
} else {
  // data has the correct type
}

You can also check for the type of error using helpers.

import { isAuthError, isServerError } from '@stashbase/node-sdk'
const { data, error } = stashbase.secrets.list()

if (error) {
  if (isAuthError(error)) {
    // is auth related error
  } else if (isServerError(error)) {
    // is server related error
  }
}

Reference