Node SDK

The official TypeScript SDK for Burdenoff Workspaces provides a typed GraphQL client, authentication helpers, and modules for workspaces, projects, conversations, files, and more.

Install

bun add @burdenoff/workspaces-sdk
# or
npm install @burdenoff/workspaces-sdk

Environment selection

The SDK endpoint defaults to production. Pass the appropriate endpoint in WorkspacesSDKConfig, or set BURDENOFF_ENV in your shell to derive defaults:

Environment	Workspace endpoint	Global endpoint
`prod` (default)	`https://graphqlworkspaces.burdenoff.com/workspaces/graphql`	`https://graphql.burdenoff.com/global/graphql`
`alpha`	`https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql`	`https://alphagraphql.burdenoff.com/global/graphql`
`local`	`http://localhost:4003/workspaces/graphql`	`http://localhost:4000/global/graphql`

Set BURDENOFF_ENV=local|alpha|prod in your shell if your app consumes it to choose endpoints, or pass them explicitly to WorkspacesSDKConfig.

Quick start

import { WorkspacesSDK } from '@burdenoff/workspaces-sdk';

const sdk = new WorkspacesSDK({
  workspaceEndpoint: 'https://graphqlworkspaces.burdenoff.com/workspaces/graphql',
  globalEndpoint: 'https://graphql.burdenoff.com/global/graphql',
});

// Sign in
await sdk.auth.signIn({ username: '[email protected]', password: 'secret' });

// Fetch workspaces and issue workspace token
const workspaces = await sdk.auth.fetchWorkspaces();
await sdk.auth.issueWorkspaceToken(workspaces[0].id, workspaces[0].organizationId);

// Use the SDK
const projects = await sdk.workspace.listProjects();
const conversations = await sdk.conversation.listChannels();

Authentication

Email / password

const auth = await sdk.auth.signIn({ username: '[email protected]', password: 'secret' });

OAuth2 device code flow

const { userCode, verificationUri, promise } = await sdk.auth.loginWithDeviceCode();
console.log(`Open ${verificationUri} and enter: ${userCode}`);
const tokens = await promise;

OAuth2 authorization code + PKCE

const challenge = sdk.auth.getAuthorizationUrl({
  redirectUri: 'http://localhost:8400/callback',
  scopes: ['openid', 'profile', 'email', 'offline_access'],
});
// Redirect user to challenge.url, then exchange the code:
const tokens = await sdk.auth.exchangeAuthCode(code, challenge.codeVerifier, challenge.redirectUri);

Client credentials (M2M / app auth)

const result = await sdk.auth.authenticateApp(clientId, clientSecret);

Workspace token

await sdk.auth.issueWorkspaceToken(workspaceId, organizationId);

Modules

Module	Access	Description
`sdk.auth`	Auth	Sign in/up, OAuth flows, token management
`sdk.workspace`	CRUD	Workspace and project lifecycle
`sdk.conversation`	CRUD	Channels, direct messages, threads
`sdk.file`	CRUD	File uploads, downloads, metadata
`sdk.tag`	CRUD	Tag creation, assignment, search
`sdk.group`	CRUD	Group and team management
`sdk.rbac`	Read/Check	Role checks, permission queries
`sdk.billing`	Read	Plans, invoices, usage
`sdk.scheduler`	CRUD	Job scheduling and monitoring
`sdk.webhook`	CRUD	Webhook management and testing
`sdk.notification`	CRUD	Notification channel configuration

Configuration

interface WorkspacesSDKConfig {
  workspaceEndpoint: string;   // Workspace gateway GraphQL endpoint
  globalEndpoint: string;      // Global gateway GraphQL endpoint
  oidcIssuer?: string;         // OIDC issuer URL (derived from globalEndpoint if omitted)
  clientId?: string;           // OAuth2 client ID
  clientSecret?: string;       // OAuth2 client secret
  redirectUri?: string;        // Redirect URI for auth code flow
  apiKey?: string;             // API key authentication
  accessToken?: string;        // Pre-existing access token
  refreshToken?: string;       // Pre-existing refresh token
  workspaceToken?: string;     // Pre-existing workspace token
  timeout?: number;            // Request timeout in ms (default: 30000)
  autoRefresh?: boolean;       // Auto-refresh tokens (default: true)
  onTokenRefresh?: (tokens: TokenPair) => void | Promise<void>;
}

Error handling

import { WorkspacesError, AuthenticationError, NetworkError } from '@burdenoff/workspaces-sdk';

try {
  await sdk.auth.signIn({ username: 'invalid', password: 'invalid' });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Auth failed:', error.message);
  } else if (error instanceof NetworkError) {
    console.error('Network error:', error.message);
  }
}

Development

git clone https://github.com/algoshred/workspaces-sdk-node.git
cd workspaces-sdk-node
bun install
bun run dev          # Watch mode
bun run build        # Production build
bun run test         # Run tests
bun run sanity       # All checks (format, lint, type-check, test, build)

Shell out to the CLI

For quick scripting, you can also shell out to the workspaces-cli CLI:

import {execFile} from "node:child_process";
import {promisify} from "node:util";
const exec = promisify(execFile);

const {stdout} = await exec("workspaces-cli", ["workspaces", "list", "--json"]);
const workspaces = JSON.parse(stdout);

Most CLI commands support --json for structured output.

Source

Repository: github.com/algoshred/workspaces-sdk-node
Package: @burdenoff/workspaces-sdk on npm

Install​

Environment selection​

Quick start​

Authentication​

Email / password​

OAuth2 device code flow​

OAuth2 authorization code + PKCE​

Client credentials (M2M / app auth)​

Workspace token​

Modules​

Configuration​

Error handling​

Development​

Shell out to the CLI​

Source​

Next steps​