@babelqueue/core 1.0.0 → 1.2.0

package/dist/chunk-7FUZ3LYT.js

@@ -0,0 +1,150 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/errors.ts
+var BabelQueueError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "BabelQueueError";
+  }
+};
+var UnknownUrnError = class extends BabelQueueError {
+  constructor(urn) {
+    super(`No handler is mapped for the message URN "${urn}".`);
+    this.name = "UnknownUrnError";
+  }
+};
+var InvalidPayloadError = class extends BabelQueueError {
+  constructor(urn, violation) {
+    super(`Message data for "${urn}" does not match its URN schema: ${violation}.`);
+    this.urn = urn;
+    this.violation = violation;
+    this.name = "InvalidPayloadError";
+  }
+  urn;
+  violation;
+};
+
+// src/codec.ts
+import { randomUUID } from "crypto";
+var SCHEMA_VERSION = 1;
+var SOURCE_LANG = "node";
+var EnvelopeCodec = {
+  SCHEMA_VERSION,
+  SOURCE_LANG,
+  /**
+   * Build the canonical envelope for a `(urn, data)` pair. Mints a fresh trace id
+   * unless `options.traceId` is given, starts `attempts` at 0, and stamps `meta`.
+   * Throws {@link BabelQueueError} when the URN is blank.
+   */
+  make(urn, data, options = {}) {
+    const resolvedUrn = (urn ?? "").trim();
+    if (resolvedUrn === "") {
+      throw new BabelQueueError(
+        "A polyglot message must expose a stable, non-empty URN so consumers can identify it without any class name."
+      );
+    }
+    const traceId = (options.traceId ?? "").trim() || randomUUID();
+    return {
+      job: resolvedUrn,
+      trace_id: traceId,
+      data: { ...data },
+      meta: {
+        id: randomUUID(),
+        queue: options.queue ?? "default",
+        lang: SOURCE_LANG,
+        schema_version: SCHEMA_VERSION,
+        created_at: Date.now()
+      },
+      attempts: 0
+    };
+  },
+  /**
+   * Build the envelope from a {@link PolyglotMessage}. If the message also
+   * implements {@link HasTraceId} and returns a non-empty value, that trace id is
+   * reused.
+   */
+  fromMessage(message, queue = "default") {
+    const traceId = typeof message.getBabelTraceId === "function" ? message.getBabelTraceId() ?? void 0 : void 0;
+    return EnvelopeCodec.make(message.getBabelUrn(), message.toPayload(), {
+      queue,
+      traceId
+    });
+  },
+  /**
+   * Encode the envelope as compact UTF-8 JSON. `JSON.stringify` already emits the
+   * canonical form — no spaces, and slashes/unicode/HTML left unescaped — matching
+   * the other SDK cores.
+   */
+  encode(envelope) {
+    return JSON.stringify(envelope);
+  },
+  /**
+   * Parse a raw JSON body. Returns `{}` for malformed or non-object input (call
+   * {@link EnvelopeCodec.accepts} before trusting it). Resolves the `urn` inbound
+   * alias into `job`.
+   */
+  decode(raw) {
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch {
+      return {};
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    const envelope = parsed;
+    if (!envelope.job && typeof envelope.urn === "string") {
+      envelope.job = envelope.urn;
+    }
+    return envelope;
+  },
+  /** The message URN — canonical `job`, with `urn` accepted as an alias. */
+  urn(envelope) {
+    const value = envelope?.job ?? envelope?.urn ?? "";
+    return typeof value === "string" ? value.trim() : "";
+  },
+  /**
+   * Whether a consumer should accept this envelope. Rejects a missing URN, an
+   * unsupported `meta.schema_version`, a non-object `data`, a non-integer
+   * `attempts`, or a blank `trace_id` — the consumer-side counterpart to the
+   * producer JSON Schema. Acts as a type guard that narrows to {@link Envelope}.
+   */
+  accepts(envelope) {
+    if (EnvelopeCodec.urn(envelope) === "") {
+      return false;
+    }
+    const meta = envelope.meta;
+    if (meta === null || typeof meta !== "object" || meta.schema_version !== SCHEMA_VERSION) {
+      return false;
+    }
+    const data = envelope.data;
+    if (data === null || typeof data !== "object" || Array.isArray(data)) {
+      return false;
+    }
+    const attempts = envelope.attempts;
+    if (typeof attempts !== "number" || !Number.isInteger(attempts)) {
+      return false;
+    }
+    const traceId = envelope.trace_id;
+    if (typeof traceId !== "string" || traceId.trim() === "") {
+      return false;
+    }
+    return true;
+  }
+};
+
+export {
+  __export,
+  BabelQueueError,
+  UnknownUrnError,
+  InvalidPayloadError,
+  SCHEMA_VERSION,
+  SOURCE_LANG,
+  EnvelopeCodec
+};
+//# sourceMappingURL=chunk-7FUZ3LYT.js.map

package/dist/chunk-7FUZ3LYT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/codec.ts"],"sourcesContent":["/** Base error for all BabelQueue failures. */\nexport class BabelQueueError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"BabelQueueError\";\n  }\n}\n\n/** Raised when no handler is mapped for a message URN. */\nexport class UnknownUrnError extends BabelQueueError {\n  constructor(urn: string) {\n    super(`No handler is mapped for the message URN \"${urn}\".`);\n    this.name = \"UnknownUrnError\";\n  }\n}\n\n/**\n * Raised when a message's `data` does not match the JSON Schema registered for its URN\n * (ADR-0024). The consumer-side {@link schema.wrap} throws it so the adapter redelivers\n * (and eventually dead-letters) a poison message.\n */\nexport class InvalidPayloadError extends BabelQueueError {\n  constructor(\n    readonly urn: string,\n    readonly violation: string,\n  ) {\n    super(`Message data for \"${urn}\" does not match its URN schema: ${violation}.`);\n    this.name = \"InvalidPayloadError\";\n  }\n}\n","import { randomUUID } from \"node:crypto\";\n\nimport type { HasTraceId, PolyglotMessage } from \"./contracts.js\";\nimport { BabelQueueError } from \"./errors.js\";\n\n/** The wire envelope schema version this core implements (versioned independently of the package version). */\nexport const SCHEMA_VERSION = 1;\n\n/** Stamped into `meta.lang` for envelopes produced by this core. */\nexport const SOURCE_LANG = \"node\";\n\n/** Immutable per-message metadata. */\nexport interface Meta {\n  id: string;\n  queue: string;\n  lang: string;\n  schema_version: number;\n  /** Unix milliseconds, UTC. */\n  created_at: number;\n}\n\n/** The additive block appended to an envelope when a message is dead-lettered. */\nexport interface DeadLetter {\n  reason: string;\n  error: string | null;\n  exception: string | null;\n  /** Unix milliseconds, UTC. */\n  failed_at: number;\n  original_queue: string;\n  attempts: number;\n  lang: string;\n}\n\n/**\n * The canonical BabelQueue wire message: a strict, language-neutral JSON shape\n * that every SDK produces and consumes identically. The property order here is\n * significant — it matches the other cores so {@link EnvelopeCodec.encode} is\n * byte-for-byte identical across the insertion-order languages (PHP/Python).\n */\nexport interface Envelope {\n  /** The message URN (never a class name). */\n  job: string;\n  /** Correlation id, preserved across every hop. */\n  trace_id: string;\n  /** The pure-JSON payload. */\n  data: Record<string, unknown>;\n  meta: Meta;\n  /** Top-level transport retry counter. */\n  attempts: number;\n  /** Present only once the message has been dead-lettered. */\n  dead_letter?: DeadLetter;\n}\n\n/**\n * A decoded, not-yet-validated envelope. Fields are loosely typed because they\n * come off the wire; `urn` is accepted as an inbound alias for `job`. Narrow it\n * with {@link EnvelopeCodec.accepts} before trusting the contents.\n */\nexport interface IncomingEnvelope {\n  job?: string;\n  /** Inbound alias for `job`. */\n  urn?: string;\n  trace_id?: string;\n  data?: unknown;\n  meta?: unknown;\n  attempts?: unknown;\n  dead_letter?: unknown;\n}\n\n/** Options for {@link EnvelopeCodec.make}. */\nexport interface MakeOptions {\n  /** Logical queue name recorded in `meta.queue` (default `\"default\"`). */\n  queue?: string;\n  /** Reuse an existing trace id (trace continuation) instead of minting one. */\n  traceId?: string;\n}\n\n/**\n * Builds, encodes and decodes the canonical envelope — the single Node/TypeScript\n * implementation of the wire format.\n */\nexport const EnvelopeCodec = {\n  SCHEMA_VERSION,\n  SOURCE_LANG,\n\n  /**\n   * Build the canonical envelope for a `(urn, data)` pair. Mints a fresh trace id\n   * unless `options.traceId` is given, starts `attempts` at 0, and stamps `meta`.\n   * Throws {@link BabelQueueError} when the URN is blank.\n   */\n  make(\n    urn: string,\n    data: Record<string, unknown>,\n    options: MakeOptions = {},\n  ): Envelope {\n    const resolvedUrn = (urn ?? \"\").trim();\n    if (resolvedUrn === \"\") {\n      throw new BabelQueueError(\n        \"A polyglot message must expose a stable, non-empty URN so consumers can identify it without any class name.\",\n      );\n    }\n\n    const traceId = (options.traceId ?? \"\").trim() || randomUUID();\n\n    return {\n      job: resolvedUrn,\n      trace_id: traceId,\n      data: { ...data },\n      meta: {\n        id: randomUUID(),\n        queue: options.queue ?? \"default\",\n        lang: SOURCE_LANG,\n        schema_version: SCHEMA_VERSION,\n        created_at: Date.now(),\n      },\n      attempts: 0,\n    };\n  },\n\n  /**\n   * Build the envelope from a {@link PolyglotMessage}. If the message also\n   * implements {@link HasTraceId} and returns a non-empty value, that trace id is\n   * reused.\n   */\n  fromMessage(\n    message: PolyglotMessage & Partial<HasTraceId>,\n    queue = \"default\",\n  ): Envelope {\n    const traceId =\n      typeof message.getBabelTraceId === \"function\"\n        ? (message.getBabelTraceId() ?? undefined)\n        : undefined;\n\n    return EnvelopeCodec.make(message.getBabelUrn(), message.toPayload(), {\n      queue,\n      traceId,\n    });\n  },\n\n  /**\n   * Encode the envelope as compact UTF-8 JSON. `JSON.stringify` already emits the\n   * canonical form — no spaces, and slashes/unicode/HTML left unescaped — matching\n   * the other SDK cores.\n   */\n  encode(envelope: Envelope): string {\n    return JSON.stringify(envelope);\n  },\n\n  /**\n   * Parse a raw JSON body. Returns `{}` for malformed or non-object input (call\n   * {@link EnvelopeCodec.accepts} before trusting it). Resolves the `urn` inbound\n   * alias into `job`.\n   */\n  decode(raw: string): IncomingEnvelope {\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(raw);\n    } catch {\n      return {};\n    }\n    if (parsed === null || typeof parsed !== \"object\" || Array.isArray(parsed)) {\n      return {};\n    }\n\n    const envelope = parsed as IncomingEnvelope;\n    if (!envelope.job && typeof envelope.urn === \"string\") {\n      envelope.job = envelope.urn;\n    }\n    return envelope;\n  },\n\n  /** The message URN — canonical `job`, with `urn` accepted as an alias. */\n  urn(envelope: IncomingEnvelope): string {\n    const value = envelope?.job ?? envelope?.urn ?? \"\";\n    return typeof value === \"string\" ? value.trim() : \"\";\n  },\n\n  /**\n   * Whether a consumer should accept this envelope. Rejects a missing URN, an\n   * unsupported `meta.schema_version`, a non-object `data`, a non-integer\n   * `attempts`, or a blank `trace_id` — the consumer-side counterpart to the\n   * producer JSON Schema. Acts as a type guard that narrows to {@link Envelope}.\n   */\n  accepts(envelope: IncomingEnvelope): envelope is Envelope {\n    if (EnvelopeCodec.urn(envelope) === \"\") {\n      return false;\n    }\n\n    const meta = envelope.meta;\n    if (\n      meta === null ||\n      typeof meta !== \"object\" ||\n      (meta as Meta).schema_version !== SCHEMA_VERSION\n    ) {\n      return false;\n    }\n\n    const data = envelope.data;\n    if (data === null || typeof data !== \"object\" || Array.isArray(data)) {\n      return false;\n    }\n\n    const attempts = envelope.attempts;\n    if (typeof attempts !== \"number\" || !Number.isInteger(attempts)) {\n      return false;\n    }\n\n    const traceId = envelope.trace_id;\n    if (typeof traceId !== \"string\" || traceId.trim() === \"\") {\n      return false;\n    }\n\n    return true;\n  },\n} as const;\n"],"mappings":"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","names":[]}

