Node.js SDK

Use @squasher-ai/node for Express, Fastify, Hono, Bun, workers, and plain scripts.

Install

bun add @squasher-ai/node

Initialize early

Call init() before you import code that might throw.

src/index.ts

import { init } from "@squasher-ai/node";

init({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
  environment: process.env.NODE_ENV,
  sampling: {
    successRate: 0.1,
    errorRate: 1,
    slowRate: 1,
    slowThresholdMs: 1000,
  },
});

For long-running services, install process-level handlers and close the client during shutdown:

import { close, installGlobalHandlers } from "@squasher-ai/node";

installGlobalHandlers();

process.on("SIGTERM", () => {
  void close().finally(() => process.exit(0));
});

The SDK batches buffered events and automatically splits multi-event request bodies at 1 MB. The configured event-count and flush-interval thresholds still determine when a flush starts; the byte limit only keeps a single outbound request bounded.

Use a standalone client

init() sets the optional process-wide client used by the package-level helpers. Use SquasherClient directly when you need explicit ownership, isolated tests, or more than one client in the same process:

import { SquasherClient } from "@squasher-ai/node";

const client = new SquasherClient({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
  environment: process.env.NODE_ENV,
});

await client.captureMessage("Worker started", "info");

process.on("SIGTERM", () => {
  void client.close().finally(() => process.exit(0));
});

Methods on SquasherClient do not use the process-wide client. Package-level helpers such as captureError() and close() continue to use the client created by init(). flush() and close() wait for queued events and any active batch request that the batch-size threshold started.

Check local delivery health

Read getDeliveryStats() when a health endpoint, shutdown check, or local debug tool needs to know whether the SDK can deliver events:

const stats = client.getDeliveryStats();

console.log({
  queued: stats.queueDepth,
  queueHighWaterMark: stats.queueHighWaterMark,
  sent: stats.sentEvents,
  retried: stats.retriedEvents,
  dropped: stats.droppedEvents,
  lastOutcome: stats.lastOutcome,
  lastFlushDurationMs: stats.lastFlushDurationMs,
});

The immutable snapshot stays in the current process. Reading it does not send a diagnostic event, so delivery failures cannot create a recursive telemetry loop. Counters start at zero when the client starts and are not stored across process restarts. Attempted counts cover initial batches; retried counts cover later delivery attempts for those batches.

Wrap request handlers

Use withHttpRequest to emit one correlated completion event for successful and failed requests:

import { getClient, withHttpRequest } from "@squasher-ai/node";

app.get("/checkout", async (req, res) => {
  const result = await withHttpRequest(
    getClient(),
    { request: req, response: res, attributes: { "http.route": "/checkout" } },
    async () => runCheckout(req),
  );

  res.json(result);
});

Wrap AWS Lambda handlers

Use withAwsLambda to capture handler failures and flush queued events before the invocation ends:

src/handler.ts

import { SquasherClient, withAwsLambda } from "@squasher-ai/node";

const client = new SquasherClient({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
});

export const handler = withAwsLambda(client, async (event: { orderId: string }) => {
  await processOrder(event.orderId);
  return { statusCode: 200 };
});

The wrapper uses the Lambda context to limit its flush time. By default, it waits for at most one second and keeps 100 ms for the Lambda runtime. It has no AWS SDK, Lambda layer, extension, or collector dependency. It uses the normal Squasher ingestion request and does not provision a separate service. The flush runs inside the invocation and can add up to the configured wait time. Use shorter limits when the function has a strict response budget:

export const handler = withAwsLambda(client, runJob, {
  flushTimeoutMs: 500,
  remainingTimeReserveMs: 150,
});

Capture framework errors

Express
Fastify
Hono

import express from "express";
import { captureError } from "@squasher-ai/node";

const app = express();

app.use(async (error: unknown, req, res, _next) => {
  if (error instanceof Error) {
    await captureError(error, { url: req.originalUrl, method: req.method });
  }
  res.status(500).json({ error: "Internal server error" });
});

import Fastify from "fastify";
import { captureError } from "@squasher-ai/node";

const app = Fastify();

app.setErrorHandler(async (error, request, reply) => {
  await captureError(error, { url: request.url, method: request.method });
  reply.status(500).send({ error: "Internal server error" });
});

