# Getting Started


## Installation

```bash
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](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](presence)
for the contract.

## Minimal microservice setup

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

```ts
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:

```bash
curl http://localhost:3002/health
```

```json
{
  "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](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:

```ts
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):

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

## Next steps

- [Authentication](authentication) — configure auth for STANDALONE or GATEWAY-RESOLVED mode
- [NATS Client](nats-client) — publish/subscribe patterns
- [Service Registration](service-registration) — lifecycle events
- [HTTP Server](http-server) — the unified `/health` response shape and custom checks
- [Cache layer](cache-layer) — optional Redis cache for hot single-row reads
- [Presence](presence) — optional real-time collaboration awareness
- [API Reference](api-reference) — full API listing