Server SDK Integration Guide

This guide explains how to integrate the Pulse Server SDK and its Express and NestJS wrappers into your backend applications. It covers installation, configuration, and usage for each supported framework.

Overview

The Pulse Server SDK enables backend services to access Pulse settings, tracking, and context propagation. It is framework-agnostic and can be used directly or via wrappers for Express and NestJS.

• @pulse/server: Core SDK for Node.js backends.
• @pulse/express: Express.js middleware for request context.
• @pulse/nest: NestJS module and middleware for seamless integration.

---

Installation

Install the required packages from your registry:

npm install @pulse/server @pulse/express @pulse/nest

---

Configuration

All integrations use a common configuration object. The most important option is app, which identifies your application. You can also specify settings for the tracker, settings, and other features.

Example configuration:

const config = {
  app: "your-app-name",
  settings: {
    defaults: {
      /* key-value pairs */
    },
    remoteSettingEnabled: true,
  },
  tracker: {
    version: "your app version",
  },
};

---

Usage

1. Direct Server SDK Usage

Use this approach for custom Node.js servers, request handlers outside Express/NestJS, or any code that owns its own request lifecycle.

import { createClient } from "@pulse/server";
import { pulse } from "@pulse/core";

const client = createClient(config);

// Wrap the per-request work in an async context — `pulse` from `@pulse/core`
// resolves to this request's context inside the callback (and any async branch
// from inside it).
await client.createAsyncContext(
  { user_id: "user-123" /* ...other context fields */ },
  async () => {
    const value = await pulse.get("setting_name", "tag_name");
    // ... handle the request, use settings / fire events ...
  },
);

For long-running Node processes (CLIs, daemons, batch scripts) where there's no per-request boundary, see the dedicated CLI / Standalone Node Tracker guide. It documents the tracker surface (event, events, attribute, etc.), device-id persistence, and the wire format CLI events use.

---

2. Express Integration

Use the Express middleware to automatically inject Pulse context into each request.

import { pulse } from "@pulse/core";
import { usePulse } from "@pulse/express";
import express from "express";

const host = process.env["HOST"] ?? "localhost";
const port = process.env["PORT"] ? Number(process.env["PORT"]) : 9000;

const app = express();

// Initialize Pulse middleware with configuration
app.use(
  usePulse({
    app: "your-app-name",
  })
);

app.get("/", async (_req, res) => {
  let settingValue = null;

  try {
    settingValue = await pulse.get("setting_name", "tag_name");
  } catch (error) {
    settingValue = { error: "Failed to fetch setting" };
  }

  res.send({
    message: "Hello API!",
    setting: settingValue,
  });
});

Key Points:

• The middleware is initialized with your app name.
• In route handlers, you can access the Pulse context and fetch settings asynchronously.
• Error handling is included for robustness.

---

3. NestJS Integration

Use the NestJS module and middleware for seamless integration.

import { Module } from "@nestjs/common";
import { PulseModule } from "@pulse/nest";

@Module({
  imports: [PulseModule.forRoot(config)],
})
export class AppModule {}

• The PulseMiddleware is automatically applied to all routes.
• Inject the Pulse client or access context in your services/controllers as needed.

---

API Reference

createClient(config)

Creates a Pulse client instance with the given configuration.

Express: usePulse(config)

Returns Express middleware that injects Pulse context into each request.

NestJS: PulseModule.forRoot(config)

Registers the Pulse module and middleware for your NestJS app.

---

Notes

• Always initialize the SDK with your application name and relevant configuration.
• For advanced scenarios, refer to the SDK source or contact the Pulse team.