@bara-agency/bems-sdk

Send errors from Heroku Node.js apps to the Bara Log Error Retool workflow webhook using the same payload shape as existing Retool and Zapier integrations.

Install

npm install @bara-agency/bems-sdk

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | RETOOL_LOG_ERROR_API_KEY | Yes | Sent as X-Workflow-Api-Key header | | APP_ID | Yes | Project UUID sent as app_id (see below) | | APP_NAME | Yes | Display name → payload app_name | | APP_LINK | Yes | Heroku dashboard URL → payload app_link (not the public app URL) | | APP_ENV | Yes (production) | Errors are sent only when APP_ENV=production | | RETOOL_LOG_ERROR_SYSTEM | No | Default "Heroku" | | RETOOL_LOG_ERROR_WEBHOOK_URL | No | Default https://bara.retool.com/url/bals-query | | RETOOL_LOG_ERROR_ENABLED | No | Set to "false" to disable | | RETOOL_LOG_ERROR_EXCLUDED_STATUS_CODES | No | Default 500,404,403 |

Webhook endpoint

https://bara.retool.com/url/bals-query

Authentication: X-Workflow-Api-Key header from RETOOL_LOG_ERROR_API_KEY.

APP_ID — project UUID

Generate once per project and reuse on every Heroku environment:

uuidgen | tr '[:upper:]' '[:lower:]'

| Variable | Payload field | |----------|---------------| | APP_ID | app_id | | APP_NAME | app_name | | APP_LINK | app_link (Heroku dashboard URL) |

Usage

import express from "express";
import { createRetoolErrorLogger } from "@bara-agency/bems-sdk";

const errorLogger = createRetoolErrorLogger();

errorLogger.installProcessHandlers();

const app = express();
app.use(errorLogger.expressMiddleware());

app.listen(process.env.PORT ?? 3000);

Heroku config (production)

heroku config:set \
  RETOOL_LOG_ERROR_API_KEY="your-workflow-api-key" \
  APP_ID="your-project-uuid" \
  APP_NAME="bara-forms" \
  APP_LINK="https://dashboard.heroku.com/apps/bara-forms-prod" \
  APP_ENV="production" \
  --app bara-forms-prod

Docs

• Log Error workflow review
• bara-forms integration guide

Development

npm install
npm run build

Publish

Releases are published to npm when you:

• Create a GitHub Release, or
• Push a version tag (git push origin v0.1.1), or
• Run the Publish workflow manually from the Actions tab

The workflow uses npm trusted publishing (OIDC) — no NPM_TOKEN secret is required.

For a manual publish from your machine:

npm publish --access public --otp=YOUR_6_DIGIT_CODE

Requires npm login with publish access to the @bara-agency scope.