@dispatchitapp/express 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Recursivity LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,29 @@
+# @dispatchitapp/express
+
+Express error-handler middleware for [Dispatch](https://dispatchit.app). Auto-captures
+unhandled route errors with request context, then re-propagates — it never swallows the error.
+
+```ts
+import express from "express";
+import { init } from "@dispatchitapp/node";
+import { errorHandler } from "@dispatchitapp/express";
+
+init({ apiKey: process.env.DISPATCH_API_KEY!, environment: process.env.NODE_ENV });
+
+const app = express();
+app.get("/orders/:id", (req, res) => { /* ... */ });
+
+// Register LAST — after routes and any other error handlers.
+app.use(errorHandler({
+  user: (req) => req.user && { external_id: req.user.id, email: req.user.email },
+}));
+```
+
+Each captured event carries `handled: false`, the request (`url`, `method`, `query_string`,
+allow-listed headers, client IP), the `transaction` (`"POST /orders/:id"` — the matched route
+pattern, low cardinality), and the resolved user. The error then continues to Express's default
+handler (or yours), so behaviour is unchanged.
+
+Options: `client` (defaults to the `init()` client), `user(req)`, `shouldHandle(err, req)`.
+Pairs with [`@dispatchitapp/node`](../node)'s global handlers, which catch anything that escapes the
+request lifecycle.

package/dist/index.cjs

@@ -0,0 +1,57 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  errorHandler: () => errorHandler
+});
+module.exports = __toCommonJS(index_exports);
+var import_node = require("@dispatchitapp/node");
+function transactionOf(req) {
+  const routePath = req.route?.path;
+  const base = req.baseUrl ?? "";
+  const path = routePath ? base + routePath : req.path ?? req.originalUrl ?? req.url;
+  if (!path) return void 0;
+  return req.method ? `${req.method} ${path}` : path;
+}
+function errorHandler(options = {}) {
+  return function dispatchErrorHandler(err, req, _res, next) {
+    try {
+      const client = options.client ?? (0, import_node.getClient)();
+      const handle = options.shouldHandle ? options.shouldHandle(err, req) : true;
+      if (client && handle) {
+        const resolvedUser = options.user ? options.user(req) : req.user;
+        client.captureException(err, {
+          handled: false,
+          request: (0, import_node.extractRequest)(req),
+          transaction: transactionOf(req),
+          user: (0, import_node.normalizeUser)(resolvedUser)
+        });
+      }
+    } catch {
+    }
+    next(err);
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  errorHandler
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @dispatchitapp/express — Express error-handler middleware.\n//\n// Register it LAST (after your routes and any other error handlers) so it sees unhandled route\n// errors with full request context, captures them (handled:false), and then re-propagates via\n// next(err) — it never swallows the error. The innermost-and-re-raise shape mirrors the gem's\n// Rack middleware.\n\nimport {\n  type Client,\n  type DispatchUser,\n  type HttpRequestLike,\n  extractRequest,\n  getClient,\n  normalizeUser,\n} from \"@dispatchitapp/node\";\n\n// Structural subset of an Express request — we depend on no Express types.\nexport interface ExpressRequestLike extends HttpRequestLike {\n  baseUrl?: string;\n  path?: string;\n  route?: { path?: string };\n  user?: unknown;\n}\n\ntype NextFunction = (err?: unknown) => void;\n\nexport interface ErrorHandlerOptions {\n  /** Client to report through. Defaults to the module-level client from init(). */\n  client?: Client;\n  /** Resolve the affected user from the request. Falls back to req.user. */\n  user?: (req: ExpressRequestLike) => DispatchUser | Record<string, unknown> | null | undefined;\n  /** Decide whether a given error should be captured. Default: always. */\n  shouldHandle?: (err: unknown, req: ExpressRequestLike) => boolean;\n}\n\n// \"POST /orders/:id\" — prefer the matched route pattern (low cardinality), else the path.\nfunction transactionOf(req: ExpressRequestLike): string | undefined {\n  const routePath = req.route?.path;\n  const base = req.baseUrl ?? \"\";\n  const path = routePath ? base + routePath : (req.path ?? req.originalUrl ?? req.url);\n  if (!path) return undefined;\n  return req.method ? `${req.method} ${path}` : path;\n}\n\nexport function errorHandler(options: ErrorHandlerOptions = {}) {\n  // Arity 4 is required for Express to treat this as an error handler.\n  return function dispatchErrorHandler(\n    err: unknown,\n    req: ExpressRequestLike,\n    _res: unknown,\n    next: NextFunction,\n  ): void {\n    try {\n      const client = options.client ?? getClient();\n      const handle = options.shouldHandle ? options.shouldHandle(err, req) : true;\n      if (client && handle) {\n        const resolvedUser = options.user ? options.user(req) : req.user;\n        client.captureException(err, {\n          handled: false,\n          request: extractRequest(req),\n          transaction: transactionOf(req),\n          user: normalizeUser(resolvedUser),\n        });\n      }\n    } catch {\n      // Telemetry must never break the error pipeline.\n    }\n    next(err);\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAOA,kBAOO;AAsBP,SAAS,cAAc,KAA6C;AAClE,QAAM,YAAY,IAAI,OAAO;AAC7B,QAAM,OAAO,IAAI,WAAW;AAC5B,QAAM,OAAO,YAAY,OAAO,YAAa,IAAI,QAAQ,IAAI,eAAe,IAAI;AAChF,MAAI,CAAC,KAAM,QAAO;AAClB,SAAO,IAAI,SAAS,GAAG,IAAI,MAAM,IAAI,IAAI,KAAK;AAChD;AAEO,SAAS,aAAa,UAA+B,CAAC,GAAG;AAE9D,SAAO,SAAS,qBACd,KACA,KACA,MACA,MACM;AACN,QAAI;AACF,YAAM,SAAS,QAAQ,cAAU,uBAAU;AAC3C,YAAM,SAAS,QAAQ,eAAe,QAAQ,aAAa,KAAK,GAAG,IAAI;AACvE,UAAI,UAAU,QAAQ;AACpB,cAAM,eAAe,QAAQ,OAAO,QAAQ,KAAK,GAAG,IAAI,IAAI;AAC5D,eAAO,iBAAiB,KAAK;AAAA,UAC3B,SAAS;AAAA,UACT,aAAS,4BAAe,GAAG;AAAA,UAC3B,aAAa,cAAc,GAAG;AAAA,UAC9B,UAAM,2BAAc,YAAY;AAAA,QAClC,CAAC;AAAA,MACH;AAAA,IACF,QAAQ;AAAA,IAER;AACA,SAAK,GAAG;AAAA,EACV;AACF;","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,22 @@
+import { Client, HttpRequestLike, DispatchUser } from '@dispatchitapp/node';
+
+interface ExpressRequestLike extends HttpRequestLike {
+    baseUrl?: string;
+    path?: string;
+    route?: {
+        path?: string;
+    };
+    user?: unknown;
+}
+type NextFunction = (err?: unknown) => void;
+interface ErrorHandlerOptions {
+    /** Client to report through. Defaults to the module-level client from init(). */
+    client?: Client;
+    /** Resolve the affected user from the request. Falls back to req.user. */
+    user?: (req: ExpressRequestLike) => DispatchUser | Record<string, unknown> | null | undefined;
+    /** Decide whether a given error should be captured. Default: always. */
+    shouldHandle?: (err: unknown, req: ExpressRequestLike) => boolean;
+}
+declare function errorHandler(options?: ErrorHandlerOptions): (err: unknown, req: ExpressRequestLike, _res: unknown, next: NextFunction) => void;
+
+export { type ErrorHandlerOptions, type ExpressRequestLike, errorHandler };

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+import { Client, HttpRequestLike, DispatchUser } from '@dispatchitapp/node';
+
+interface ExpressRequestLike extends HttpRequestLike {
+    baseUrl?: string;
+    path?: string;
+    route?: {
+        path?: string;
+    };
+    user?: unknown;
+}
+type NextFunction = (err?: unknown) => void;
+interface ErrorHandlerOptions {
+    /** Client to report through. Defaults to the module-level client from init(). */
+    client?: Client;
+    /** Resolve the affected user from the request. Falls back to req.user. */
+    user?: (req: ExpressRequestLike) => DispatchUser | Record<string, unknown> | null | undefined;
+    /** Decide whether a given error should be captured. Default: always. */
+    shouldHandle?: (err: unknown, req: ExpressRequestLike) => boolean;
+}
+declare function errorHandler(options?: ErrorHandlerOptions): (err: unknown, req: ExpressRequestLike, _res: unknown, next: NextFunction) => void;
+
+export { type ErrorHandlerOptions, type ExpressRequestLike, errorHandler };

package/dist/index.js

@@ -0,0 +1,36 @@
+// src/index.ts
+import {
+  extractRequest,
+  getClient,
+  normalizeUser
+} from "@dispatchitapp/node";
+function transactionOf(req) {
+  const routePath = req.route?.path;
+  const base = req.baseUrl ?? "";
+  const path = routePath ? base + routePath : req.path ?? req.originalUrl ?? req.url;
+  if (!path) return void 0;
+  return req.method ? `${req.method} ${path}` : path;
+}
+function errorHandler(options = {}) {
+  return function dispatchErrorHandler(err, req, _res, next) {
+    try {
+      const client = options.client ?? getClient();
+      const handle = options.shouldHandle ? options.shouldHandle(err, req) : true;
+      if (client && handle) {
+        const resolvedUser = options.user ? options.user(req) : req.user;
+        client.captureException(err, {
+          handled: false,
+          request: extractRequest(req),
+          transaction: transactionOf(req),
+          user: normalizeUser(resolvedUser)
+        });
+      }
+    } catch {
+    }
+    next(err);
+  };
+}
+export {
+  errorHandler
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["// @dispatchitapp/express — Express error-handler middleware.\n//\n// Register it LAST (after your routes and any other error handlers) so it sees unhandled route\n// errors with full request context, captures them (handled:false), and then re-propagates via\n// next(err) — it never swallows the error. The innermost-and-re-raise shape mirrors the gem's\n// Rack middleware.\n\nimport {\n  type Client,\n  type DispatchUser,\n  type HttpRequestLike,\n  extractRequest,\n  getClient,\n  normalizeUser,\n} from \"@dispatchitapp/node\";\n\n// Structural subset of an Express request — we depend on no Express types.\nexport interface ExpressRequestLike extends HttpRequestLike {\n  baseUrl?: string;\n  path?: string;\n  route?: { path?: string };\n  user?: unknown;\n}\n\ntype NextFunction = (err?: unknown) => void;\n\nexport interface ErrorHandlerOptions {\n  /** Client to report through. Defaults to the module-level client from init(). */\n  client?: Client;\n  /** Resolve the affected user from the request. Falls back to req.user. */\n  user?: (req: ExpressRequestLike) => DispatchUser | Record<string, unknown> | null | undefined;\n  /** Decide whether a given error should be captured. Default: always. */\n  shouldHandle?: (err: unknown, req: ExpressRequestLike) => boolean;\n}\n\n// \"POST /orders/:id\" — prefer the matched route pattern (low cardinality), else the path.\nfunction transactionOf(req: ExpressRequestLike): string | undefined {\n  const routePath = req.route?.path;\n  const base = req.baseUrl ?? \"\";\n  const path = routePath ? base + routePath : (req.path ?? req.originalUrl ?? req.url);\n  if (!path) return undefined;\n  return req.method ? `${req.method} ${path}` : path;\n}\n\nexport function errorHandler(options: ErrorHandlerOptions = {}) {\n  // Arity 4 is required for Express to treat this as an error handler.\n  return function dispatchErrorHandler(\n    err: unknown,\n    req: ExpressRequestLike,\n    _res: unknown,\n    next: NextFunction,\n  ): void {\n    try {\n      const client = options.client ?? getClient();\n      const handle = options.shouldHandle ? options.shouldHandle(err, req) : true;\n      if (client && handle) {\n        const resolvedUser = options.user ? options.user(req) : req.user;\n        client.captureException(err, {\n          handled: false,\n          request: extractRequest(req),\n          transaction: transactionOf(req),\n          user: normalizeUser(resolvedUser),\n        });\n      }\n    } catch {\n      // Telemetry must never break the error pipeline.\n    }\n    next(err);\n  };\n}\n"],"mappings":";AAOA;AAAA,EAIE;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAsBP,SAAS,cAAc,KAA6C;AAClE,QAAM,YAAY,IAAI,OAAO;AAC7B,QAAM,OAAO,IAAI,WAAW;AAC5B,QAAM,OAAO,YAAY,OAAO,YAAa,IAAI,QAAQ,IAAI,eAAe,IAAI;AAChF,MAAI,CAAC,KAAM,QAAO;AAClB,SAAO,IAAI,SAAS,GAAG,IAAI,MAAM,IAAI,IAAI,KAAK;AAChD;AAEO,SAAS,aAAa,UAA+B,CAAC,GAAG;AAE9D,SAAO,SAAS,qBACd,KACA,KACA,MACA,MACM;AACN,QAAI;AACF,YAAM,SAAS,QAAQ,UAAU,UAAU;AAC3C,YAAM,SAAS,QAAQ,eAAe,QAAQ,aAAa,KAAK,GAAG,IAAI;AACvE,UAAI,UAAU,QAAQ;AACpB,cAAM,eAAe,QAAQ,OAAO,QAAQ,KAAK,GAAG,IAAI,IAAI;AAC5D,eAAO,iBAAiB,KAAK;AAAA,UAC3B,SAAS;AAAA,UACT,SAAS,eAAe,GAAG;AAAA,UAC3B,aAAa,cAAc,GAAG;AAAA,UAC9B,MAAM,cAAc,YAAY;AAAA,QAClC,CAAC;AAAA,MACH;AAAA,IACF,QAAQ;AAAA,IAER;AACA,SAAK,GAAG;AAAA,EACV;AACF;","names":[]}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@dispatchitapp/express",
+  "version": "1.0.0",
+  "description": "Express error-handler middleware for Dispatch — auto-captures unhandled route errors with request context.",
+  "license": "MIT",
+  "author": "Dispatch Team <hello@dispatchit.app>",
+  "homepage": "https://dispatchit.app",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Recursivity-LLC/dispatch-sdks.git",
+    "directory": "packages/express"
+  },
+  "bugs": "https://github.com/Recursivity-LLC/dispatch-sdks/issues",
+  "keywords": [
+    "error-tracking",
+    "express",
+    "middleware",
+    "dispatch",
+    "monitoring"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@dispatchitapp/node": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0",
+    "@dispatchitapp/core": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "tsc --noEmit"
+  }
+}