Skip to main content

Workspaces SDK Overview

The Burdenoff Workspaces SDK is a comprehensive TypeScript/JavaScript library that provides a simple and intuitive interface for interacting with the Workspaces API. It handles authentication, GraphQL operations, and provides type-safe access to all workspace management functionality.

Features​

  • TypeScript Support: Full type safety with auto-generated types from the GraphQL schema
  • Modular Architecture: Organized into logical modules for different API areas
  • Authentication Management: Built-in token handling and workspace switching
  • Comprehensive Coverage: Supports all major API operations including:
    • User authentication and management
    • Workspace creation and management
    • Role-based access control (RBAC)
    • Team management
    • Project management
    • Resource management
  • Error Handling: Consistent error handling across all operations
  • Testing: Comprehensive unit test coverage
  • Developer Experience: IntelliSense support and clear documentation

Installation​

npm install @burdenoff/workspaces-sdk

Quick Start​

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

// Initialize the SDK
const sdk = new WorkspacesSDK({
  endpoint: 'https://api.yourworkspace.com/graphql',
  apiKey: 'your-api-key', // Optional
});

// Register a new user
const user = await sdk.auth.register({
  email: '[email protected]',
  name: 'John Doe',
  password: 'securepassword',
});

// Verify user with token
const authResult = await sdk.auth.verifyUser('verification-token');

// Get workspaces
const workspaces = await sdk.workspaces.getWorkspaces();

// Create a new workspace
const newWorkspace = await sdk.workspaces.createWorkspace({
  name: 'My New Workspace',
  tenantID: 'tenant-123',
});

Architecture​

The SDK is organized into the following modules:

Core Modules​

  • Auth Module (sdk.auth): User authentication, registration, and session management
  • User Module (sdk.users): User profile management and invitations
  • Workspace Module (sdk.workspaces): Workspace CRUD operations and member management
  • RBAC Module (sdk.rbac): Role-based access control, permissions, and role management
  • Team Module (sdk.teams): Team creation, management, and member operations
  • Project Module (sdk.projects): Project management and member roles
  • Resource Module (sdk.resources): Resource management and resource types

Configuration​

The SDK accepts the following configuration options:

interface WorkspacesSDKConfig {
  endpoint: string;          // GraphQL API endpoint
  apiKey?: string;          // Optional API key
  accessToken?: string;     // Optional access token
  refreshToken?: string;    // Optional refresh token
  timeout?: number;         // Request timeout (deprecated)
}

Authentication​

The SDK provides built-in token management:

// Set tokens after authentication
sdk.setTokens('access-token', 'refresh-token');

// Get current tokens
const tokens = sdk.getTokens();

// Clear tokens (logout)
sdk.clearTokens();

Error Handling​

All SDK methods return Promises and throw errors for failed operations. Errors include:

  • GraphQL validation errors
  • Network errors
  • Authentication errors
  • Permission errors
try {
  const user = await sdk.users.getUser({ id: 'user-123' });
} catch (error) {
  console.error('Failed to get user:', error.message);
}

Type Safety​

The SDK provides full TypeScript support with generated types from the GraphQL schema:

import type { User, Workspace, CreateWorkspaceInput } from '@burdenoff/workspaces-sdk';

const createWorkspace = async (input: CreateWorkspaceInput): Promise<Workspace> => {
  return await sdk.workspaces.createWorkspace(input);
};

Next Steps​