Copy page

SDK Library

Getting Started

Installation

Code
pnpm add @primebrick/sdk

The SDK has runtime dependencies: jose (JWT/OIDC), json-bigint (BigInt-safe JSON), nats (NATS™ client), redis (optional cache), and reflect-metadata (cache metadata). These are installed automatically.

Redis (optional)

Redis is NOT required to run Primebrick. If you want to enable the optional cache layer for hot single-row reads, install Redis and set the redis_url key in the auth_configurations table. See Cache layer for details. Without redis_url, the system runs DB-only with no cache.

Redis is also used by the optional presence module (collaboration awareness — who is viewing/editing an entity). Like the cache, presence is best-effort: if Redis is unavailable, the BE wrapper turns presence calls into no-ops and the UI simply shows no other users. See Presence for the contract.

Minimal microservice setup

A typical Primebrick microservice wires up the SDK in this order at startup:

Code
import {
  NatsClient,
  ServiceRegistrar,
  createHttpServer,
  HealthCheck,
  GracefulShutdown,
  validateEnv,
  logModuleStartup,
  logServiceStartup,
} from "@primebrick/sdk";

// 1. Validate environment
const env = validateEnv({
  NATS_URL: { required: true },
  PORT: { required: true },
  SERVICE_CODE: { required: true },
  BASE_URL: { required: true },
});

// 2. Connect to NATS — getConnection() logs the [startup] banner automatically
await NatsClient.getConnection(env.NATS_URL);
logModuleStartup("NATS", NatsClient.getServerVersion(), env.NATS_URL);

// 3. Health checks — the HealthCheck class produces the unified HealthResponse
//    shape consumed by both BE and US /health endpoints.
const healthCheck = new HealthCheck();
healthCheck.add("nats", () => NatsClient.isConnected());

// 4. Register the service via NATS lifecycle events
const registrar = new ServiceRegistrar(NatsClient, {
  serviceCode: env.SERVICE_CODE,
  baseUrl: env.BASE_URL,
  endpoints: { "POST /send": {} },
}, async () => ({
  http_healthy: true,
  checks: { nats: { ok: NatsClient.isConnected() } },
}));
await registrar.register();
registrar.startHeartbeat();

// 5. HTTP server with health endpoint — serviceVersion + serviceUrl are
//    included in the /health response so the FE can display them.
const server = await createHttpServer({
  port: Number(env.PORT),
  serviceName: env.SERVICE_CODE,
  serviceVersion: "1.0.0",           // from package.json
  serviceUrl: env.BASE_URL,
  healthCheck,
  routeHandler: async (req, res, url) => {
    // your routes here
    return false;
  },
});
logServiceStartup(env.SERVICE_CODE, "1.0.0", env.BASE_URL);

// 6. Graceful shutdown
GracefulShutdown.register(async () => {
  await registrar.unregister();
  server.close();
  await NatsClient.close();
});

Verify the health endpoint

After running the service, verify it is up with a single curl:

Code
curl http://localhost:3002/health

Code
{
  "ok": true,
  "service": "emailsender",
  "version": "1.0.0",
  "url": "http://localhost:3002",
  "checks": { "nats": { "ok": true } }
}

If any check fails, the HTTP status is 503 and ok is false — the FE's 503 interceptor probes /health and shows the right health chip. See HTTP Server for the full HealthResponse shape and how to register custom checks (db, redis, idp).

Importing sub-modules

The SDK exports everything from the package root:

Code
import { NatsClient, verifyAuth, extJsonStringify, Permission } from "@primebrick/sdk";

The Ext-JSON module is also available as a sub-path import (useful when you need only JSON serialization without pulling in the NATS™/auth code paths):

Code
import { extJsonStringify, extJsonParse } from "@primebrick/sdk/json";

Next steps

• Authentication — configure auth for STANDALONE or GATEWAY-RESOLVED mode
• NATS Client — publish/subscribe patterns
• Service Registration — lifecycle events
• HTTP Server — the unified /health response shape and custom checks
• Cache layer — optional Redis cache for hot single-row reads
• Presence — optional real-time collaboration awareness
• API Reference — full API listing