package/dist/idempotency-DDHjGwF7.d.cts

@@ -0,0 +1,178 @@
+/**
+ * A message that can be produced as a polyglot envelope. Implement it on your
+ * own classes/objects so {@link EnvelopeCodec.fromMessage} can build the canonical
+ * envelope without ever leaking a language-specific class name onto the wire.
+ */
+interface PolyglotMessage {
+    /** The stable URN that identifies this message across languages. */
+    getBabelUrn(): string;
+    /** The pure-JSON payload (no class instances). */
+    toPayload(): Record<string, unknown>;
+}
+/**
+ * Optionally implemented alongside {@link PolyglotMessage} to continue an existing
+ * distributed trace instead of minting a fresh one.
+ */
+interface HasTraceId {
+    /** The trace id to reuse, or null/undefined to mint a new one. */
+    getBabelTraceId(): string | null | undefined;
+}
+
+/** The wire envelope schema version this core implements (versioned independently of the package version). */
+declare const SCHEMA_VERSION = 1;
+/** Stamped into `meta.lang` for envelopes produced by this core. */
+declare const SOURCE_LANG = "node";
+/** Immutable per-message metadata. */
+interface Meta {
+    id: string;
+    queue: string;
+    lang: string;
+    schema_version: number;
+    /** Unix milliseconds, UTC. */
+    created_at: number;
+}
+/** The additive block appended to an envelope when a message is dead-lettered. */
+interface DeadLetter {
+    reason: string;
+    error: string | null;
+    exception: string | null;
+    /** Unix milliseconds, UTC. */
+    failed_at: number;
+    original_queue: string;
+    attempts: number;
+    lang: string;
+}
+/**
+ * The canonical BabelQueue wire message: a strict, language-neutral JSON shape
+ * that every SDK produces and consumes identically. The property order here is
+ * significant — it matches the other cores so {@link EnvelopeCodec.encode} is
+ * byte-for-byte identical across the insertion-order languages (PHP/Python).
+ */
+interface Envelope {
+    /** The message URN (never a class name). */
+    job: string;
+    /** Correlation id, preserved across every hop. */
+    trace_id: string;
+    /** The pure-JSON payload. */
+    data: Record<string, unknown>;
+    meta: Meta;
+    /** Top-level transport retry counter. */
+    attempts: number;
+    /** Present only once the message has been dead-lettered. */
+    dead_letter?: DeadLetter;
+}
+/**
+ * A decoded, not-yet-validated envelope. Fields are loosely typed because they
+ * come off the wire; `urn` is accepted as an inbound alias for `job`. Narrow it
+ * with {@link EnvelopeCodec.accepts} before trusting the contents.
+ */
+interface IncomingEnvelope {
+    job?: string;
+    /** Inbound alias for `job`. */
+    urn?: string;
+    trace_id?: string;
+    data?: unknown;
+    meta?: unknown;
+    attempts?: unknown;
+    dead_letter?: unknown;
+}
+/** Options for {@link EnvelopeCodec.make}. */
+interface MakeOptions {
+    /** Logical queue name recorded in `meta.queue` (default `"default"`). */
+    queue?: string;
+    /** Reuse an existing trace id (trace continuation) instead of minting one. */
+    traceId?: string;
+}
+/**
+ * Builds, encodes and decodes the canonical envelope — the single Node/TypeScript
+ * implementation of the wire format.
+ */
+declare const EnvelopeCodec: {
+    readonly SCHEMA_VERSION: 1;
+    readonly SOURCE_LANG: "node";
+    /**
+     * Build the canonical envelope for a `(urn, data)` pair. Mints a fresh trace id
+     * unless `options.traceId` is given, starts `attempts` at 0, and stamps `meta`.
+     * Throws {@link BabelQueueError} when the URN is blank.
+     */
+    readonly make: (urn: string, data: Record<string, unknown>, options?: MakeOptions) => Envelope;
+    /**
+     * Build the envelope from a {@link PolyglotMessage}. If the message also
+     * implements {@link HasTraceId} and returns a non-empty value, that trace id is
+     * reused.
+     */
+    readonly fromMessage: (message: PolyglotMessage & Partial<HasTraceId>, queue?: string) => Envelope;
+    /**
+     * Encode the envelope as compact UTF-8 JSON. `JSON.stringify` already emits the
+     * canonical form — no spaces, and slashes/unicode/HTML left unescaped — matching
+     * the other SDK cores.
+     */
+    readonly encode: (envelope: Envelope) => string;
+    /**
+     * Parse a raw JSON body. Returns `{}` for malformed or non-object input (call
+     * {@link EnvelopeCodec.accepts} before trusting it). Resolves the `urn` inbound
+     * alias into `job`.
+     */
+    readonly decode: (raw: string) => IncomingEnvelope;
+    /** The message URN — canonical `job`, with `urn` accepted as an alias. */
+    readonly urn: (envelope: IncomingEnvelope) => string;
+    /**
+     * Whether a consumer should accept this envelope. Rejects a missing URN, an
+     * unsupported `meta.schema_version`, a non-object `data`, a non-integer
+     * `attempts`, or a blank `trace_id` — the consumer-side counterpart to the
+     * producer JSON Schema. Acts as a type guard that narrows to {@link Envelope}.
+     */
+    readonly accepts: (envelope: IncomingEnvelope) => envelope is Envelope;
+};
+
+/**
+ * Optional idempotency helper (ADR-0022): dedupe a consume handler on `meta.id`.
+ *
+ * The Node mirror of the PHP `BabelQueue\Idempotency` and Go `idempotency` helpers.
+ * The core is codec-only (no dispatcher), so this wraps a user-provided handler that
+ * an adapter (NestJS, BullMQ, ...) drives:
+ *
+ * ```ts
+ * import { Wrap, InMemoryStore, type Handler } from "@babelqueue/core";
+ *
+ * const store = new InMemoryStore();
+ * const handler = Wrap(store, async (env) => {  ...  });
+ * ```
+ *
+ * A previously-seen id returns early (the adapter acks it); a throwing/rejecting
+ * handler leaves the id unmarked so a redelivery runs it again; a message with no
+ * usable `meta.id` runs unchanged. "Seen-set" post-success dedupe — not exactly-once,
+ * not in-flight concurrency locking (a transactional mode is a future direction).
+ */
+
+/** A consume handler: receives a decoded envelope, may be sync or async. */
+type Handler = (env: Envelope) => void | Promise<void>;
+/**
+ * A pluggable record of message ids already processed, keyed on `meta.id`. Methods may
+ * be sync or async so a production store can be Redis- or DB-backed; the reference
+ * {@link InMemoryStore} is synchronous.
+ */
+interface Store {
+    seen(messageId: string): boolean | Promise<boolean>;
+    remember(messageId: string): void | Promise<void>;
+    forget(messageId: string): void | Promise<void>;
+}
+/**
+ * Process-local {@link Store} backed by a Set. For tests / single-process consumers;
+ * not shared across workers and not persistent — use a Redis- or DB-backed store for
+ * production fleets.
+ */
+declare class InMemoryStore implements Store {
+    private readonly entries;
+    seen(messageId: string): boolean;
+    remember(messageId: string): void;
+    forget(messageId: string): void;
+}
+/**
+ * Wraps `handler` so a message whose `meta.id` was already processed successfully is
+ * skipped. A thrown/rejected handler leaves the id unmarked, so a redelivery runs it
+ * again (retry / dead-letter still apply); a message with no usable id runs unchanged.
+ */
+declare function Wrap(store: Store, handler: Handler): Handler;
+
+export { type DeadLetter as D, type Envelope as E, type Handler as H, InMemoryStore as I, type MakeOptions as M, type PolyglotMessage as P, SCHEMA_VERSION as S, Wrap as W, EnvelopeCodec as a, type HasTraceId as b, type IncomingEnvelope as c, type Meta as d, SOURCE_LANG as e, type Store as f };

