@nwire/envelope 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+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,59 @@
+# @nwire/envelope
+
+> Universal message envelope — correlation, causation, tenant, user, version.
+
+## What it is
+
+`MessageEnvelope` is the small bag of identifiers every message in Nwire carries — an HTTP request, a queue job, a scheduled tick, an action dispatched from a CLI. It makes chains of work debuggable, traceable, and tenant-scoped. Zero-dep leaf package: logger, dead-letter, queue, http, store all depend on this.
+
+## Install
+
+```bash
+pnpm add @nwire/envelope
+```
+
+## Standalone use
+
+For developers who want a tiny correlation-id / causation-chain primitive in any TS app — no Nwire dependency required.
+
+```ts
+import { seedEnvelope, deriveEnvelope } from "@nwire/envelope";
+
+// At the edge — seed a new envelope for an incoming request
+const root = seedEnvelope({
+  source: "http",
+  tenant: "acme",
+  userId: req.userId,
+});
+
+// Inside a handler — derive a child envelope for the next message
+const child = deriveEnvelope(root, { source: "queue" });
+// child.correlationId === root.correlationId  (same chain)
+// child.causationId   === root.messageId      (parent reference)
+```
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack. Already transitively present in every layer; you usually read `ctx.envelope` inside a handler. Touch this package directly when writing a custom transport or bus adapter that must construct envelopes.
+
+```ts
+// inside a handler:
+defineAction("recordWash", {
+  handler: async ({ input, ctx }) => {
+    ctx.logger.info({ stationId: input.stationId }, "wash recorded");
+    // ctx.envelope.correlationId, .tenant, .userId all attached automatically
+  },
+});
+```
+
+## API
+
+- `MessageEnvelope` — shape: `messageId`, `correlationId`, `causationId`, `tenant?`, `userId?`, `timestamp`, `version`, `source?`.
+- `seedEnvelope(input)` — start a new chain at a system edge.
+- `deriveEnvelope(parent, overrides?)` — descend one step; carries correlation, advances causation.
+- `SeedEnvelopeInput` — caller-side type.
+
+## See also
+
+- [Architecture sketch §05 — Foundation tier](../../architecture-sketch.html#packages)
+- Sibling packages: [@nwire/messages](../nwire-messages), [@nwire/logger](../nwire-logger), [@nwire/queue](../nwire-queue)

package/dist/envelope.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `@nwire/envelope` — the framework's universal message envelope.
+ *
+ * Every message in nwire — an HTTP request, a queue job, a scheduled tick,
+ * an action dispatched from a CLI — carries a `MessageEnvelope`. The
+ * envelope is what makes a chain of work debuggable, traceable, and tenant-
+ * scoped.
+ *
+ *   messageId      — unique to this individual message
+ *   correlationId  — ties a chain of related messages together
+ *   causationId    — the messageId of the message that caused this one
+ *   tenant         — tenant scope (multi-tenancy)
+ *   userId         — acting user (audit + authz)
+ *   timestamp      — ISO 8601 at envelope creation
+ *   version        — schema evolution
+ *
+ * Zero-dep core package. Logger, DLQ, queue, http, mongo all depend on this.
+ */
+export { seedEnvelope, deriveEnvelope, type MessageEnvelope, type SeedEnvelopeInput, } from "./message-envelope.js";
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,YAAY,EACZ,cAAc,EACd,KAAK,eAAe,EACpB,KAAK,iBAAiB,GACvB,MAAM,oBAAoB,CAAC"}

package/dist/envelope.js

@@ -0,0 +1,20 @@
+/**
+ * `@nwire/envelope` — the framework's universal message envelope.
+ *
+ * Every message in nwire — an HTTP request, a queue job, a scheduled tick,
+ * an action dispatched from a CLI — carries a `MessageEnvelope`. The
+ * envelope is what makes a chain of work debuggable, traceable, and tenant-
+ * scoped.
+ *
+ *   messageId      — unique to this individual message
+ *   correlationId  — ties a chain of related messages together
+ *   causationId    — the messageId of the message that caused this one
+ *   tenant         — tenant scope (multi-tenancy)
+ *   userId         — acting user (audit + authz)
+ *   timestamp      — ISO 8601 at envelope creation
+ *   version        — schema evolution
+ *
+ * Zero-dep core package. Logger, DLQ, queue, http, mongo all depend on this.
+ */
+export { seedEnvelope, deriveEnvelope, } from "./message-envelope.js";
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,YAAY,EACZ,cAAc,GAGf,MAAM,oBAAoB,CAAC"}

package/dist/message-envelope.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Every message in the framework — an HTTP request entering a handler, an
+ * event flowing through the bus, a queued job, a scheduled tick — carries
+ * an envelope. The envelope is what makes a chain of work debuggable.
+ *
+ *   messageId      — unique to this individual message
+ *   correlationId  — ties a chain of related messages together; preserved
+ *                    across all handlers triggered by an originating event
+ *   causationId    — the messageId of the message that caused this one;
+ *                    enables reconstructing the *graph* of work, not just
+ *                    the chain
+ *   tenant / userId — actor context propagated for authorization + audit
+ *   timestamp      — ISO 8601 string at envelope creation
+ *   version        — for schema evolution; default 1
+ *
+ * The envelope is created at entry points (HTTP middleware, queue consumer)
+ * and propagated automatically through every sub-handler invocation. The
+ * developer never constructs one; the framework does.
+ */
+export interface MessageEnvelope {
+    readonly messageId: string;
+    readonly correlationId: string;
+    readonly causationId: string;
+    readonly tenant?: string;
+    readonly userId?: string;
+    /**
+     * Resolved User object — attached by the identity plugin's HTTP/transport
+     * middleware after token verification, alongside `userId`. RBAC + audit
+     * + per-request scoping read from here. Kept as `unknown` here so the
+     * envelope stays domain-agnostic; `@nwire/auth` narrows this to `User`.
+     */
+    readonly user?: unknown;
+    readonly timestamp: string;
+    readonly version: number;
+}
+export interface SeedEnvelopeInput {
+    correlationId?: string;
+    causationId?: string;
+    tenant?: string;
+    userId?: string;
+    user?: unknown;
+    version?: number;
+}
+/**
+ * Create a fresh envelope at an entry point (HTTP request, queue message,
+ * scheduled tick). Use this where the chain begins.
+ *
+ * If a correlationId is supplied (e.g., via an `x-correlation-id` header),
+ * use it; otherwise mint a new one. If a causationId is supplied (e.g., via
+ * `x-causation-id` header from an upstream service), use it; otherwise the
+ * envelope sits at the head of its chain (causationId === messageId).
+ */
+export declare function seedEnvelope(input?: SeedEnvelopeInput): MessageEnvelope;
+/**
+ * Derive a child envelope from a parent. Use this when a handler invokes
+ * another handler, or when an event handler is dispatched with the event's
+ * envelope as its parent.
+ *
+ *   - new messageId (this message is its own thing)
+ *   - same correlationId (chain stays linked)
+ *   - causationId = parent's messageId (this was caused by that)
+ *   - tenant / userId / version inherited unless overridden
+ */
+export declare function deriveEnvelope(parent: MessageEnvelope, overrides?: Partial<Pick<MessageEnvelope, "tenant" | "userId" | "user" | "version">>): MessageEnvelope;
+//# sourceMappingURL=message-envelope.d.ts.map

package/dist/message-envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-envelope.d.ts","sourceRoot":"","sources":["../src/message-envelope.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,GAAE,iBAAsB,GAAG,eAAe,CAY3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,eAAe,EACvB,SAAS,GAAE,OAAO,CAAC,IAAI,CAAC,eAAe,EAAE,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC,CAAM,GACvF,eAAe,CAWjB"}

package/dist/message-envelope.js

@@ -0,0 +1,46 @@
+import { randomUUID } from "node:crypto";
+/**
+ * Create a fresh envelope at an entry point (HTTP request, queue message,
+ * scheduled tick). Use this where the chain begins.
+ *
+ * If a correlationId is supplied (e.g., via an `x-correlation-id` header),
+ * use it; otherwise mint a new one. If a causationId is supplied (e.g., via
+ * `x-causation-id` header from an upstream service), use it; otherwise the
+ * envelope sits at the head of its chain (causationId === messageId).
+ */
+export function seedEnvelope(input = {}) {
+    const messageId = randomUUID();
+    return {
+        messageId,
+        correlationId: input.correlationId ?? messageId,
+        causationId: input.causationId ?? messageId,
+        tenant: input.tenant,
+        userId: input.userId,
+        user: input.user,
+        timestamp: new Date().toISOString(),
+        version: input.version ?? 1,
+    };
+}
+/**
+ * Derive a child envelope from a parent. Use this when a handler invokes
+ * another handler, or when an event handler is dispatched with the event's
+ * envelope as its parent.
+ *
+ *   - new messageId (this message is its own thing)
+ *   - same correlationId (chain stays linked)
+ *   - causationId = parent's messageId (this was caused by that)
+ *   - tenant / userId / version inherited unless overridden
+ */
+export function deriveEnvelope(parent, overrides = {}) {
+    return {
+        messageId: randomUUID(),
+        correlationId: parent.correlationId,
+        causationId: parent.messageId,
+        tenant: overrides.tenant ?? parent.tenant,
+        userId: overrides.userId ?? parent.userId,
+        user: overrides.user ?? parent.user,
+        timestamp: new Date().toISOString(),
+        version: overrides.version ?? parent.version,
+    };
+}
+//# sourceMappingURL=message-envelope.js.map

package/dist/message-envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-envelope.js","sourceRoot":"","sources":["../src/message-envelope.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AA+CzC;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,QAA2B,EAAE;IACxD,MAAM,SAAS,GAAG,UAAU,EAAE,CAAC;IAC/B,OAAO;QACL,SAAS;QACT,aAAa,EAAE,KAAK,CAAC,aAAa,IAAI,SAAS;QAC/C,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,SAAS;QAC3C,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,CAAC;KAC5B,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAuB,EACvB,YAAsF,EAAE;IAExF,OAAO;QACL,SAAS,EAAE,UAAU,EAAE;QACvB,aAAa,EAAE,MAAM,CAAC,aAAa;QACnC,WAAW,EAAE,MAAM,CAAC,SAAS;QAC7B,MAAM,EAAE,SAAS,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM;QACzC,MAAM,EAAE,SAAS,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM;QACzC,IAAI,EAAE,SAAS,CAAC,IAAI,IAAI,MAAM,CAAC,IAAI;QACnC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACnC,OAAO,EAAE,SAAS,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO;KAC7C,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nwire/envelope",
+  "version": "0.7.0",
+  "description": "Nwire — universal message envelope. messageId, correlationId, causationId, tenant, userId. Zero-dep; every nwire package depends on this.",
+  "keywords": [
+    "causation",
+    "correlation",
+    "envelope",
+    "nwire",
+    "tracing"
+  ],
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./dist/envelope.js",
+  "types": "./dist/envelope.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/envelope.js",
+      "types": "./dist/envelope.d.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.9",
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsc && node ../../scripts/fix-dist-extensions.mjs dist",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}