@burdenoff/be-sdk

Backend SDK for Burdenoff products providing unified access to notifications, RBAC, activity tracking, usage monitoring, and more.

Published automatically using npm trusted publishers (OIDC) - no long-lived tokens needed!

Installation

npm install @burdenoff/be-sdk

Quick Start

import { BurdenoffSDK } from '@burdenoff/be-sdk';

// Initialize SDK
const sdk = new BurdenoffSDK({
  workspacesApiUrl: 'https://api.burdenoff.com/graphql',
  tenantApiUrl: 'https://tenant.burdenoff.com/graphql',
  context: {
    userId: 'user-123',
    workspaceId: 'workspace-456',
    token: 'your-jwt-token',
  },
});

// Send notification
await sdk.notifications.send({
  title: 'Welcome',
  message: 'Hello from Burdenoff!',
  userIds: ['user-123'],
  type: 'info',
});

// Track operation with RBAC + Activity + Usage
await sdk.tracker.trackOperation({
  operationName: 'createProject',
  userId: 'user-123',
  rbacCheck: { workspaceId: 'workspace-456' },
  activityOptions: {
    description: 'Created new project',
    metadata: { projectName: 'My Project' },
  },
  usageOptions: {
    billingAccountId: 'billing-123',
  },
});

// Check permissions
await sdk.rbac.requirePermission({
  userId: 'user-123',
  action: 'create:project',
  resourceType: 'project',
  workspaceId: 'workspace-456',
});

// Record activity
await sdk.activity.record({
  userId: 'user-123',
  action: 'PROJECT_CREATED',
  description: 'Created new project',
  productId: 'WORKSPACE',
  workspaceId: 'workspace-456',
});

// Add usage
await sdk.usage.add({
  billingAccountId: 'billing-123',
  quotaName: 'api_calls',
  value: 1,
  description: 'API call for project creation',
});

// Export product translations from i18n service
const hiDictionary = await sdk.translation.exportProductTranslations({
  productName: 'vibecontrols',
  languageCode: 'hi',
  format: 'JSON',
  decodeJson: true,
});

// Upsert product translations (creates missing keys/translations, publishes)
await sdk.translation.upsertProductTranslations({
  productName: 'vibecontrols',
  languageCode: 'ta',
  translations: {
    'overviewPage.title': 'VibeControls மேலோட்டம்',
  },
});

Features

• Unified Tracking: Single function for RBAC + Activity + Usage + Quota checking
• Notifications: Send in-app, email, SMS, and push notifications
• RBAC: Role-based access control and permission management
• Activity Logging: Comprehensive audit trail for all operations
• Usage Tracking: Track resource consumption for billing
• Graph Integration: Global search across all products
• Context Management: Automatic context propagation
• Event Queue: NATS integration for event-driven architecture
• Database Helpers: Prisma utilities and transaction management
• Authentication: JWT verification and token management
• Payments: Payment processing and webhook handling
• Translation: Backend i18n support
• Search: Advanced search utilities
• Logger: Structured logging compatible with console

Modules

Core Modules

• tracker: Unified operation tracking (RBAC + Activity + Usage + Notifications)
• logger: Structured logging system
• context: Request context management
• client: GraphQL client with retry logic

Integration Modules

• notifications: Notification management
• rbac: Permission and access control
• activity: Activity logging
• usage: Usage and quota tracking
• graph: Knowledge graph integration
• events: Event queue (NATS) integration
• auth: Authentication and JWT handling

Utility Modules

• database: Prisma helpers
• search: Search utilities
• translation: i18n support
• payments: Payment processing
• bootstrap: Server initialization
• platform: Scale primitives (see below)

Platform Primitives (@burdenoff/be-sdk/platform)

Reusable building blocks consumed fleet-wide as part of the scale refactor:

| Primitive | Purpose | |-----------|---------| | httpClient / createHttpClient | Hardened fetch wrapper: per-request AbortSignal.timeout (default 5s), retries with jitter, per-host circuit breaker (opens at 5 consecutive 5xx, half-open after 30s). | | withLeaderLock(redis, name, fn, { ttlMs, renewMs }) | Redis-based leader election via SET NX EX; auto-renews while fn() runs; releases via token-checked LUA DEL. | | rateLimitIncr(redis, { key, limit, windowMs }) | Atomic INCR + EXPIRE NX rate limiter. Returns { allowed, remaining, resetAt }. | | buildLoaders + resolveReferenceLoader | Per-request DataLoader factory + Apollo Federation __resolveReference helper. | | clampLimit + paginate | Cursor pagination (take = limit + 1 to compute hasMore and nextCursor). | | LLMRouter | Multi-provider LLM wrapper (Anthropic / OpenAI / OpenRouter) with timeout, retries with jitter, provider fallback chain (env LLM_PROVIDER_CHAIN), and token cap. | | ensureMonthlyPartitions / dropOldPartitions | PostgreSQL monthly RANGE partition creation + retention drop. | | buildCacheKey / invalidateNamespace | Versioned-key cache invalidation (INCR v:{namespace} — no KEYS/SCAN). |

import { Platform } from '@burdenoff/be-sdk';
// or: import { httpClient, withLeaderLock, ... } from '@burdenoff/be-sdk/platform';

const response = await Platform.httpClient('https://api.example.com/v1/users');

await Platform.withLeaderLock(redis, 'nightly-cleanup', async () => {
  // only one replica runs this
}, { ttlMs: 60_000 });

const { allowed } = await Platform.rateLimitIncr(redis, {
  key: `signup:${ip}`,
  limit: 5,
  windowMs: 60_000,
});

Documentation

For detailed documentation, see:

• API Reference
• Integration Guide
• Examples
• Migration Guide
• Internal Client Architecture - Service-to-service communication and header transformation

Development

# Install dependencies
npm install

# Run tests
npm test

# Build
npm run build

# Lint
npm run lint

# Format
npm run format

License

PROPRIETARY - Copyright Burdenoff Consultancy Services Pvt. Ltd.

Support

For support, email [email protected] or visit https://burdenoff.com/support.