Node SDK

Official TypeScript SDK for SemanticFed — programmatic access to the federated semantic layer.

• Package: @semanticfed/sdk
• Repository: github.com/algoshred/semanticfed-sdk-node

Install

bun add @semanticfed/sdk
# or
npm install @semanticfed/sdk

Quick start

import { SemanticFedSDK } from '@semanticfed/sdk';

// Production is the default
const sdk = new SemanticFedSDK({
  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 connectors = await sdk.semanticfed.connectors.list();
const metrics = await sdk.semanticfed.metrics.list();

Environment selection

The SDK defaults to production. For local or alpha, pass the appropriate endpoints:

// Local
const sdk = new SemanticFedSDK({
  workspaceEndpoint: 'http://127.0.0.1:4003/workspaces/graphql',
  globalEndpoint: 'http://127.0.0.1:4000/global/graphql',
});

// Alpha
const sdk = new SemanticFedSDK({
  workspaceEndpoint: 'https://alphagraphqlworkspaces.burdenoff.com/workspaces/graphql',
  globalEndpoint: 'https://alphagraphql.burdenoff.com/global/graphql',
});

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:
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);

Namespaces

Namespace	Description
sdk.auth	Sign in/up, OAuth flows, token management
sdk.semanticfed	SemanticFed domain — connectors, dataSources, models, entities, dimensions, metrics, relationships, queries, queryRuns, accessPolicies, health
sdk.sandbox	Ephemeral sandbox environments
sdk.billing	Subscriptions, invoices, plans
sdk.workspaces	Workspace CRUD + members + projects
sdk.rbac	Permissions, role assignment
sdk.tags	Tag CRUD + tagging
sdk.files	Browse, upload, share files
sdk.notifications	Notification center + preferences
sdk.organizations	Organizations + invites
sdk.health	Gateway/service health probes

Configuration

interface SemanticFedSDKConfig {
  workspaceEndpoint: string;
  globalEndpoint: string;
  oidcIssuer?: string;
  clientId?: string;
  clientSecret?: string;
  redirectUri?: string;
  apiKey?: string;
  accessToken?: string;
  refreshToken?: string;
  workspaceToken?: string;
  timeout?: number;          // default: 30000
  autoRefresh?: boolean;     // default: true
}

Error handling

import { SemanticFedError, AuthenticationError, NetworkError } from '@semanticfed/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/semanticfed-sdk-node.git
cd semanticfed-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)

License

Proprietary — Copyright Burdenoff Consultancy Services Pvt. Ltd.