SDKs
Node.js SDK Guide
Complete guide for @lazers/agent-sdk covering Express, NestJS, background queues, and webhook monitoring.
The official Node.js SDK (`@lazers/agent-sdk`) is built for Node.js 18+ and TypeScript. It includes non-blocking queueing, exponential retry backoff, and automatic credential scrubbing.
Installation ```bash npm install @lazers/agent-sdk # or pnpm add @lazers/agent-sdk ```
Configuration Options - `apiKey` (string, required): Server key beginning with `laz_live_`. - `endpoint` (string, required): Lazers API base URL (`https://api.lazers.app`). - `projectId` (string, required): Target project identifier. - `environment` (string, required): e.g. `production`, `staging`. - `serviceName` (string, required): Logical microservice name. - `release` (string, optional): Git commit SHA, semver, or build ID. - `maxQueueSize` (number, optional, default: 100): In-memory buffer size. - `maxRetries` (number, optional, default: 5): Delivery attempts before dropping.
Express Integration Attach error-handling middleware at the bottom of your Express route definitions:
Integration Code Examples
Express Middleware
import express from "express";
import { createLazersAgent } from "@lazers/agent-sdk";
const lazers = createLazersAgent({
apiKey: process.env.LAZERS_API_KEY!,
endpoint: process.env.LAZERS_ENDPOINT || "https://api.lazers.app",
projectId: process.env.LAZERS_PROJECT_ID!,
environment: process.env.LAZERS_ENVIRONMENT || "production",
serviceName: "checkout-api",
});
const app = express();
// Your business routes
app.post("/checkout", (req, res) => {
throw new Error("Stripe card verification failed");
});
// Global Lazers error handler (must have 4 arguments)
app.use((error: Error, req: express.Request, res: express.Response, next: express.NextFunction) => {
void lazers.captureError(error, {
correlationId: (req.headers["x-request-id"] as string) || undefined,
metadata: { path: req.path, method: req.method },
actor: (req as any).user ? { type: "customer", id: (req as any).user.id } : undefined,
});
next(error);
});
// Clean shutdown
process.on("SIGTERM", async () => {
await lazers.flush();
process.exit(0);
});NestJS Service
import { Injectable, OnApplicationShutdown } from "@nestjs/common";
import { createLazersAgent, LazersAgent } from "@lazers/agent-sdk";
@Injectable()
export class LazersService implements OnApplicationShutdown {
readonly agent: LazersAgent;
constructor() {
this.agent = createLazersAgent({
apiKey: process.env.LAZERS_API_KEY!,
endpoint: process.env.LAZERS_ENDPOINT || "https://api.lazers.app",
projectId: process.env.LAZERS_PROJECT_ID!,
environment: process.env.LAZERS_ENVIRONMENT || "production",
serviceName: "core-api",
release: process.env.GIT_COMMIT_SHA,
});
}
captureError(error: unknown, correlationId?: string) {
return this.agent.captureError(error, { correlationId });
}
async onApplicationShutdown() {
await this.agent.flush();
}
}Background Jobs & Webhooks
// BullMQ / Worker Job Failure
worker.on("failed", (job, error) => {
void lazers.captureJobFailure(job.name, error, {
correlationId: job.id,
metadata: { attempts: job.attemptsMade, queue: "email-queue" },
});
});
// Webhook Catch Handler
app.post("/webhooks/paystack", (req, res) => {
try {
verifyPaystackSignature(req);
} catch (error) {
void lazers.captureWebhookFailure("paystack", error, {
correlationId: req.headers["x-paystack-signature"] as string,
});
return res.status(400).send("Invalid signature");
}
});