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,
});

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.

Wrap request handlers

Use withHttpRequest when you want request metadata attached automatically if the handler throws:

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);
});

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. 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.

Get Started

SDKs

Integrations

Migrations

Cloud Log Drains

Features

API Reference

Install

Initialize early

Wrap request handlers

Capture framework errors

Manual capture

Actionable error context

Local debug artifacts

Agent handoff

​Install

​Initialize early

​Wrap request handlers

​Capture framework errors

​Manual capture

​Actionable error context

​Local debug artifacts

​Agent handoff

​Related guides

Install

Initialize early

Wrap request handlers

Capture framework errors

Manual capture

Actionable error context

Local debug artifacts

Agent handoff

Related guides