@autotix/sdk

Ship JS errors from any browser, Node, or edge runtime to Autotix. Autotix turns the errors into Jira/GitHub tickets and (when enabled) opens auto-fix PRs.

• Universal — browsers, Node 18+, Lambdas, Vercel/Cloudflare/Deno workers
• Tiny — < 4 KB gzipped browser bundle, zero dependencies
• Drop-in auto-capture in browsers (window.onerror, unhandledrejection)
• Manual API for Node scripts, server components, CLI tools, etc.
• TypeScript-first with full type definitions

Install

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

Quick start

Browsers (with auto-capture)

import { init } from "@autotix/sdk/browser";

init({
  token: "iat_xxxxxxxxxxxxxxxxxxxx",
  environment: "production",
  release: "v1.4.2",
});
// Done. Uncaught errors and unhandled promise rejections now ship to Autotix.

Node, Lambdas, edge (no auto-capture)

import { init, capture } from "@autotix/sdk";

init({
  token: process.env.AUTOTIX_INGEST_TOKEN!,
  environment: process.env.NODE_ENV,
});

try {
  await doRiskyThing();
} catch (err) {
  capture(err, { tags: { module: "billing" } });
  throw err;
}

Manual capture (works in both)

import { capture, captureMessage, setUser, setContext } from "@autotix/sdk";

setUser({ id: user.id, email: user.email });
setContext("page", { path: location.pathname });

try {
  await checkout();
} catch (err) {
  capture(err);
}

// Non-error messages too:
captureMessage("user requested account deletion", { level: "warning" });

Where do I get a token?

In your Autotix dashboard, go to Settings → JS Errors and click Create Token. You'll get a string like iat_2a1b…. Treat it like a public-write API key — anyone with it can submit events to your org. Revoke compromised tokens with one click; existing client deployments using the old token stop working immediately.

Configuration

init({
  token: "iat_…",                    // required
  endpoint: "https://app.autotix.io/api/client-errors", // override for self-hosted
  environment: "production",          // tag every event
  release: "v1.2.3",                  // tag every event
  sampleRate: 1.0,                    // 0..1 — fraction of events to ship

  // Browser-only auto-capture (ignored in Node/edge):
  captureUnhandledErrors: true,       // window.addEventListener("error")
  captureUnhandledRejections: true,   // unhandledrejection
  captureConsoleError: false,         // wrap console.error (noisy — opt-in)

  // Hooks:
  beforeSend: (event) => {
    if (event.message.includes("ResizeObserver")) return null; // drop
    return event;
  },

  // Inject a custom fetch (testing, custom retry/timeout, etc.):
  fetch: customFetch,
});

API

| Function | What it does | | ----------------------------- | --------------------------------------------------------------------- | | init(options) | Initialize the SDK. Required before any other call. | | capture(error, options?) | Ship an Error / thrown value. | | captureMessage(msg, opts?) | Ship a non-error message (defaults to level: "info"). | | setUser(user \| null) | Tag every subsequent event with this user. | | setContext(key, value) | Attach key/value extra data to every subsequent event. | | setTag(key, value) | Attach a searchable tag to every subsequent event. | | flush(timeoutMs = 2000) | Wait for in-flight requests. Returns false on timeout. | | close() | Stop processing future events (in-flight requests still complete). | | getClient() | Get the singleton client, or null if init() wasn't called yet. |

capture() and captureMessage() accept an options object:

capture(err, {
  level: "fatal",                       // fatal | error | warning | info | debug
  tags: { module: "auth", retried: 1 }, // searchable
  extra: { requestId: "abc-123" },      // non-searchable detail
  user: { id: "u_42" },                 // override setUser
  url: "/checkout/payment",             // override default URL
});

Frameworks

Next.js (App Router) — drop-in subpaths

The package ships pre-wired entry points for Next.js. Three lines of code total:

// instrumentation.ts (project root) — server errors + init
export { register, onRequestError } from "@autotix/sdk/nextjs";

// app/layout.tsx — browser auto-capture
import { AutotixProvider } from "@autotix/sdk/nextjs/client";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <AutotixProvider />
        {children}
      </body>
    </html>
  );
}

# .env (or Vercel project env)
NEXT_PUBLIC_AUTOTIX_INGEST_TOKEN=iat_xxx

That's it. You now get:

• Uncaught browser errors + unhandled promise rejections
• Server component / route handler / server action errors (via Next 15's onRequestError)
• Auto-tagged environment (from VERCEL_ENV) and release (from VERCEL_GIT_COMMIT_SHA) on every event

To tag events with the signed-in user, call setUser() from your auth context:

import { setUser } from "@autotix/sdk";
setUser({ id: user.id, email: user.email });

React error boundaries

import { Component } from "react";
import { capture } from "@autotix/sdk";

export class ErrorBoundary extends Component<{ children: React.ReactNode }> {
  componentDidCatch(error: Error, info: React.ErrorInfo) {
    capture(error, { extra: { componentStack: info.componentStack } });
  }
  render() { return this.props.children; }
}

AWS Lambda

import { init, capture, flush } from "@autotix/sdk";

init({ token: process.env.AUTOTIX_INGEST_TOKEN! });

export const handler = async (event) => {
  try {
    return await doWork(event);
  } catch (err) {
    capture(err, { extra: { awsRequestId: event.requestContext?.requestId } });
    // IMPORTANT: flush before Lambda freezes the runtime, or your event is lost.
    await flush();
    throw err;
  }
};

What gets sent

Every event is a small JSON object — no PII unless you provide it via setUser() / extra:

{
  "message": "TypeError: Cannot read properties of undefined",
  "stack": "TypeError: …\n    at handleClick (app.js:42:7)\n    …",
  "level": "error",
  "url": "https://app.example.com/checkout",
  "userAgent": "Mozilla/5.0 …",
  "release": "v1.4.2",
  "environment": "production",
  "timestamp": 1735603200000,
  "tags": { "module": "auth" },
  "extra": { "requestId": "abc-123" },
  "user": { "id": "u_42" }
}

Privacy / safety

• Failures don't break your app. A network error or 500 from Autotix returns silently — never throws into your code.
• keepalive: true so events fire during page navigation aren't dropped.
• Body cap: 64 KB. Larger payloads are rejected by the server with 413.
• Rate limit: 600 req/min/token. Use sampleRate if you exceed this.
• No third-party deps. Just the platform fetch.

License

MIT