Copy page

SDK Library

Overview

@primebrick/sdk is the shared infrastructure SDK for Primebrick v3. It provides the building blocks that every backend service and microservice needs: config loading, service registration, NATS™ messaging, auth, JSON serialization, health checks, graceful shutdown, env validation, and database migrations.

Design principles

• DB-agnostic — the SDK depends on port interfaces, not on any specific DAL. Consumers provide adapters using their DAL of choice.
• Framework-agnostic — auth works with raw Node.js® HTTP, Express, and NATS™ through a single HeaderProvider abstraction.
• NATS™-first — microservices register and heartbeat via NATS™, not via direct DB access. The BE subscribes to lifecycle events and persists them.
• BigInt-safe — all JSON serialization uses ext-json so bigint values survive the wire format without number | bigint ambiguity.
• Optional Redis cache — best-effort cache for hot single-row reads. The system is fully valid without it; if Redis is unavailable, reads fall through to the database with warn logs. See Cache layer for usage.

Modules

Module	What it does
auth	JWT/OIDC verification, API keys, RBAC, session context (AsyncLocalStorage)
nats	Singleton NATS™ client with Ext-JSON publish/subscribe/request-reply
service	NATS™-based service registration, heartbeats, and lifecycle events
json	BigInt-safe JSON stringify/parse + Express middleware
cache	Optional Redis cache layer (@Cached, @CacheKey, withCache, RedisCachePort)
http	Minimal HTTP server with unified /health endpoint and RFC 7807 error responses
config	Dictionary-style config loader with in-memory cache + NATS™ config.get sharing
lifecycle	Graceful shutdown coordinator + consistent [startup] logging banner
migrations	SHA-256-enforced database patch runner
env	Environment variable validation
sse	Server-Sent Events writer, event bus, and NATS™→SSE bridge (BE only)
presence	Real-time collaboration awareness — who is viewing/editing an entity (BE only)

Architecture

The BE validates JWTs against the IDP (STANDALONE mode), resolves users to internal UUIDs, expands roles to permissions, then serializes the full AuthUser into headers when proxying to microservices. Microservices (GATEWAY-RESOLVED mode) verify the gateway secret and deserialize the pre-resolved user — no DB access, no ports needed.

The BE also publishes presence deltas and entity-changed markers to NATS™ (presence.{entityType}.{entityUuid} and entity.{entityType}.{entityUuid}.changed), bridges them to per-entity SSE event buses, and forwards them to connected FE clients. See Presence for the collaboration awareness contract.

Quick start

The fastest way to verify a service built on the SDK is up is the /health endpoint. Every service that uses createHttpServer() exposes it, and the BE exposes it at /api/v1/health.

Code
# Microservice (US) — uses createHttpServer() from the SDK
curl http://localhost:3002/health

Code
{
  "ok": true,
  "service": "emailsender",
  "version": "1.4.0",
  "url": "http://localhost:3002",
  "checks": {
    "db":   { "ok": true, "version": "18.0" },
    "nats": { "ok": true, "version": "2.14.3" },
    "redis":{ "ok": true, "version": "8.8.0" }
  }
}

If any check fails, ok is false and the HTTP status is 503. The FE's 503 interceptor probes /health and shows the right health chip. See HTTP Server for the full HealthResponse shape and Getting Started for the complete service bootstrap.

Next steps

• Getting Started — install and wire up the SDK
• Authentication — auth modes, RBAC, session context
• NATS Client — publish/subscribe with Ext-JSON
• Service Registration — NATS™-based lifecycle
• Ext-JSON — BigInt-safe serialization
• Cache layer — optional Redis cache for hot single-row reads
• HTTP Server — unified health checks and RFC 7807 errors
• SSE standard — Server-Sent Events writer, event bus, NATS™ bridge
• Presence — real-time collaboration awareness
• API Reference — every exported symbol