package/dist/idempotency-DDHjGwF7.d.ts

@@ -0,0 +1,178 @@
+/**
+ * A message that can be produced as a polyglot envelope. Implement it on your
+ * own classes/objects so {@link EnvelopeCodec.fromMessage} can build the canonical
+ * envelope without ever leaking a language-specific class name onto the wire.
+ */
+interface PolyglotMessage {
+    /** The stable URN that identifies this message across languages. */
+    getBabelUrn(): string;
+    /** The pure-JSON payload (no class instances). */
+    toPayload(): Record<string, unknown>;
+}
+/**
+ * Optionally implemented alongside {@link PolyglotMessage} to continue an existing
+ * distributed trace instead of minting a fresh one.
+ */
+interface HasTraceId {
+    /** The trace id to reuse, or null/undefined to mint a new one. */
+    getBabelTraceId(): string | null | undefined;
+}
+
+/** The wire envelope schema version this core implements (versioned independently of the package version). */
+declare const SCHEMA_VERSION = 1;
+/** Stamped into `meta.lang` for envelopes produced by this core. */
+declare const SOURCE_LANG = "node";
+/** Immutable per-message metadata. */
+interface Meta {
+    id: string;
+    queue: string;
+    lang: string;
+    schema_version: number;
+    /** Unix milliseconds, UTC. */
+    created_at: number;
+}
+/** The additive block appended to an envelope when a message is dead-lettered. */
+interface DeadLetter {
+    reason: string;
+    error: string | null;
+    exception: string | null;
+    /** Unix milliseconds, UTC. */
+    failed_at: number;
+    original_queue: string;
+    attempts: number;
+    lang: string;
+}
+/**
+ * The canonical BabelQueue wire message: a strict, language-neutral JSON shape
+ * that every SDK produces and consumes identically. The property order here is
+ * significant — it matches the other cores so {@link EnvelopeCodec.encode} is
+ * byte-for-byte identical across the insertion-order languages (PHP/Python).
+ */
+interface Envelope {
+    /** The message URN (never a class name). */
+    job: string;
+    /** Correlation id, preserved across every hop. */
+    trace_id: string;
+    /** The pure-JSON payload. */
+    data: Record<string, unknown>;
+    meta: Meta;
+    /** Top-level transport retry counter. */
+    attempts: number;
+    /** Present only once the message has been dead-lettered. */
+    dead_letter?: DeadLetter;
+}
+/**
+ * A decoded, not-yet-validated envelope. Fields are loosely typed because they
+ * come off the wire; `urn` is accepted as an inbound alias for `job`. Narrow it
+ * with {@link EnvelopeCodec.accepts} before trusting the contents.
+ */
+interface IncomingEnvelope {
+    job?: string;
+    /** Inbound alias for `job`. */
+    urn?: string;
+    trace_id?: string;
+    data?: unknown;
+    meta?: unknown;
+    attempts?: unknown;
+    dead_letter?: unknown;
+}
+/** Options for {@link EnvelopeCodec.make}. */
+interface MakeOptions {
+    /** Logical queue name recorded in `meta.queue` (default `"default"`). */
+    queue?: string;
+    /** Reuse an existing trace id (trace continuation) instead of minting one. */
+    traceId?: string;
+}
+/**
+ * Builds, encodes and decodes the canonical envelope — the single Node/TypeScript
+ * implementation of the wire format.
+ */
+declare const EnvelopeCodec: {
+    readonly SCHEMA_VERSION: 1;
+    readonly SOURCE_LANG: "node";
+    /**
+     * Build the canonical envelope for a `(urn, data)` pair. Mints a fresh trace id
+     * unless `options.traceId` is given, starts `attempts` at 0, and stamps `meta`.
+     * Throws {@link BabelQueueError} when the URN is blank.
+     */
+    readonly make: (urn: string, data: Record<string, unknown>, options?: MakeOptions) => Envelope;
+    /**
+     * Build the envelope from a {@link PolyglotMessage}. If the message also
+     * implements {@link HasTraceId} and returns a non-empty value, that trace id is
+     * reused.
+     */
+    readonly fromMessage: (message: PolyglotMessage & Partial<HasTraceId>, queue?: string) => Envelope;
+    /**
+     * Encode the envelope as compact UTF-8 JSON. `JSON.stringify` already emits the
+     * canonical form — no spaces, and slashes/unicode/HTML left unescaped — matching
+     * the other SDK cores.
+     */
+    readonly encode: (envelope: Envelope) => string;
+    /**
+     * Parse a raw JSON body. Returns `{}` for malformed or non-object input (call
+     * {@link EnvelopeCodec.accepts} before trusting it). Resolves the `urn` inbound
+     * alias into `job`.
+     */
+    readonly decode: (raw: string) => IncomingEnvelope;
+    /** The message URN — canonical `job`, with `urn` accepted as an alias. */
+    readonly urn: (envelope: IncomingEnvelope) => string;
+    /**
+     * Whether a consumer should accept this envelope. Rejects a missing URN, an
+     * unsupported `meta.schema_version`, a non-object `data`, a non-integer
+     * `attempts`, or a blank `trace_id` — the consumer-side counterpart to the
+     * producer JSON Schema. Acts as a type guard that narrows to {@link Envelope}.
+     */
+    readonly accepts: (envelope: IncomingEnvelope) => envelope is Envelope;
+};
+
+/**
+ * Optional idempotency helper (ADR-0022): dedupe a consume handler on `meta.id`.
+ *
+ * The Node mirror of the PHP `BabelQueue\Idempotency` and Go `idempotency` helpers.
+ * The core is codec-only (no dispatcher), so this wraps a user-provided handler that
+ * an adapter (NestJS, BullMQ, ...) drives:
+ *
+ * ```ts
+ * import { Wrap, InMemoryStore, type Handler } from "@babelqueue/core";
+ *
+ * const store = new InMemoryStore();
+ * const handler = Wrap(store, async (env) => {  ...  });
+ * ```
+ *
+ * A previously-seen id returns early (the adapter acks it); a throwing/rejecting
+ * handler leaves the id unmarked so a redelivery runs it again; a message with no
+ * usable `meta.id` runs unchanged. "Seen-set" post-success dedupe — not exactly-once,
+ * not in-flight concurrency locking (a transactional mode is a future direction).
+ */
+
+/** A consume handler: receives a decoded envelope, may be sync or async. */
+type Handler = (env: Envelope) => void | Promise<void>;
+/**
+ * A pluggable record of message ids already processed, keyed on `meta.id`. Methods may
+ * be sync or async so a production store can be Redis- or DB-backed; the reference
+ * {@link InMemoryStore} is synchronous.
+ */
+interface Store {
+    seen(messageId: string): boolean | Promise<boolean>;
+    remember(messageId: string): void | Promise<void>;
+    forget(messageId: string): void | Promise<void>;
+}
+/**
+ * Process-local {@link Store} backed by a Set. For tests / single-process consumers;
+ * not shared across workers and not persistent — use a Redis- or DB-backed store for
+ * production fleets.
+ */
+declare class InMemoryStore implements Store {
+    private readonly entries;
+    seen(messageId: string): boolean;
+    remember(messageId: string): void;
+    forget(messageId: string): void;
+}
+/**
+ * Wraps `handler` so a message whose `meta.id` was already processed successfully is
+ * skipped. A thrown/rejected handler leaves the id unmarked, so a redelivery runs it
+ * again (retry / dead-letter still apply); a message with no usable id runs unchanged.
+ */
+declare function Wrap(store: Store, handler: Handler): Handler;
+
+export { type DeadLetter as D, type Envelope as E, type Handler as H, InMemoryStore as I, type MakeOptions as M, type PolyglotMessage as P, SCHEMA_VERSION as S, Wrap as W, EnvelopeCodec as a, type HasTraceId as b, type IncomingEnvelope as c, type Meta as d, SOURCE_LANG as e, type Store as f };