import { Hono } from "hono";
import { captureError } from "@squasher-ai/node";

const app = new Hono();

app.onError(async (error, c) => {
  await captureError(error, { url: c.req.url, method: c.req.method });
  return c.json({ error: "Internal server error" }, 500);
});

Manual capture

import {
  captureError,
  captureGeneration,
  captureMessage,
  captureTelemetry,
} from "@squasher-ai/node";

await captureMessage("Worker started", "info");
await captureError(new Error("Verification error"));
await captureGeneration("Support reply drafted", {
  llm: {
    provider: "openai",
    model: "gpt-4o-mini",
    prompt_tokens: 820,
    completion_tokens: 140,
    total_tokens: 960,
    cached_input_tokens: 320,
    cost_usd: 0.0021,
  },
});

await captureTelemetry({
  message: "Payment authorization failed",
  level: "error",
  kind: "error",
  attributes: {
    "error.why": "The payment provider declined the authorization.",
    "error.fix": "Ask the customer to use another payment method.",
    "error.link": "https://docs.example.com/payments/declines",
    "error.status": "actionable",
  },
});

Actionable error context

Squasher AI triage works best when errors include a short explanation and a next step. For Node services, send that context as structured attributes on telemetry events:

Attribute	Use for
`error.why`	What likely happened, in one sentence
`error.fix`	The safest next action for an engineer or agent
`error.link`	A public runbook or product doc URL
`error.status`	Current state or status code, for example `actionable`, `investigate`, or `429`

Keep these values safe to store with remote project telemetry. Put private implementation notes in your own development workflow rather than public-facing docs or customer-visible messages. Supported release line: @squasher-ai/node 0.4.x and the companion JavaScript SDKs at 0.3.x. Do not install earlier 0.x artifacts. For reusable application errors, create the context once and let captureError merge it into the event:

import { captureError, createActionableError } from "@squasher-ai/node";

await captureError(
  createActionableError("Payment authorization failed", {
    why: "The payment provider declined the authorization.",
    fix: "Ask the customer to use another payment method.",
    link: "https://docs.example.com/payments/declines",
    status: "actionable",
    internal: { provider_status: "card_declined" },
  }),
);

internal is hidden from the error’s normal JSON representation, but it is still sent to Squasher as event extra. Only include values that are safe for retained project telemetry.

Local debug artifacts

Enable localEventSink when you want a coding agent or local debug script to inspect the exact events the SDK prepared after beforeSend.

import { init } from "@squasher-ai/node";

init({
  apiKey: process.env.SQUASHER_API_KEY!,
  projectId: process.env.SQUASHER_PROJECT_ID!,
  localEventSink: {
    enabled: process.env.NODE_ENV === "development",
    directory: ".squasher/events",
    redactKeys: ["x-internal-admin-token"],
  },
});

The sink writes redacted NDJSON files named YYYY-MM-DD.jsonl. Treat them as temporary debugging output for agents and humans. They complement Squasher’s remote observability, but they are not the production source of truth and should not be used for alerting, retention, or incident history.

Agent handoff

Install @squasher-ai/node. Initialize it before application code runs, use withHttpRequest around HTTP handlers where possible, install global handlers for long-running services, add safe actionable attributes for known failure modes, and call close() during shutdown.

Use Pino transport or Winston transport for structured logs.
Use source maps to improve stack trace quality.
Use AI triage to turn rich error context into root-cause summaries.
Use Design Queryable Logs for operation event fields and sampling.

Get Started

SDKs

Integrations

Migrations

Cloud Log Drains

Features

API Reference

Install

Initialize early

Use a standalone client

Check local delivery health

Wrap request handlers

Wrap AWS Lambda handlers

Capture framework errors

Manual capture

Actionable error context

Local debug artifacts

Agent handoff

​Install

​Initialize early

​Use a standalone client

​Check local delivery health

​Wrap request handlers

​Wrap AWS Lambda handlers

​Capture framework errors

​Manual capture

​Actionable error context

​Local debug artifacts

​Agent handoff

​Related guides

Install

Initialize early

Use a standalone client

Check local delivery health

Wrap request handlers

Wrap AWS Lambda handlers

Capture framework errors

Manual capture

Actionable error context

Local debug artifacts

Agent handoff

Related guides