PlatformClient (Node.js SDK)
The main entry point for the @mpratyush54/sdk-node package. Handles service registration, heartbeat, logging, metrics, config, storage, and optional database connections.
Installation
npm install @mpratyush54/sdk-node
Requires Node.js >= 18.
Import
import { PlatformClient } from '@mpratyush54/sdk-node';
// Or use the default singleton export
import platform from '@mpratyush54/sdk-node';
Constructor
const client = new PlatformClient();
The constructor takes no arguments. All configuration is passed to init().
init(options) — Initialise the client
await client.init(options: PlatformOptions): Promise<void>
PlatformOptions
| Property | Type | Default | Description |
|---|---|---|---|
projectName |
string |
— | Required. Your Cairn project name |
platformUrl |
string |
— | Required. Cairn API base URL (e.g. https://platform.example.com) |
sdkToken |
string? |
process.env.PLATFORM_SDK_TOKEN |
Bearer token for API authentication |
environmentName |
string |
'development' |
Deployment environment label |
version |
string |
'1.0.0' |
Application version |
branch |
string |
'main' |
Git branch name |
commitSha |
string? |
— | Git commit SHA |
namespace |
string? |
— | Ignored — server assigns {project}-{environment} |
hostname |
string |
os.hostname() |
Machine hostname |
databases |
string[] |
[] |
Database types to auto-connect: 'postgres', 'mongo', 'redis' |
repositoryUrl |
string? |
— | Must match project repositoryUrl for GitOps register |
gitPath |
string? |
— | Path to manifests in the repo |
gitRevision |
string? |
branch / main |
Git revision for ArgoCD |
domain |
string? |
— | Base domain for ingress hosts |
gitops |
boolean? |
— | Prefer GitOps path when repo is set |
serviceName |
string? |
projectName |
K8s Service name for ingress |
servicePort |
number? |
— | Service port for ingress |
What init() does
- Configures the internal HTTP client with the platform URL and auth header.
- Configures the logger, metrics tracker, config client, and storage client with project context.
- Registers the service with the Cairn API (
POST /api/sdk/register). - Loads remote config values and starts a background refresh (every 30 s).
- Starts a heartbeat (every 15 s) sending CPU %, memory, uptime, and DB health.
- Starts CPU sampling (every 10 s) for real-time CPU utilisation.
- Connects to each database type listed in
databasesusing credentials fetched via registration.
config(key, defaultValue?) — Read remote config
client.config(key: string, defaultValue?: any): any
Synchronously reads a config value from the in-memory cache (populated by init() and refreshed every 30 s). Returns the cached value, or defaultValue if the key is absent.
Config values of 'true' / 'false' are automatically coerced to booleans.
expressMiddleware() — HTTP metrics middleware
client.expressMiddleware(): (req, res, next) => void
Returns a middleware function compatible with Express, Fastify, and NestJS. Tracks per-route latency, response status code, and heap memory delta. Metrics are batched and flushed every 5 s to POST /api/sdk/api-metrics.
See expressMiddleware.
captureConsole() — Capture console.* calls
client.captureConsole(): this
Patches console.log, console.warn, console.error, and console.debug to forward all output to the Cairn logger. Returns this for chaining.
See captureConsole.
winstonTransport() — Winston-compatible transport
client.winstonTransport(): object
Returns an object with a log() method that satisfies the Winston transport interface. Every log entry is forwarded to the Cairn logger.
pinoTransport() — Pino-compatible transport
client.pinoTransport(): { write: (chunk: string) => void }
Returns a stream-like object with a write() method that accepts newline-delimited JSON Pino output and forwards it to the Cairn logger.
shutdown() — Graceful shutdown
await client.shutdown(): Promise<void>
- Stops heartbeat, CPU sampling, metrics flush, config refresh, and logger flush.
- Disconnects all database managers (PostgreSQL, MongoDB, Redis).
- Deregisters the service from the Cairn API (
POST /api/sdk/deregister).
Instance Properties
| Property | Type | Description |
|---|---|---|
client.registration |
RegistrationClient |
Low-level registration client |
client.logger |
LoggerClient |
Logger instance with info, warn, error, debug |
client.metrics |
MetricsClient |
Metrics buffer and flush engine |
client.configClient |
ConfigClient |
Remote config cache client |
client.storage |
StorageClient |
File upload / signed URL / delete client |
client.db.postgres |
PostgresManager? |
PostgreSQL pool manager (if enabled) |
client.db.mongo |
MongoManager? |
MongoDB connection manager (if enabled) |
client.db.redis |
RedisManager? |
Redis connection manager (if enabled) |
Full Example — Express App
import express from 'express';
import { PlatformClient } from '@mpratyush54/sdk-node';
const app = express();
const client = new PlatformClient();
async function main() {
await client.init({
projectName: 'my-api-service',
platformUrl: 'https://platform.example.com',
sdkToken: process.env.PLATFORM_SDK_TOKEN,
environmentName: process.env.NODE_ENV || 'development',
version: '2.1.0',
branch: 'main',
databases: ['postgres', 'redis'],
});
// Middleware — tracks every request
app.use(client.expressMiddleware());
// Capture console.log/warn/error
client.captureConsole();
// Routes
app.get('/api/health', (req, res) => {
const pgHealthy = client.db.postgres?.isConnected;
const redisHealthy = client.db.redis?.isConnected;
res.json({ status: 'ok', postgres: pgHealthy, redis: redisHealthy });
});
app.get('/api/items', async (req, res) => {
const result = await client.db.postgres!.query('SELECT * FROM items');
res.json(result.rows);
});
app.listen(3000, () => {
client.logger.info('Server started', { port: 3000 });
});
}
main().catch(console.error);
// Graceful shutdown
process.on('SIGTERM', async () => {
await client.shutdown();
process.exit(0);
});
Error Handling
- Registration failure: Non-blocking; logs a warning and continues.
- Config fetch failure: Non-blocking; uses cached values or defaults.
- Database connection failure: Non-blocking; the manager is still created but
isConnectedwill befalse. Automatic reconnection is attempted with exponential backoff (up to 5 retries, max 30 s delay). - Metrics / Log flush failure: Entries are re-queued (up to 500) to avoid data loss.
shutdown()usesPromise.allSettledso a single disconnect failure never prevents other resources from being released.