Rollbar plugin

• Every response carries err. err: 0 is success and anything else is a failure — and the HTTP status is not a reliable proxy for it. The live “access token required” response is a 401 with { "err": 1, "message": "access token required" }, while a rejected item update can be a 200 with err: 1. The plugin reads err and turns a non-zero value into an error even on a 200.
• Tokens are scoped, and no single token covers every operation. A project token with read and write covers items, occurrences, events, comments (reading) and deploy listing for its own project; Rollbar will not give one token both write and post_server_item. deploys.create needs a project token with post_server_item. projects.list needs an account or personal access token. itemComments.create needs a personal access token with write, and posts as that user. With an account or personal token, pass project_id on the item and occurrence operations, or Rollbar answers 403 “Requires project access”. A 401 means the token is missing or malformed; a 403 means it is valid but lacks the scope or project.
• instances is the API’s word for occurrences. Rollbar lists occurrences at /api/1/instances and returns them under an instances key; the plugin exposes them as occurrences so the name matches the concept.
• Repeated filters. level and project_ids are repeated query parameters, so items.list takes arrays and sends each value under the same key. Rollbar’s documented ids filter is not offered: in a live check it ignored one id and answered 502 to several.
• Item ids. items.list returns each id as a numeric string while items.get returns a number; the plugin returns a number from both.
• Paging is a page number. Lists return 20 per page by default (items.list 100) and the item, comment and event lists report total_count beside it, which is null when a project has more than 100,000 unique items. A snooze needs a duration, so items.update rejects snooze_enabled without snooze_expiration_in_seconds.
• Timestamps are unix seconds, on requests and responses alike.
• Retries. A 429 is the token’s rate limit. Rollbar sends no Retry-After; the plugin waits for the time in X-Rate-Limit-Remaining-Seconds / X-Rate-Limit-Reset and backs off exponentially when neither is present. A 5xx is retried only for a read; a body-level failure has no status and is never retried.
• Deploys. deploys.create answers { "data": { "deploy_id": … } }, the one route without err/result; the plugin returns deploy_id. deploys.list has no environment filter (Rollbar ignores one).

• 11 typed API operations

​

Setup

npm install corsair @corsair-dev/rollbar better-sqlite3
npm install --save-dev @types/better-sqlite3

yarn add corsair @corsair-dev/rollbar better-sqlite3
yarn add --dev @types/better-sqlite3

pnpm install corsair @corsair-dev/rollbar better-sqlite3
pnpm install --save-dev @types/better-sqlite3

bun add corsair @corsair-dev/rollbar better-sqlite3
bun add --dev @types/better-sqlite3

import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { rollbar } from '@corsair-dev/rollbar';

export const corsair = createCorsair({
	plugins: [
		rollbar(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});

rollbar()

const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'rollbar',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl

​

Example API calls

const tenant = corsair.withTenant('acme');
await tenant.rollbar.api.items.list({ environment: 'production' });

const tenant = corsair.withTenant('acme');
await tenant.rollbar.api.items.update({ item_id: 12345, snooze_enabled: true, snooze_expiration_in_seconds: 3600 });

​

What’s next