@aimondev/sdk

Error monitoring SDK for Node.js and Next.js. Captures exceptions and sends them to your Aimon project for AI-powered triage and routing.

Installation

npm install @aimondev/sdk
# or
yarn add @aimondev/sdk
# or
pnpm add @aimondev/sdk

Quick start — plain Node.js

import { initAimon, captureException } from '@aimondev/sdk';

initAimon({
  dsn: 'aimon://[email protected]/YOUR_PROJECT_ID',
  service: 'my-api',
  environment: 'production',
  release: '1.0.0',
});

// Manual capture
try {
  await processPayment(order);
} catch (err) {
  captureException(err, {
    transaction: 'POST /checkout',
    user: { id: user.id },
    tags: { plan: 'pro' },
  });
  throw err; // re-throw if you want the error to propagate
}

// Uncaught exceptions and unhandled promise rejections
// are captured automatically — no extra code needed.

Next.js (App Router)

1. Create instrumentation.ts at the project root

Next.js runs this file once on server startup. It's the right place to initialise the SDK.

// instrumentation.ts  (project root, next to package.json)
export async function register() {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { initAimon } = await import('@aimondev/sdk');

    initAimon({
      dsn: process.env.AIMON_DSN!,
      service: 'web',
      environment: process.env.NODE_ENV,
      release: process.env.NEXT_PUBLIC_APP_VERSION,
    });
  }
}

Enable the instrumentation hook in next.config.ts if you're on Next.js < 15:

// next.config.ts
const nextConfig = {
  experimental: {
    instrumentationHook: true,   // not needed in Next.js 15+
  },
};
export default nextConfig;

2. Add your DSN to .env.local

AIMON_DSN=aimon://[email protected]/YOUR_PROJECT_ID

3. Capture errors in Route Handlers

// app/api/orders/route.ts
import { captureException } from '@aimondev/sdk';
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  try {
    const body = await req.json();
    const order = await createOrder(body);
    return NextResponse.json(order);
  } catch (err) {
    captureException(err, {
      transaction: 'POST /api/orders',
      tags: { handler: 'orders' },
    });
    return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
  }
}

4. Capture errors in Server Actions

// app/actions/checkout.ts
'use server';
import { captureException } from '@aimondev/sdk';

export async function checkoutAction(formData: FormData) {
  try {
    await processPayment(formData);
  } catch (err) {
    captureException(err, {
      transaction: 'checkoutAction',
      user: { id: formData.get('userId') as string },
    });
    throw err;
  }
}

5. Capture errors in Server Components

// app/dashboard/page.tsx
import { captureException } from '@aimondev/sdk';

export default async function DashboardPage() {
  try {
    const data = await fetchDashboardData();
    return <Dashboard data={data} />;
  } catch (err) {
    captureException(err, { transaction: 'DashboardPage' });
    throw err; // triggers Next.js error.tsx boundary
  }
}

Express / Fastify

import express from 'express';
import { initAimon, captureException } from '@aimondev/sdk';

initAimon({
  dsn: process.env.AIMON_DSN!,
  service: 'api',
  environment: process.env.NODE_ENV,
});

const app = express();

// Add as the last middleware to catch all errors
app.use((err: Error, req: express.Request, res: express.Response, next: express.NextFunction) => {
  captureException(err, {
    transaction: `${req.method} ${req.path}`,
    request_id: req.headers['x-request-id'] as string,
    user: (req as any).user,
    tags: {
      method: req.method,
      path: req.path,
      status: res.statusCode.toString(),
    },
  });
  res.status(500).json({ error: 'Internal server error' });
});

Configuration options

initAimon({
  // Required
  dsn: 'aimon://KEY@host/project_id',

  // Optional
  service: 'my-service',          // shown in the dashboard, default: 'unknown'
  environment: 'production',      // default: process.env.NODE_ENV
  release: '1.2.3',               // git SHA or semver, shown in event list
  debug: false,                   // log SDK activity to console
  captureGlobalErrors: true,      // auto-capture uncaughtException + unhandledRejection

  // Filter or modify events before sending
  beforeSend(event) {
    // Drop events from health checks
    if (event.transaction?.includes('/health')) return null;
    // Scrub sensitive data
    if (event.extra?.password) delete event.extra.password;
    return event;
  },
});

captureException context

captureException(error, {
  transaction: 'POST /api/payments',  // route or function name
  request_id: 'req-abc-123',          // correlate with your request logs
  user: {
    id: 'usr-42',                     // hashed before storage — never stored raw
    role: 'admin',
  },
  tags: {
    plan: 'enterprise',               // searchable key-value pairs
    region: 'eu-west-1',
  },
  extra: {
    orderId: '123',                   // any extra debug data
    retryCount: 3,
  },
});

What happens when you call captureException

1. Stack trace is parsed into structured frames
2. Event is sent to your Aimon backend (POST /v1/events) with your DSN as auth
3. Backend computes a fingerprint → deduplicates against existing groups
4. If it's a new error (or a spike): AI triage runs in the background
5. AI assigns severity, writes root cause analysis and suggested fixes
6. Routing runs: creates Linear issue and/or launches Cursor agent based on your project settings
7. Error appears in your Aimon dashboard within seconds

Publishing to npm (for Aimon maintainers)

# 1. Create an account at npmjs.com then log in
npm login

# 2. Build
cd sdk-js
npm run build

# 3. Publish (first time — scoped packages need --access public)
npm publish --access public

# 4. For future releases, bump version first
npm version patch   # 0.1.0 → 0.1.1
npm run build
npm publish

After publishing, customers install with:

npm install @aimondev/sdk