@alby-sh/report

Official Alby error-tracking SDK for Node.js and TypeScript.

Captures uncaught exceptions, unhandled rejections, and anything you explicitly report, then ships them to your Alby project where an AI agent can auto-open a fix task.

Install

npm install @alby-sh/report

Use

import { Alby } from '@alby-sh/report'

Alby.init({
  dsn: process.env.ALBY_DSN,      // https://<key>@alby.sh/ingest/v1/<app-id>
  release: '1.4.2',
  environment: 'production',
})

// Uncaught exceptions and unhandled rejections are sent automatically.

// Manual report:
try {
  doThing()
} catch (err) {
  Alby.captureException(err)
}

// Non-error events:
Alby.captureMessage('Failed to acquire lease', 'warning')

// Enrich:
Alby.setUser({ id: 'u_412', email: '[email protected]' })
Alby.setTag('region', 'eu-west-3')
Alby.setContext('billing_tenant', { plan: 'pro', seats: 12 })
Alby.addBreadcrumb({ type: 'http', message: 'GET /api/orders/42' })

// Before exit (e.g. in a short-lived CLI):
await Alby.flush(2000)

Source-map upload

After a production build:

export ALBY_DSN="https://<key>@alby.sh/ingest/v1/<app-id>"
export ALBY_TOKEN="<your Alby personal access token>"

npx alby sourcemaps upload \
  --dsn "$ALBY_DSN" \
  --release "$npm_package_version" \
  --url-prefix "https://app.example.com/static/" \
  dist/**/*.map

Wire protocol

This SDK speaks the Alby Ingest Protocol v1. If you're writing a new SDK (different runtime, different language) start there.

Options

| Option | Type | Default | Notes | |-----------------|------------------|-----------------|-------| | dsn | string | — (required) | The DSN from your Alby app settings. | | release | string | '' | Your build version. Enables release tracking / auto-resolve. | | environment | string | NODE_ENV | production / staging / dev / anything. | | sampleRate | 0..1 | 1 | Fraction of events actually sent. | | platform | string | 'node'/'browser' | Override auto-detection. | | serverName | string | os.hostname() | Attached to every event. | | autoRegister | boolean | true | Install process-level handlers. | | transport | Transport | FetchTransport| Custom delivery (tests, batching, filesystem spool). | | debug | boolean | false | Log SDK diagnostics. |

Links

• Website: alby.sh
• Report issues: GitHub Issues
• Other SDKs: alby-sdk-browser · alby-sdk-php · alby-sdk-python

License

MIT — © Alby.