@babelqueue/pulsar 1.0.0

package/README.md

@@ -0,0 +1,81 @@
+# @babelqueue/pulsar
+
+Apache Pulsar adapter for [BabelQueue](https://babelqueue.com) — a canonical-envelope
+**publisher** and a URN-routed **consumer** over `pulsar-client`, on `@babelqueue/core`.
+Implements
+[§5 of the broker-bindings contract](https://babelqueue.com/docs/spec/1.x/broker-bindings#apache-pulsar),
+so a Pulsar-based Node service speaks the same wire contract as the .NET, Java, Python and Go
+SDKs.
+
+## Install
+
+```bash
+npm i @babelqueue/pulsar pulsar-client
+```
+
+`pulsar-client` is an optional peer — **you provide the producer/consumer** (a `Producer` /
+`Consumer` from `pulsar-client` satisfies the adapter structurally).
+
+## Use
+
+```ts
+import Pulsar from "pulsar-client";
+import { PulsarPublisher, PulsarConsumer } from "@babelqueue/pulsar";
+
+const client = new Pulsar.Client({ serviceUrl: "pulsar://localhost:6650" });
+
+// produce
+const producer = await client.createProducer({ topic: "orders" });
+const id = await new PulsarPublisher(producer)
+  .publish("urn:babel:orders:created", { order_id: 1042 });
+
+// consume (Shared subscription)
+const sub = await client.subscribe({
+  topic: "orders",
+  subscription: "babelqueue",
+  subscriptionType: "Shared",
+});
+const consumer = new PulsarConsumer(
+  sub,
+  {
+    "urn:babel:orders:created": async (env, message) => {
+      console.log(env.data.order_id, env.trace_id, env.attempts);
+    },
+  },
+  { onError: (err) => console.error(err) },
+);
+await consumer.run();
+```
+
+Delayed delivery: `publish(urn, data, { delayMs: 300000 })` → native `deliverAfter`. The
+consumer routes purely on the `bq-job` property.
+
+## Contract mapping (§5)
+
+| Envelope | Apache Pulsar |
+| :--- | :--- |
+| body | message payload (byte-identical across SDKs) |
+| `job` (URN) | property `bq-job` (consumer routes on this) |
+| `trace_id` | property `bq-trace-id` |
+| `meta.id` | property `bq-message-id` |
+| `meta.schema_version` | property `bq-schema-version` |
+| `meta.lang` | property `bq-source-lang` |
+| `meta.created_at` | publish time (mirror; body authoritative) |
+| `attempts` | property `bq-attempts` (authoritative), cross-checked against `getRedeliveryCount()` |
+| reserve / ack / retry | `acknowledge` / `negativeAcknowledge` |
+
+Pulsar properties are string→string, so `bq-attempts` carries the contract `attempts` and is
+**authoritative**. The consumer reconciles to `max(bq-attempts, getRedeliveryCount())`:
+`getRedeliveryCount()` is 0-based (0 on first delivery) so it maps directly with **no −1**,
+and the `max` never lowers a higher body count — so a republish-driven retry and a native
+redelivery both converge on the same number. A throwing handler `negativeAcknowledge`s, so
+the broker redelivers (at-least-once). The poll loop never stops on a bad message — observe
+via `onError` / `onUnknownUrn`. The envelope is unchanged (`schema_version` stays `1`);
+Pulsar is purely additive.
+
+The producer/consumer are injected, so the unit tests use fakes — no Pulsar, no broker. Dual
+ESM + CJS.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,154 @@
+"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, {
+  PulsarConsumer: () => PulsarConsumer,
+  PulsarPublisher: () => PulsarPublisher,
+  pulsarProperties: () => pulsarProperties,
+  toPulsarMessage: () => toPulsarMessage
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@babelqueue/core");
+function topicName(topic) {
+  const slash = topic.lastIndexOf("/");
+  return slash >= 0 ? topic.slice(slash + 1) : topic;
+}
+function pulsarProperties(envelope) {
+  const properties = {};
+  if (envelope.job) properties["bq-job"] = envelope.job;
+  if (envelope.trace_id) properties["bq-trace-id"] = envelope.trace_id;
+  if (envelope.meta.id) properties["bq-message-id"] = envelope.meta.id;
+  if (envelope.meta.schema_version != null) {
+    properties["bq-schema-version"] = String(envelope.meta.schema_version);
+  }
+  if (envelope.meta.lang) properties["bq-source-lang"] = envelope.meta.lang;
+  properties["bq-attempts"] = String(envelope.attempts ?? 0);
+  return properties;
+}
+function toPulsarMessage(envelope) {
+  return {
+    data: Buffer.from(import_core.EnvelopeCodec.encode(envelope), "utf8"),
+    properties: pulsarProperties(envelope)
+  };
+}
+var PulsarPublisher = class {
+  constructor(producer) {
+    this.producer = producer;
+  }
+  producer;
+  /**
+   * Build the canonical envelope for `(urn, data)`, send it with the §5 property projection,
+   * and return the message id (`meta.id`). A positive `delayMs` schedules native delayed
+   * delivery via `deliverAfter` and mirrors `bq-delay`.
+   */
+  async publish(urn, data, options = {}) {
+    const envelope = import_core.EnvelopeCodec.make(urn, data, {
+      queue: topicName(this.producer.getTopic()),
+      traceId: options.traceId
+    });
+    const message = toPulsarMessage(envelope);
+    if (options.delayMs != null && options.delayMs > 0) {
+      message.properties = { ...message.properties, "bq-delay": String(options.delayMs) };
+      message.deliverAfter = options.delayMs;
+    }
+    await this.producer.send(message);
+    return envelope.meta.id;
+  }
+};
+function isReceiveTimeout(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return /timeout/i.test(message);
+}
+function decodePayload(data) {
+  return typeof data === "string" ? data : data.toString("utf8");
+}
+var PulsarConsumer = class {
+  constructor(consumer, handlers, options = {}) {
+    this.consumer = consumer;
+    this.handlers = handlers;
+    this.options = options;
+  }
+  consumer;
+  handlers;
+  options;
+  /** Receive one message (up to the receive timeout), route + settle it. Returns 1, or 0 on timeout. */
+  async poll() {
+    let message;
+    try {
+      message = await this.consumer.receive(this.options.receiveTimeoutMs ?? 1e3);
+    } catch (error) {
+      if (isReceiveTimeout(error)) return 0;
+      throw error;
+    }
+    await this.handle(message);
+    return 1;
+  }
+  /** Poll until `signal` aborts. */
+  async run(signal) {
+    while (signal?.aborted !== true) {
+      await this.poll();
+    }
+  }
+  async handle(message) {
+    const envelope = import_core.EnvelopeCodec.decode(decodePayload(message.getData()));
+    const redeliveryCount = typeof message.getRedeliveryCount === "function" ? message.getRedeliveryCount() : 0;
+    const current = typeof envelope.attempts === "number" ? envelope.attempts : 0;
+    if (redeliveryCount > current) {
+      envelope.attempts = redeliveryCount;
+    }
+    if (!import_core.EnvelopeCodec.accepts(envelope)) {
+      this.options.onError?.(
+        new import_core.BabelQueueError("Rejected a non-conformant BabelQueue envelope from Apache Pulsar."),
+        envelope,
+        message
+      );
+      await this.consumer.negativeAcknowledge(message);
+      return;
+    }
+    const urn = import_core.EnvelopeCodec.urn(envelope);
+    const handler = this.handlers[urn];
+    if (!handler) {
+      if (this.options.onUnknownUrn) {
+        await this.options.onUnknownUrn(envelope, message);
+        await this.consumer.acknowledge(message);
+      } else {
+        this.options.onError?.(new import_core.UnknownUrnError(urn), envelope, message);
+        await this.consumer.negativeAcknowledge(message);
+      }
+      return;
+    }
+    try {
+      await handler(envelope, message);
+      await this.consumer.acknowledge(message);
+    } catch (error) {
+      this.options.onError?.(error, envelope, message);
+      await this.consumer.negativeAcknowledge(message);
+    }
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  PulsarConsumer,
+  PulsarPublisher,
+  pulsarProperties,
+  toPulsarMessage
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Apache Pulsar adapter for BabelQueue.\n *\n * A canonical-envelope **publisher** and a URN-routed **consumer** over Apache Pulsar, so a\n * Pulsar-based Node service speaks the same contract (envelope shape, URN identity, trace\n * propagation) as the .NET, Java, Python and Go SDKs.\n *\n *     import Pulsar from \"pulsar-client\";\n *     import { PulsarPublisher, PulsarConsumer } from \"@babelqueue/pulsar\";\n *\n *     const client = new Pulsar.Client({ serviceUrl: \"pulsar://localhost:6650\" });\n *\n *     const producer = await client.createProducer({ topic: \"orders\" });\n *     await new PulsarPublisher(producer).publish(\"urn:babel:orders:created\", { order_id: 1042 });\n *\n *     const sub = await client.subscribe({\n *       topic: \"orders\", subscription: \"babelqueue\", subscriptionType: \"Shared\",\n *     });\n *     const consumer = new PulsarConsumer(sub, {\n *       \"urn:babel:orders:created\": async (env) => { ... },\n *     });\n *     await consumer.run();\n *\n * This implements §5 of the broker-bindings contract: the canonical envelope is the message\n * payload, projected onto native Pulsar message properties (string→string) — `bq-job` = URN,\n * `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus `bq-schema-version` /\n * `bq-source-lang` / `bq-attempts`. The envelope is unchanged (`schema_version` stays 1);\n * Pulsar is purely additive. A failed handler `negativeAcknowledge`s the message, so it is\n * redelivered (at-least-once) and `getRedeliveryCount()` is incremented; the authoritative\n * attempt count is the body's `bq-attempts`, reconciled to `max(bq-attempts,\n * getRedeliveryCount())` — no −1, because Pulsar's redelivery count is 0-based.\n */\n\nimport { BabelQueueError, EnvelopeCodec, UnknownUrnError } from \"@babelqueue/core\";\nimport type { Envelope, IncomingEnvelope } from \"@babelqueue/core\";\n\n// --- Minimal Pulsar shapes (a structural subset of pulsar-client) --------------\n\n/** A message to send (structural subset of pulsar-client `ProducerMessage`). */\nexport interface PulsarProducerMessage {\n  data: Buffer;\n  properties?: { [key: string]: string };\n  /** Relative delay in milliseconds before the message becomes available (native `deliverAfter`). */\n  deliverAfter?: number;\n}\n\n/**\n * The subset of the Pulsar producer this adapter calls. A `Producer` from `pulsar-client`\n * satisfies it structurally; a fake satisfies it in tests.\n */\nexport interface PulsarProducer {\n  getTopic(): string;\n  send(message: PulsarProducerMessage): Promise<unknown>;\n}\n\n/** A received message (structural subset of pulsar-client `Message`). */\nexport interface PulsarReceivedMessage {\n  getData(): Buffer | string;\n  getProperties(): { [key: string]: string };\n  getRedeliveryCount(): number;\n}\n\n/**\n * The subset of the Pulsar consumer this adapter calls. A `Consumer` from `pulsar-client`\n * satisfies it structurally; a fake satisfies it in tests.\n */\nexport interface PulsarConsumerClient {\n  receive(timeoutMs?: number): Promise<PulsarReceivedMessage>;\n  acknowledge(message: PulsarReceivedMessage): Promise<void> | void;\n  negativeAcknowledge(message: PulsarReceivedMessage): Promise<void> | void;\n}\n\n// --- Property projection (contract §5.2) ---------------------------------------\n\n/** Bare topic name (the part after the last `/`), used as `meta.queue`. */\nfunction topicName(topic: string): string {\n  const slash = topic.lastIndexOf(\"/\");\n  return slash >= 0 ? topic.slice(slash + 1) : topic;\n}\n\n/**\n * Project the envelope's contract fields onto native Pulsar message properties\n * (string→string): `bq-job` = URN, `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus\n * `bq-schema-version` / `bq-source-lang` / `bq-attempts`. The body stays authoritative.\n */\nexport function pulsarProperties(envelope: Envelope): { [key: string]: string } {\n  const properties: { [key: string]: string } = {};\n  if (envelope.job) properties[\"bq-job\"] = envelope.job;\n  if (envelope.trace_id) properties[\"bq-trace-id\"] = envelope.trace_id;\n  if (envelope.meta.id) properties[\"bq-message-id\"] = envelope.meta.id;\n  if (envelope.meta.schema_version != null) {\n    properties[\"bq-schema-version\"] = String(envelope.meta.schema_version);\n  }\n  if (envelope.meta.lang) properties[\"bq-source-lang\"] = envelope.meta.lang;\n  properties[\"bq-attempts\"] = String(envelope.attempts ?? 0);\n  return properties;\n}\n\n/** Project the envelope onto a native Pulsar producer message (payload + properties). */\nexport function toPulsarMessage(envelope: Envelope): PulsarProducerMessage {\n  return {\n    data: Buffer.from(EnvelopeCodec.encode(envelope), \"utf8\"),\n    properties: pulsarProperties(envelope),\n  };\n}\n\n// --- Publisher -----------------------------------------------------------------\n\n/** Options for {@link PulsarPublisher.publish}. */\nexport interface PublishOptions {\n  /** Reuse an existing trace id (trace continuation). */\n  traceId?: string;\n  /** Schedule native delayed delivery this many milliseconds from now (`deliverAfter`). */\n  delayMs?: number;\n}\n\n/** Sends canonical-envelope messages to one Pulsar topic with the §5 property projection. */\nexport class PulsarPublisher {\n  constructor(private readonly producer: PulsarProducer) {}\n\n  /**\n   * Build the canonical envelope for `(urn, data)`, send it with the §5 property projection,\n   * and return the message id (`meta.id`). A positive `delayMs` schedules native delayed\n   * delivery via `deliverAfter` and mirrors `bq-delay`.\n   */\n  async publish(\n    urn: string,\n    data: Record<string, unknown>,\n    options: PublishOptions = {},\n  ): Promise<string> {\n    const envelope = EnvelopeCodec.make(urn, data, {\n      queue: topicName(this.producer.getTopic()),\n      traceId: options.traceId,\n    });\n    const message = toPulsarMessage(envelope);\n\n    if (options.delayMs != null && options.delayMs > 0) {\n      message.properties = { ...message.properties, \"bq-delay\": String(options.delayMs) };\n      message.deliverAfter = options.delayMs;\n    }\n\n    await this.producer.send(message);\n    return envelope.meta.id;\n  }\n}\n\n// --- Consumer ------------------------------------------------------------------\n\n/** A URN handler. Receives the validated envelope and the raw Pulsar message. */\nexport type BabelHandler = (envelope: Envelope, message: PulsarReceivedMessage) => unknown | Promise<unknown>;\n\n/** A map of URN → handler. */\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/** Options for {@link PulsarConsumer}. */\nexport interface PulsarConsumerOptions {\n  /** Called instead of erroring when a message's URN has no handler (then the message is acknowledged). */\n  onUnknownUrn?: (envelope: IncomingEnvelope, message: PulsarReceivedMessage) => unknown | Promise<unknown>;\n  /** Called for a non-conformant envelope, an unmapped URN (no `onUnknownUrn`), or a throwing handler. The loop never stops. */\n  onError?: (error: unknown, envelope: IncomingEnvelope, message: PulsarReceivedMessage) => void;\n  /** Per-receive timeout in ms (default 1000). A timeout yields an empty poll, not an error. */\n  receiveTimeoutMs?: number;\n}\n\nfunction isReceiveTimeout(error: unknown): boolean {\n  const message = error instanceof Error ? error.message : String(error);\n  return /timeout/i.test(message);\n}\n\nfunction decodePayload(data: Buffer | string): string {\n  return typeof data === \"string\" ? data : data.toString(\"utf8\");\n}\n\n/**\n * Receives from a Pulsar subscription, decodes + validates each message, routes it to the\n * handler for its URN, and acknowledges it on success. A throwing handler\n * `negativeAcknowledge`s the message — the broker redelivers it and increments\n * `getRedeliveryCount()` (at-least-once); `attempts` is reconciled to\n * `max(bq-attempts, getRedeliveryCount())` for the handler.\n */\nexport class PulsarConsumer {\n  constructor(\n    private readonly consumer: PulsarConsumerClient,\n    private readonly handlers: BabelHandlers,\n    private readonly options: PulsarConsumerOptions = {},\n  ) {}\n\n  /** Receive one message (up to the receive timeout), route + settle it. Returns 1, or 0 on timeout. */\n  async poll(): Promise<number> {\n    let message: PulsarReceivedMessage;\n    try {\n      message = await this.consumer.receive(this.options.receiveTimeoutMs ?? 1000);\n    } catch (error) {\n      if (isReceiveTimeout(error)) return 0;\n      throw error;\n    }\n    await this.handle(message);\n    return 1;\n  }\n\n  /** Poll until `signal` aborts. */\n  async run(signal?: AbortSignal): Promise<void> {\n    while (signal?.aborted !== true) {\n      await this.poll();\n    }\n  }\n\n  private async handle(message: PulsarReceivedMessage): Promise<void> {\n    const envelope = EnvelopeCodec.decode(decodePayload(message.getData()));\n\n    // attempts = max(current, getRedeliveryCount()): the redelivery count is 0-based, so it\n    // maps directly with no −1; the max never lowers a higher body count republished from\n    // another SDK (the Go/Python transports retry by re-sending with attempts+1).\n    const redeliveryCount = typeof message.getRedeliveryCount === \"function\" ? message.getRedeliveryCount() : 0;\n    const current = typeof envelope.attempts === \"number\" ? envelope.attempts : 0;\n    if (redeliveryCount > current) {\n      envelope.attempts = redeliveryCount;\n    }\n\n    if (!EnvelopeCodec.accepts(envelope)) {\n      this.options.onError?.(\n        new BabelQueueError(\"Rejected a non-conformant BabelQueue envelope from Apache Pulsar.\"),\n        envelope,\n        message,\n      );\n      await this.consumer.negativeAcknowledge(message);\n      return;\n    }\n\n    const urn = EnvelopeCodec.urn(envelope);\n    const handler = this.handlers[urn];\n    if (!handler) {\n      if (this.options.onUnknownUrn) {\n        await this.options.onUnknownUrn(envelope, message);\n        await this.consumer.acknowledge(message);\n      } else {\n        this.options.onError?.(new UnknownUrnError(urn), envelope, message);\n        await this.consumer.negativeAcknowledge(message);\n      }\n      return;\n    }\n\n    try {\n      await handler(envelope as Envelope, message);\n      await this.consumer.acknowledge(message);\n    } catch (error) {\n      // Negative-ack releases the message — the broker redelivers and increments the count.\n      this.options.onError?.(error, envelope, message);\n      await this.consumer.negativeAcknowledge(message);\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,130 @@
+import { Envelope, IncomingEnvelope } from '@babelqueue/core';
+
+/**
+ * Apache Pulsar adapter for BabelQueue.
+ *
+ * A canonical-envelope **publisher** and a URN-routed **consumer** over Apache Pulsar, so a
+ * Pulsar-based Node service speaks the same contract (envelope shape, URN identity, trace
+ * propagation) as the .NET, Java, Python and Go SDKs.
+ *
+ *     import Pulsar from "pulsar-client";
+ *     import { PulsarPublisher, PulsarConsumer } from "@babelqueue/pulsar";
+ *
+ *     const client = new Pulsar.Client({ serviceUrl: "pulsar://localhost:6650" });
+ *
+ *     const producer = await client.createProducer({ topic: "orders" });
+ *     await new PulsarPublisher(producer).publish("urn:babel:orders:created", { order_id: 1042 });
+ *
+ *     const sub = await client.subscribe({
+ *       topic: "orders", subscription: "babelqueue", subscriptionType: "Shared",
+ *     });
+ *     const consumer = new PulsarConsumer(sub, {
+ *       "urn:babel:orders:created": async (env) => { ... },
+ *     });
+ *     await consumer.run();
+ *
+ * This implements §5 of the broker-bindings contract: the canonical envelope is the message
+ * payload, projected onto native Pulsar message properties (string→string) — `bq-job` = URN,
+ * `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus `bq-schema-version` /
+ * `bq-source-lang` / `bq-attempts`. The envelope is unchanged (`schema_version` stays 1);
+ * Pulsar is purely additive. A failed handler `negativeAcknowledge`s the message, so it is
+ * redelivered (at-least-once) and `getRedeliveryCount()` is incremented; the authoritative
+ * attempt count is the body's `bq-attempts`, reconciled to `max(bq-attempts,
+ * getRedeliveryCount())` — no −1, because Pulsar's redelivery count is 0-based.
+ */
+
+/** A message to send (structural subset of pulsar-client `ProducerMessage`). */
+interface PulsarProducerMessage {
+    data: Buffer;
+    properties?: {
+        [key: string]: string;
+    };
+    /** Relative delay in milliseconds before the message becomes available (native `deliverAfter`). */
+    deliverAfter?: number;
+}
+/**
+ * The subset of the Pulsar producer this adapter calls. A `Producer` from `pulsar-client`
+ * satisfies it structurally; a fake satisfies it in tests.
+ */
+interface PulsarProducer {
+    getTopic(): string;
+    send(message: PulsarProducerMessage): Promise<unknown>;
+}
+/** A received message (structural subset of pulsar-client `Message`). */
+interface PulsarReceivedMessage {
+    getData(): Buffer | string;
+    getProperties(): {
+        [key: string]: string;
+    };
+    getRedeliveryCount(): number;
+}
+/**
+ * The subset of the Pulsar consumer this adapter calls. A `Consumer` from `pulsar-client`
+ * satisfies it structurally; a fake satisfies it in tests.
+ */
+interface PulsarConsumerClient {
+    receive(timeoutMs?: number): Promise<PulsarReceivedMessage>;
+    acknowledge(message: PulsarReceivedMessage): Promise<void> | void;
+    negativeAcknowledge(message: PulsarReceivedMessage): Promise<void> | void;
+}
+/**
+ * Project the envelope's contract fields onto native Pulsar message properties
+ * (string→string): `bq-job` = URN, `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus
+ * `bq-schema-version` / `bq-source-lang` / `bq-attempts`. The body stays authoritative.
+ */
+declare function pulsarProperties(envelope: Envelope): {
+    [key: string]: string;
+};
+/** Project the envelope onto a native Pulsar producer message (payload + properties). */
+declare function toPulsarMessage(envelope: Envelope): PulsarProducerMessage;
+/** Options for {@link PulsarPublisher.publish}. */
+interface PublishOptions {
+    /** Reuse an existing trace id (trace continuation). */
+    traceId?: string;
+    /** Schedule native delayed delivery this many milliseconds from now (`deliverAfter`). */
+    delayMs?: number;
+}
+/** Sends canonical-envelope messages to one Pulsar topic with the §5 property projection. */
+declare class PulsarPublisher {
+    private readonly producer;
+    constructor(producer: PulsarProducer);
+    /**
+     * Build the canonical envelope for `(urn, data)`, send it with the §5 property projection,
+     * and return the message id (`meta.id`). A positive `delayMs` schedules native delayed
+     * delivery via `deliverAfter` and mirrors `bq-delay`.
+     */
+    publish(urn: string, data: Record<string, unknown>, options?: PublishOptions): Promise<string>;
+}
+/** A URN handler. Receives the validated envelope and the raw Pulsar message. */
+type BabelHandler = (envelope: Envelope, message: PulsarReceivedMessage) => unknown | Promise<unknown>;
+/** A map of URN → handler. */
+type BabelHandlers = Record<string, BabelHandler>;
+/** Options for {@link PulsarConsumer}. */
+interface PulsarConsumerOptions {
+    /** Called instead of erroring when a message's URN has no handler (then the message is acknowledged). */
+    onUnknownUrn?: (envelope: IncomingEnvelope, message: PulsarReceivedMessage) => unknown | Promise<unknown>;
+    /** Called for a non-conformant envelope, an unmapped URN (no `onUnknownUrn`), or a throwing handler. The loop never stops. */
+    onError?: (error: unknown, envelope: IncomingEnvelope, message: PulsarReceivedMessage) => void;
+    /** Per-receive timeout in ms (default 1000). A timeout yields an empty poll, not an error. */
+    receiveTimeoutMs?: number;
+}
+/**
+ * Receives from a Pulsar subscription, decodes + validates each message, routes it to the
+ * handler for its URN, and acknowledges it on success. A throwing handler
+ * `negativeAcknowledge`s the message — the broker redelivers it and increments
+ * `getRedeliveryCount()` (at-least-once); `attempts` is reconciled to
+ * `max(bq-attempts, getRedeliveryCount())` for the handler.
+ */
+declare class PulsarConsumer {
+    private readonly consumer;
+    private readonly handlers;
+    private readonly options;
+    constructor(consumer: PulsarConsumerClient, handlers: BabelHandlers, options?: PulsarConsumerOptions);
+    /** Receive one message (up to the receive timeout), route + settle it. Returns 1, or 0 on timeout. */
+    poll(): Promise<number>;
+    /** Poll until `signal` aborts. */
+    run(signal?: AbortSignal): Promise<void>;
+    private handle;
+}
+
+export { type BabelHandler, type BabelHandlers, type PublishOptions, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, pulsarProperties, toPulsarMessage };

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+import { Envelope, IncomingEnvelope } from '@babelqueue/core';
+
+/**
+ * Apache Pulsar adapter for BabelQueue.
+ *
+ * A canonical-envelope **publisher** and a URN-routed **consumer** over Apache Pulsar, so a
+ * Pulsar-based Node service speaks the same contract (envelope shape, URN identity, trace
+ * propagation) as the .NET, Java, Python and Go SDKs.
+ *
+ *     import Pulsar from "pulsar-client";
+ *     import { PulsarPublisher, PulsarConsumer } from "@babelqueue/pulsar";
+ *
+ *     const client = new Pulsar.Client({ serviceUrl: "pulsar://localhost:6650" });
+ *
+ *     const producer = await client.createProducer({ topic: "orders" });
+ *     await new PulsarPublisher(producer).publish("urn:babel:orders:created", { order_id: 1042 });
+ *
+ *     const sub = await client.subscribe({
+ *       topic: "orders", subscription: "babelqueue", subscriptionType: "Shared",
+ *     });
+ *     const consumer = new PulsarConsumer(sub, {
+ *       "urn:babel:orders:created": async (env) => { ... },
+ *     });
+ *     await consumer.run();
+ *
+ * This implements §5 of the broker-bindings contract: the canonical envelope is the message
+ * payload, projected onto native Pulsar message properties (string→string) — `bq-job` = URN,
+ * `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus `bq-schema-version` /
+ * `bq-source-lang` / `bq-attempts`. The envelope is unchanged (`schema_version` stays 1);
+ * Pulsar is purely additive. A failed handler `negativeAcknowledge`s the message, so it is
+ * redelivered (at-least-once) and `getRedeliveryCount()` is incremented; the authoritative
+ * attempt count is the body's `bq-attempts`, reconciled to `max(bq-attempts,
+ * getRedeliveryCount())` — no −1, because Pulsar's redelivery count is 0-based.
+ */
+
+/** A message to send (structural subset of pulsar-client `ProducerMessage`). */
+interface PulsarProducerMessage {
+    data: Buffer;
+    properties?: {
+        [key: string]: string;
+    };
+    /** Relative delay in milliseconds before the message becomes available (native `deliverAfter`). */
+    deliverAfter?: number;
+}
+/**
+ * The subset of the Pulsar producer this adapter calls. A `Producer` from `pulsar-client`
+ * satisfies it structurally; a fake satisfies it in tests.
+ */
+interface PulsarProducer {
+    getTopic(): string;
+    send(message: PulsarProducerMessage): Promise<unknown>;
+}
+/** A received message (structural subset of pulsar-client `Message`). */
+interface PulsarReceivedMessage {
+    getData(): Buffer | string;
+    getProperties(): {
+        [key: string]: string;
+    };
+    getRedeliveryCount(): number;
+}
+/**
+ * The subset of the Pulsar consumer this adapter calls. A `Consumer` from `pulsar-client`
+ * satisfies it structurally; a fake satisfies it in tests.
+ */
+interface PulsarConsumerClient {
+    receive(timeoutMs?: number): Promise<PulsarReceivedMessage>;
+    acknowledge(message: PulsarReceivedMessage): Promise<void> | void;
+    negativeAcknowledge(message: PulsarReceivedMessage): Promise<void> | void;
+}
+/**
+ * Project the envelope's contract fields onto native Pulsar message properties
+ * (string→string): `bq-job` = URN, `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus
+ * `bq-schema-version` / `bq-source-lang` / `bq-attempts`. The body stays authoritative.
+ */
+declare function pulsarProperties(envelope: Envelope): {
+    [key: string]: string;
+};
+/** Project the envelope onto a native Pulsar producer message (payload + properties). */
+declare function toPulsarMessage(envelope: Envelope): PulsarProducerMessage;
+/** Options for {@link PulsarPublisher.publish}. */
+interface PublishOptions {
+    /** Reuse an existing trace id (trace continuation). */
+    traceId?: string;
+    /** Schedule native delayed delivery this many milliseconds from now (`deliverAfter`). */
+    delayMs?: number;
+}
+/** Sends canonical-envelope messages to one Pulsar topic with the §5 property projection. */
+declare class PulsarPublisher {
+    private readonly producer;
+    constructor(producer: PulsarProducer);
+    /**
+     * Build the canonical envelope for `(urn, data)`, send it with the §5 property projection,
+     * and return the message id (`meta.id`). A positive `delayMs` schedules native delayed
+     * delivery via `deliverAfter` and mirrors `bq-delay`.
+     */
+    publish(urn: string, data: Record<string, unknown>, options?: PublishOptions): Promise<string>;
+}
+/** A URN handler. Receives the validated envelope and the raw Pulsar message. */
+type BabelHandler = (envelope: Envelope, message: PulsarReceivedMessage) => unknown | Promise<unknown>;
+/** A map of URN → handler. */
+type BabelHandlers = Record<string, BabelHandler>;
+/** Options for {@link PulsarConsumer}. */
+interface PulsarConsumerOptions {
+    /** Called instead of erroring when a message's URN has no handler (then the message is acknowledged). */
+    onUnknownUrn?: (envelope: IncomingEnvelope, message: PulsarReceivedMessage) => unknown | Promise<unknown>;
+    /** Called for a non-conformant envelope, an unmapped URN (no `onUnknownUrn`), or a throwing handler. The loop never stops. */
+    onError?: (error: unknown, envelope: IncomingEnvelope, message: PulsarReceivedMessage) => void;
+    /** Per-receive timeout in ms (default 1000). A timeout yields an empty poll, not an error. */
+    receiveTimeoutMs?: number;
+}
+/**
+ * Receives from a Pulsar subscription, decodes + validates each message, routes it to the
+ * handler for its URN, and acknowledges it on success. A throwing handler
+ * `negativeAcknowledge`s the message — the broker redelivers it and increments
+ * `getRedeliveryCount()` (at-least-once); `attempts` is reconciled to
+ * `max(bq-attempts, getRedeliveryCount())` for the handler.
+ */
+declare class PulsarConsumer {
+    private readonly consumer;
+    private readonly handlers;
+    private readonly options;
+    constructor(consumer: PulsarConsumerClient, handlers: BabelHandlers, options?: PulsarConsumerOptions);
+    /** Receive one message (up to the receive timeout), route + settle it. Returns 1, or 0 on timeout. */
+    poll(): Promise<number>;
+    /** Poll until `signal` aborts. */
+    run(signal?: AbortSignal): Promise<void>;
+    private handle;
+}
+
+export { type BabelHandler, type BabelHandlers, type PublishOptions, PulsarConsumer, type PulsarConsumerClient, type PulsarConsumerOptions, type PulsarProducer, type PulsarProducerMessage, PulsarPublisher, type PulsarReceivedMessage, pulsarProperties, toPulsarMessage };

package/dist/index.js

@@ -0,0 +1,126 @@
+// src/index.ts
+import { BabelQueueError, EnvelopeCodec, UnknownUrnError } from "@babelqueue/core";
+function topicName(topic) {
+  const slash = topic.lastIndexOf("/");
+  return slash >= 0 ? topic.slice(slash + 1) : topic;
+}
+function pulsarProperties(envelope) {
+  const properties = {};
+  if (envelope.job) properties["bq-job"] = envelope.job;
+  if (envelope.trace_id) properties["bq-trace-id"] = envelope.trace_id;
+  if (envelope.meta.id) properties["bq-message-id"] = envelope.meta.id;
+  if (envelope.meta.schema_version != null) {
+    properties["bq-schema-version"] = String(envelope.meta.schema_version);
+  }
+  if (envelope.meta.lang) properties["bq-source-lang"] = envelope.meta.lang;
+  properties["bq-attempts"] = String(envelope.attempts ?? 0);
+  return properties;
+}
+function toPulsarMessage(envelope) {
+  return {
+    data: Buffer.from(EnvelopeCodec.encode(envelope), "utf8"),
+    properties: pulsarProperties(envelope)
+  };
+}
+var PulsarPublisher = class {
+  constructor(producer) {
+    this.producer = producer;
+  }
+  producer;
+  /**
+   * Build the canonical envelope for `(urn, data)`, send it with the §5 property projection,
+   * and return the message id (`meta.id`). A positive `delayMs` schedules native delayed
+   * delivery via `deliverAfter` and mirrors `bq-delay`.
+   */
+  async publish(urn, data, options = {}) {
+    const envelope = EnvelopeCodec.make(urn, data, {
+      queue: topicName(this.producer.getTopic()),
+      traceId: options.traceId
+    });
+    const message = toPulsarMessage(envelope);
+    if (options.delayMs != null && options.delayMs > 0) {
+      message.properties = { ...message.properties, "bq-delay": String(options.delayMs) };
+      message.deliverAfter = options.delayMs;
+    }
+    await this.producer.send(message);
+    return envelope.meta.id;
+  }
+};
+function isReceiveTimeout(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return /timeout/i.test(message);
+}
+function decodePayload(data) {
+  return typeof data === "string" ? data : data.toString("utf8");
+}
+var PulsarConsumer = class {
+  constructor(consumer, handlers, options = {}) {
+    this.consumer = consumer;
+    this.handlers = handlers;
+    this.options = options;
+  }
+  consumer;
+  handlers;
+  options;
+  /** Receive one message (up to the receive timeout), route + settle it. Returns 1, or 0 on timeout. */
+  async poll() {
+    let message;
+    try {
+      message = await this.consumer.receive(this.options.receiveTimeoutMs ?? 1e3);
+    } catch (error) {
+      if (isReceiveTimeout(error)) return 0;
+      throw error;
+    }
+    await this.handle(message);
+    return 1;
+  }
+  /** Poll until `signal` aborts. */
+  async run(signal) {
+    while (signal?.aborted !== true) {
+      await this.poll();
+    }
+  }
+  async handle(message) {
+    const envelope = EnvelopeCodec.decode(decodePayload(message.getData()));
+    const redeliveryCount = typeof message.getRedeliveryCount === "function" ? message.getRedeliveryCount() : 0;
+    const current = typeof envelope.attempts === "number" ? envelope.attempts : 0;
+    if (redeliveryCount > current) {
+      envelope.attempts = redeliveryCount;
+    }
+    if (!EnvelopeCodec.accepts(envelope)) {
+      this.options.onError?.(
+        new BabelQueueError("Rejected a non-conformant BabelQueue envelope from Apache Pulsar."),
+        envelope,
+        message
+      );
+      await this.consumer.negativeAcknowledge(message);
+      return;
+    }
+    const urn = EnvelopeCodec.urn(envelope);
+    const handler = this.handlers[urn];
+    if (!handler) {
+      if (this.options.onUnknownUrn) {
+        await this.options.onUnknownUrn(envelope, message);
+        await this.consumer.acknowledge(message);
+      } else {
+        this.options.onError?.(new UnknownUrnError(urn), envelope, message);
+        await this.consumer.negativeAcknowledge(message);
+      }
+      return;
+    }
+    try {
+      await handler(envelope, message);
+      await this.consumer.acknowledge(message);
+    } catch (error) {
+      this.options.onError?.(error, envelope, message);
+      await this.consumer.negativeAcknowledge(message);
+    }
+  }
+};
+export {
+  PulsarConsumer,
+  PulsarPublisher,
+  pulsarProperties,
+  toPulsarMessage
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Apache Pulsar adapter for BabelQueue.\n *\n * A canonical-envelope **publisher** and a URN-routed **consumer** over Apache Pulsar, so a\n * Pulsar-based Node service speaks the same contract (envelope shape, URN identity, trace\n * propagation) as the .NET, Java, Python and Go SDKs.\n *\n *     import Pulsar from \"pulsar-client\";\n *     import { PulsarPublisher, PulsarConsumer } from \"@babelqueue/pulsar\";\n *\n *     const client = new Pulsar.Client({ serviceUrl: \"pulsar://localhost:6650\" });\n *\n *     const producer = await client.createProducer({ topic: \"orders\" });\n *     await new PulsarPublisher(producer).publish(\"urn:babel:orders:created\", { order_id: 1042 });\n *\n *     const sub = await client.subscribe({\n *       topic: \"orders\", subscription: \"babelqueue\", subscriptionType: \"Shared\",\n *     });\n *     const consumer = new PulsarConsumer(sub, {\n *       \"urn:babel:orders:created\": async (env) => { ... },\n *     });\n *     await consumer.run();\n *\n * This implements §5 of the broker-bindings contract: the canonical envelope is the message\n * payload, projected onto native Pulsar message properties (string→string) — `bq-job` = URN,\n * `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus `bq-schema-version` /\n * `bq-source-lang` / `bq-attempts`. The envelope is unchanged (`schema_version` stays 1);\n * Pulsar is purely additive. A failed handler `negativeAcknowledge`s the message, so it is\n * redelivered (at-least-once) and `getRedeliveryCount()` is incremented; the authoritative\n * attempt count is the body's `bq-attempts`, reconciled to `max(bq-attempts,\n * getRedeliveryCount())` — no −1, because Pulsar's redelivery count is 0-based.\n */\n\nimport { BabelQueueError, EnvelopeCodec, UnknownUrnError } from \"@babelqueue/core\";\nimport type { Envelope, IncomingEnvelope } from \"@babelqueue/core\";\n\n// --- Minimal Pulsar shapes (a structural subset of pulsar-client) --------------\n\n/** A message to send (structural subset of pulsar-client `ProducerMessage`). */\nexport interface PulsarProducerMessage {\n  data: Buffer;\n  properties?: { [key: string]: string };\n  /** Relative delay in milliseconds before the message becomes available (native `deliverAfter`). */\n  deliverAfter?: number;\n}\n\n/**\n * The subset of the Pulsar producer this adapter calls. A `Producer` from `pulsar-client`\n * satisfies it structurally; a fake satisfies it in tests.\n */\nexport interface PulsarProducer {\n  getTopic(): string;\n  send(message: PulsarProducerMessage): Promise<unknown>;\n}\n\n/** A received message (structural subset of pulsar-client `Message`). */\nexport interface PulsarReceivedMessage {\n  getData(): Buffer | string;\n  getProperties(): { [key: string]: string };\n  getRedeliveryCount(): number;\n}\n\n/**\n * The subset of the Pulsar consumer this adapter calls. A `Consumer` from `pulsar-client`\n * satisfies it structurally; a fake satisfies it in tests.\n */\nexport interface PulsarConsumerClient {\n  receive(timeoutMs?: number): Promise<PulsarReceivedMessage>;\n  acknowledge(message: PulsarReceivedMessage): Promise<void> | void;\n  negativeAcknowledge(message: PulsarReceivedMessage): Promise<void> | void;\n}\n\n// --- Property projection (contract §5.2) ---------------------------------------\n\n/** Bare topic name (the part after the last `/`), used as `meta.queue`. */\nfunction topicName(topic: string): string {\n  const slash = topic.lastIndexOf(\"/\");\n  return slash >= 0 ? topic.slice(slash + 1) : topic;\n}\n\n/**\n * Project the envelope's contract fields onto native Pulsar message properties\n * (string→string): `bq-job` = URN, `bq-trace-id` = trace_id, `bq-message-id` = meta.id, plus\n * `bq-schema-version` / `bq-source-lang` / `bq-attempts`. The body stays authoritative.\n */\nexport function pulsarProperties(envelope: Envelope): { [key: string]: string } {\n  const properties: { [key: string]: string } = {};\n  if (envelope.job) properties[\"bq-job\"] = envelope.job;\n  if (envelope.trace_id) properties[\"bq-trace-id\"] = envelope.trace_id;\n  if (envelope.meta.id) properties[\"bq-message-id\"] = envelope.meta.id;\n  if (envelope.meta.schema_version != null) {\n    properties[\"bq-schema-version\"] = String(envelope.meta.schema_version);\n  }\n  if (envelope.meta.lang) properties[\"bq-source-lang\"] = envelope.meta.lang;\n  properties[\"bq-attempts\"] = String(envelope.attempts ?? 0);\n  return properties;\n}\n\n/** Project the envelope onto a native Pulsar producer message (payload + properties). */\nexport function toPulsarMessage(envelope: Envelope): PulsarProducerMessage {\n  return {\n    data: Buffer.from(EnvelopeCodec.encode(envelope), \"utf8\"),\n    properties: pulsarProperties(envelope),\n  };\n}\n\n// --- Publisher -----------------------------------------------------------------\n\n/** Options for {@link PulsarPublisher.publish}. */\nexport interface PublishOptions {\n  /** Reuse an existing trace id (trace continuation). */\n  traceId?: string;\n  /** Schedule native delayed delivery this many milliseconds from now (`deliverAfter`). */\n  delayMs?: number;\n}\n\n/** Sends canonical-envelope messages to one Pulsar topic with the §5 property projection. */\nexport class PulsarPublisher {\n  constructor(private readonly producer: PulsarProducer) {}\n\n  /**\n   * Build the canonical envelope for `(urn, data)`, send it with the §5 property projection,\n   * and return the message id (`meta.id`). A positive `delayMs` schedules native delayed\n   * delivery via `deliverAfter` and mirrors `bq-delay`.\n   */\n  async publish(\n    urn: string,\n    data: Record<string, unknown>,\n    options: PublishOptions = {},\n  ): Promise<string> {\n    const envelope = EnvelopeCodec.make(urn, data, {\n      queue: topicName(this.producer.getTopic()),\n      traceId: options.traceId,\n    });\n    const message = toPulsarMessage(envelope);\n\n    if (options.delayMs != null && options.delayMs > 0) {\n      message.properties = { ...message.properties, \"bq-delay\": String(options.delayMs) };\n      message.deliverAfter = options.delayMs;\n    }\n\n    await this.producer.send(message);\n    return envelope.meta.id;\n  }\n}\n\n// --- Consumer ------------------------------------------------------------------\n\n/** A URN handler. Receives the validated envelope and the raw Pulsar message. */\nexport type BabelHandler = (envelope: Envelope, message: PulsarReceivedMessage) => unknown | Promise<unknown>;\n\n/** A map of URN → handler. */\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/** Options for {@link PulsarConsumer}. */\nexport interface PulsarConsumerOptions {\n  /** Called instead of erroring when a message's URN has no handler (then the message is acknowledged). */\n  onUnknownUrn?: (envelope: IncomingEnvelope, message: PulsarReceivedMessage) => unknown | Promise<unknown>;\n  /** Called for a non-conformant envelope, an unmapped URN (no `onUnknownUrn`), or a throwing handler. The loop never stops. */\n  onError?: (error: unknown, envelope: IncomingEnvelope, message: PulsarReceivedMessage) => void;\n  /** Per-receive timeout in ms (default 1000). A timeout yields an empty poll, not an error. */\n  receiveTimeoutMs?: number;\n}\n\nfunction isReceiveTimeout(error: unknown): boolean {\n  const message = error instanceof Error ? error.message : String(error);\n  return /timeout/i.test(message);\n}\n\nfunction decodePayload(data: Buffer | string): string {\n  return typeof data === \"string\" ? data : data.toString(\"utf8\");\n}\n\n/**\n * Receives from a Pulsar subscription, decodes + validates each message, routes it to the\n * handler for its URN, and acknowledges it on success. A throwing handler\n * `negativeAcknowledge`s the message — the broker redelivers it and increments\n * `getRedeliveryCount()` (at-least-once); `attempts` is reconciled to\n * `max(bq-attempts, getRedeliveryCount())` for the handler.\n */\nexport class PulsarConsumer {\n  constructor(\n    private readonly consumer: PulsarConsumerClient,\n    private readonly handlers: BabelHandlers,\n    private readonly options: PulsarConsumerOptions = {},\n  ) {}\n\n  /** Receive one message (up to the receive timeout), route + settle it. Returns 1, or 0 on timeout. */\n  async poll(): Promise<number> {\n    let message: PulsarReceivedMessage;\n    try {\n      message = await this.consumer.receive(this.options.receiveTimeoutMs ?? 1000);\n    } catch (error) {\n      if (isReceiveTimeout(error)) return 0;\n      throw error;\n    }\n    await this.handle(message);\n    return 1;\n  }\n\n  /** Poll until `signal` aborts. */\n  async run(signal?: AbortSignal): Promise<void> {\n    while (signal?.aborted !== true) {\n      await this.poll();\n    }\n  }\n\n  private async handle(message: PulsarReceivedMessage): Promise<void> {\n    const envelope = EnvelopeCodec.decode(decodePayload(message.getData()));\n\n    // attempts = max(current, getRedeliveryCount()): the redelivery count is 0-based, so it\n    // maps directly with no −1; the max never lowers a higher body count republished from\n    // another SDK (the Go/Python transports retry by re-sending with attempts+1).\n    const redeliveryCount = typeof message.getRedeliveryCount === \"function\" ? message.getRedeliveryCount() : 0;\n    const current = typeof envelope.attempts === \"number\" ? envelope.attempts : 0;\n    if (redeliveryCount > current) {\n      envelope.attempts = redeliveryCount;\n    }\n\n    if (!EnvelopeCodec.accepts(envelope)) {\n      this.options.onError?.(\n        new BabelQueueError(\"Rejected a non-conformant BabelQueue envelope from Apache Pulsar.\"),\n        envelope,\n        message,\n      );\n      await this.consumer.negativeAcknowledge(message);\n      return;\n    }\n\n    const urn = EnvelopeCodec.urn(envelope);\n    const handler = this.handlers[urn];\n    if (!handler) {\n      if (this.options.onUnknownUrn) {\n        await this.options.onUnknownUrn(envelope, message);\n        await this.consumer.acknowledge(message);\n      } else {\n        this.options.onError?.(new UnknownUrnError(urn), envelope, message);\n        await this.consumer.negativeAcknowledge(message);\n      }\n      return;\n    }\n\n    try {\n      await handler(envelope as Envelope, message);\n      await this.consumer.acknowledge(message);\n    } catch (error) {\n      // Negative-ack releases the message — the broker redelivers and increments the count.\n      this.options.onError?.(error, envelope, message);\n      await this.consumer.negativeAcknowledge(message);\n    }\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@babelqueue/pulsar",
+  "version": "1.0.0",
+  "description": "Apache Pulsar adapter for BabelQueue — canonical-envelope publisher and a URN-routed consumer.",
+  "keywords": ["babelqueue", "pulsar", "apache-pulsar", "queue", "polyglot", "messaging"],
+  "homepage": "https://babelqueue.com",
+  "bugs": {
+    "url": "https://github.com/BabelQueue/babelqueue-node-adapters/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BabelQueue/babelqueue-node-adapters.git",
+    "directory": "packages/pulsar"
+  },
+  "license": "MIT",
+  "author": "Muhammet Şafak <info@muhammetsafak.com.tr>",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  },
+  "dependencies": {
+    "@babelqueue/core": "^1.0.0"
+  },
+  "peerDependencies": {
+    "pulsar-client": "^1.8.0"
+  },
+  "peerDependenciesMeta": {
+    "pulsar-client": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}