@babelqueue/sqs 1.0.0

package/README.md

@@ -0,0 +1,74 @@
+# @babelqueue/sqs
+
+Amazon SQS adapter for [BabelQueue](https://babelqueue.com) — "Polyglot Queues,
+Simplified."
+
+A canonical-envelope **publisher** and a URN-routed **consumer** over Amazon SQS, so
+an SQS-based Node service speaks the same wire contract as the PHP/Laravel, Python,
+Go, Java and .NET SDKs. Implements [§3 of the broker-bindings contract](https://babelqueue.com):
+the canonical envelope is the message body, projected onto native SQS
+`MessageAttributes`.
+
+## Install
+
+```bash
+npm i @babelqueue/sqs @aws-sdk/client-sqs
+```
+
+`@aws-sdk/client-sqs` is an (optional) peer — you provide the SQS client.
+
+## Use
+
+```ts
+import { SQS } from "@aws-sdk/client-sqs";
+import { SqsPublisher, SqsConsumer } from "@babelqueue/sqs";
+
+const sqs = new SQS({ region: "eu-central-1" });
+const url = "https://sqs.eu-central-1.amazonaws.com/123456789012/orders";
+
+// produce
+await new SqsPublisher(sqs, url).publish("urn:babel:orders:created", { order_id: 1042 });
+
+// consume
+const consumer = new SqsConsumer(sqs, url, {
+  "urn:babel:orders:created": async (env) => {
+    // env.data, env.trace_id, env.attempts ...
+  },
+});
+await consumer.run(); // long-polls until the AbortSignal you pass aborts
+```
+
+FIFO queues: `new SqsPublisher(sqs, url, { fifo: true })` (the URL must end in `.fifo`).
+For LocalStack/ElasticMQ, point the `SQS` client's `endpoint` there.
+
+## Contract mapping (§3)
+
+| Envelope | SQS |
+| :--- | :--- |
+| body | `MessageBody` (byte-identical across SDKs) |
+| `job` (URN) | `MessageAttributes.bq-job` |
+| `trace_id` | `MessageAttributes.bq-trace-id` |
+| `meta.id` | `MessageAttributes.bq-message-id` |
+| `meta.schema_version` | `MessageAttributes.bq-schema-version` (Number) |
+| `meta.lang` | `MessageAttributes.bq-source-lang` |
+| `meta.created_at` | `MessageAttributes.bq-created-at` (Number, ms) |
+| `attempts` | reconciled to `ApproximateReceiveCount − 1` on receive |
+| reserve / ack | visibility timeout → `DeleteMessage` |
+
+Retry is **SQS-native**: a throwing handler leaves the message undeleted, so SQS
+redelivers it after the visibility timeout (at-least-once). The loop never stops on a
+bad message — use `onError` / `onUnknownUrn` to observe. The envelope is unchanged
+(`schema_version` stays `1`); SQS is purely additive.
+
+## Test
+
+The unit tests inject a fake SQS client (`SqsApi`), so they run without
+`@aws-sdk/client-sqs` and without a broker:
+
+```bash
+npm test
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,174 @@
+"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, {
+  SqsConsumer: () => SqsConsumer,
+  SqsPublisher: () => SqsPublisher,
+  toMessageAttributes: () => toMessageAttributes
+});
+module.exports = __toCommonJS(index_exports);
+var import_core = require("@babelqueue/core");
+var str = (value) => ({
+  DataType: "String",
+  StringValue: String(value)
+});
+var num = (value) => ({
+  DataType: "Number",
+  StringValue: String(value)
+});
+function toMessageAttributes(envelope) {
+  const attrs = {};
+  if (envelope.job) attrs["bq-job"] = str(envelope.job);
+  if (envelope.trace_id) attrs["bq-trace-id"] = str(envelope.trace_id);
+  if (envelope.meta.id) attrs["bq-message-id"] = str(envelope.meta.id);
+  if (envelope.meta.schema_version != null) {
+    attrs["bq-schema-version"] = num(envelope.meta.schema_version);
+  }
+  if (envelope.meta.lang) attrs["bq-source-lang"] = str(envelope.meta.lang);
+  if (envelope.meta.created_at != null) {
+    attrs["bq-created-at"] = num(envelope.meta.created_at);
+  }
+  return attrs;
+}
+function queueNameFromUrl(queueUrl) {
+  const segments = queueUrl.split("/").filter(Boolean);
+  return segments[segments.length - 1] ?? "default";
+}
+var SqsPublisher = class {
+  constructor(client, queueUrl, options = {}) {
+    this.client = client;
+    this.queueUrl = queueUrl;
+    this.options = options;
+  }
+  client;
+  queueUrl;
+  options;
+  /**
+   * Build the canonical envelope for `(urn, data)`, send it as the message body with
+   * the projected `MessageAttributes`, and return the message id (`meta.id`).
+   */
+  async publish(urn, data, options = {}) {
+    const envelope = import_core.EnvelopeCodec.make(urn, data, {
+      queue: queueNameFromUrl(this.queueUrl),
+      traceId: options.traceId
+    });
+    const input = {
+      QueueUrl: this.queueUrl,
+      MessageBody: import_core.EnvelopeCodec.encode(envelope),
+      MessageAttributes: toMessageAttributes(envelope)
+    };
+    if (this.options.fifo) {
+      input.MessageGroupId = this.options.messageGroupId ?? queueNameFromUrl(this.queueUrl);
+      if (!this.options.contentDedup) {
+        input.MessageDeduplicationId = envelope.meta.id;
+      }
+    }
+    await this.client.sendMessage(input);
+    return envelope.meta.id;
+  }
+};
+var SqsConsumer = class {
+  constructor(client, queueUrl, handlers, options = {}) {
+    this.client = client;
+    this.queueUrl = queueUrl;
+    this.handlers = handlers;
+    this.options = options;
+  }
+  client;
+  queueUrl;
+  handlers;
+  options;
+  /** Receive one batch, route each message, delete the ones handled. Returns the batch size. */
+  async poll() {
+    const input = {
+      QueueUrl: this.queueUrl,
+      MaxNumberOfMessages: this.options.maxMessages ?? 10,
+      WaitTimeSeconds: this.options.waitTimeSeconds ?? 20,
+      MessageAttributeNames: ["All"],
+      AttributeNames: ["ApproximateReceiveCount"]
+    };
+    if (this.options.visibilityTimeout != null) {
+      input.VisibilityTimeout = this.options.visibilityTimeout;
+    }
+    const result = await this.client.receiveMessage(input);
+    const messages = result.Messages ?? [];
+    for (const message of messages) {
+      await this.handle(message);
+    }
+    return messages.length;
+  }
+  /** Poll until `signal` aborts (each poll long-polls, so this does not busy-loop). */
+  async run(signal) {
+    while (signal?.aborted !== true) {
+      await this.poll();
+    }
+  }
+  async handle(message) {
+    const envelope = import_core.EnvelopeCodec.decode(message.Body ?? "");
+    const receiveCount = message.Attributes?.["ApproximateReceiveCount"];
+    if (receiveCount !== void 0) {
+      const native = Number.parseInt(receiveCount, 10) - 1;
+      const current = typeof envelope.attempts === "number" ? envelope.attempts : 0;
+      if (Number.isFinite(native) && native > current) {
+        envelope.attempts = native;
+      }
+    }
+    if (!import_core.EnvelopeCodec.accepts(envelope)) {
+      this.options.onError?.(
+        new import_core.BabelQueueError("Rejected a non-conformant BabelQueue envelope from SQS."),
+        envelope,
+        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.delete(message);
+      } else {
+        this.options.onError?.(new import_core.UnknownUrnError(urn), envelope, message);
+      }
+      return;
+    }
+    try {
+      await handler(envelope, message);
+      await this.delete(message);
+    } catch (error) {
+      this.options.onError?.(error, envelope, message);
+    }
+  }
+  async delete(message) {
+    if (!message.ReceiptHandle) return;
+    await this.client.deleteMessage({
+      QueueUrl: this.queueUrl,
+      ReceiptHandle: message.ReceiptHandle
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SqsConsumer,
+  SqsPublisher,
+  toMessageAttributes
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Amazon SQS adapter for BabelQueue.\n *\n * A canonical-envelope **publisher** and a URN-routed **consumer** over Amazon SQS,\n * so an SQS-based Node service speaks the same contract (envelope shape, URN\n * identity, trace propagation) as the PHP/Laravel, Python, Go, Java and .NET SDKs.\n *\n *     import { SQS } from \"@aws-sdk/client-sqs\";\n *     import { SqsPublisher, SqsConsumer } from \"@babelqueue/sqs\";\n *\n *     const sqs = new SQS({ region: \"eu-central-1\" });\n *     const url = \"https://sqs.eu-central-1.amazonaws.com/123456789012/orders\";\n *\n *     await new SqsPublisher(sqs, url).publish(\"urn:babel:orders:created\", { order_id: 1042 });\n *\n *     const consumer = new SqsConsumer(sqs, url, {\n *       \"urn:babel:orders:created\": async (env) => { ... },\n *     });\n *     await consumer.run();\n *\n * This implements §3 of the broker-bindings contract: the canonical envelope is the\n * message body, projected onto native SQS `MessageAttributes`. The envelope is\n * unchanged (`schema_version` stays 1); SQS is purely additive. Retry is SQS-native\n * (a failed handler leaves the message for visibility-timeout redelivery); the\n * authoritative attempt count is `ApproximateReceiveCount`, surfaced to handlers as\n * `attempts = count − 1`.\n */\n\nimport { BabelQueueError, EnvelopeCodec, UnknownUrnError } from \"@babelqueue/core\";\nimport type { Envelope, IncomingEnvelope } from \"@babelqueue/core\";\n\n// --- Minimal SQS shapes (a structural subset of @aws-sdk/client-sqs) -----------\n\nexport interface SqsMessageAttributeValue {\n  DataType: string;\n  StringValue?: string;\n}\n\nexport interface SqsMessage {\n  Body?: string;\n  ReceiptHandle?: string;\n  MessageAttributes?: Record<string, SqsMessageAttributeValue>;\n  Attributes?: Record<string, string>;\n}\n\nexport interface SendMessageInput {\n  QueueUrl: string;\n  MessageBody: string;\n  MessageAttributes?: Record<string, SqsMessageAttributeValue>;\n  MessageGroupId?: string;\n  MessageDeduplicationId?: string;\n}\n\nexport interface ReceiveMessageInput {\n  QueueUrl: string;\n  MaxNumberOfMessages?: number;\n  WaitTimeSeconds?: number;\n  VisibilityTimeout?: number;\n  MessageAttributeNames?: string[];\n  AttributeNames?: string[];\n}\n\n/**\n * The subset of the AWS SQS client this adapter calls. The aggregated `SQS` class\n * from `@aws-sdk/client-sqs` satisfies it structurally; a fake satisfies it in tests.\n */\nexport interface SqsApi {\n  sendMessage(input: SendMessageInput): Promise<{ MessageId?: string } | unknown>;\n  receiveMessage(input: ReceiveMessageInput): Promise<{ Messages?: SqsMessage[] }>;\n  deleteMessage(input: { QueueUrl: string; ReceiptHandle: string }): Promise<unknown>;\n}\n\n// --- Attribute projection (contract §3.2) --------------------------------------\n\nconst str = (value: unknown): SqsMessageAttributeValue => ({\n  DataType: \"String\",\n  StringValue: String(value),\n});\nconst num = (value: unknown): SqsMessageAttributeValue => ({\n  DataType: \"Number\",\n  StringValue: String(value),\n});\n\n/**\n * Project the envelope's contract fields onto native SQS `MessageAttributes` — a\n * redundant, routable view of the body (the body stays authoritative).\n */\nexport function toMessageAttributes(envelope: Envelope): Record<string, SqsMessageAttributeValue> {\n  const attrs: Record<string, SqsMessageAttributeValue> = {};\n  if (envelope.job) attrs[\"bq-job\"] = str(envelope.job);\n  if (envelope.trace_id) attrs[\"bq-trace-id\"] = str(envelope.trace_id);\n  if (envelope.meta.id) attrs[\"bq-message-id\"] = str(envelope.meta.id);\n  if (envelope.meta.schema_version != null) {\n    attrs[\"bq-schema-version\"] = num(envelope.meta.schema_version);\n  }\n  if (envelope.meta.lang) attrs[\"bq-source-lang\"] = str(envelope.meta.lang);\n  if (envelope.meta.created_at != null) {\n    attrs[\"bq-created-at\"] = num(envelope.meta.created_at);\n  }\n  return attrs;\n}\n\nfunction queueNameFromUrl(queueUrl: string): string {\n  const segments = queueUrl.split(\"/\").filter(Boolean);\n  return segments[segments.length - 1] ?? \"default\";\n}\n\n// --- Publisher -----------------------------------------------------------------\n\n/** Options for {@link SqsPublisher}. */\nexport interface SqsPublisherOptions {\n  /** Treat the queue as FIFO: set `MessageGroupId` and (unless content dedup) `MessageDeduplicationId`. */\n  fifo?: boolean;\n  /** FIFO ordering group (default: the queue name from the URL). */\n  messageGroupId?: string;\n  /** Use the queue's content-based dedup instead of `meta.id` as the dedup id. */\n  contentDedup?: boolean;\n}\n\n/** Options for {@link SqsPublisher.publish}. */\nexport interface PublishOptions {\n  /** Reuse an existing trace id (trace continuation). */\n  traceId?: string;\n}\n\n/** Sends canonical-envelope messages to one SQS queue with the §3 attribute projection. */\nexport class SqsPublisher {\n  constructor(\n    private readonly client: SqsApi,\n    private readonly queueUrl: string,\n    private readonly options: SqsPublisherOptions = {},\n  ) {}\n\n  /**\n   * Build the canonical envelope for `(urn, data)`, send it as the message body with\n   * the projected `MessageAttributes`, and return the message id (`meta.id`).\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: queueNameFromUrl(this.queueUrl),\n      traceId: options.traceId,\n    });\n    const input: SendMessageInput = {\n      QueueUrl: this.queueUrl,\n      MessageBody: EnvelopeCodec.encode(envelope),\n      MessageAttributes: toMessageAttributes(envelope),\n    };\n    if (this.options.fifo) {\n      input.MessageGroupId = this.options.messageGroupId ?? queueNameFromUrl(this.queueUrl);\n      if (!this.options.contentDedup) {\n        input.MessageDeduplicationId = envelope.meta.id;\n      }\n    }\n    await this.client.sendMessage(input);\n    return envelope.meta.id;\n  }\n}\n\n// --- Consumer ------------------------------------------------------------------\n\n/** A URN handler. Receives the validated envelope and the raw SQS message. */\nexport type BabelHandler = (envelope: Envelope, message: SqsMessage) => unknown | Promise<unknown>;\n\n/** A map of URN → handler. */\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/** Options for {@link SqsConsumer}. */\nexport interface SqsConsumerOptions {\n  /** Called instead of erroring when a message's URN has no handler (then the message is deleted). */\n  onUnknownUrn?: (envelope: IncomingEnvelope, message: SqsMessage) => 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: SqsMessage) => void;\n  /** Long-poll wait seconds (default 20). */\n  waitTimeSeconds?: number;\n  /** Reservation window applied on receive (seconds). */\n  visibilityTimeout?: number;\n  /** Max messages per receive (default 10). */\n  maxMessages?: number;\n}\n\n/**\n * Polls an SQS queue, decodes + validates each message, routes it to the handler\n * registered for its URN, and deletes it on success. A throwing handler leaves the\n * message undeleted — SQS redelivers it after the visibility timeout (at-least-once);\n * `attempts` is reconciled to `ApproximateReceiveCount − 1` for the handler.\n */\nexport class SqsConsumer {\n  constructor(\n    private readonly client: SqsApi,\n    private readonly queueUrl: string,\n    private readonly handlers: BabelHandlers,\n    private readonly options: SqsConsumerOptions = {},\n  ) {}\n\n  /** Receive one batch, route each message, delete the ones handled. Returns the batch size. */\n  async poll(): Promise<number> {\n    const input: ReceiveMessageInput = {\n      QueueUrl: this.queueUrl,\n      MaxNumberOfMessages: this.options.maxMessages ?? 10,\n      WaitTimeSeconds: this.options.waitTimeSeconds ?? 20,\n      MessageAttributeNames: [\"All\"],\n      AttributeNames: [\"ApproximateReceiveCount\"],\n    };\n    if (this.options.visibilityTimeout != null) {\n      input.VisibilityTimeout = this.options.visibilityTimeout;\n    }\n    const result = await this.client.receiveMessage(input);\n    const messages = result.Messages ?? [];\n    for (const message of messages) {\n      await this.handle(message);\n    }\n    return messages.length;\n  }\n\n  /** Poll until `signal` aborts (each poll long-polls, so this does not busy-loop). */\n  async run(signal?: AbortSignal): Promise<void> {\n    while (signal?.aborted !== true) {\n      await this.poll();\n    }\n  }\n\n  private async handle(message: SqsMessage): Promise<void> {\n    const envelope = EnvelopeCodec.decode(message.Body ?? \"\");\n\n    const receiveCount = message.Attributes?.[\"ApproximateReceiveCount\"];\n    if (receiveCount !== undefined) {\n      const native = Number.parseInt(receiveCount, 10) - 1;\n      const current = typeof envelope.attempts === \"number\" ? envelope.attempts : 0;\n      if (Number.isFinite(native) && native > current) {\n        envelope.attempts = native;\n      }\n    }\n\n    if (!EnvelopeCodec.accepts(envelope)) {\n      this.options.onError?.(\n        new BabelQueueError(\"Rejected a non-conformant BabelQueue envelope from SQS.\"),\n        envelope,\n        message,\n      );\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.delete(message);\n      } else {\n        this.options.onError?.(new UnknownUrnError(urn), envelope, message);\n      }\n      return;\n    }\n\n    try {\n      await handler(envelope, message);\n      await this.delete(message);\n    } catch (error) {\n      // Leave the message undeleted — SQS redelivers after the visibility timeout.\n      this.options.onError?.(error, envelope, message);\n    }\n  }\n\n  private async delete(message: SqsMessage): Promise<void> {\n    if (!message.ReceiptHandle) return;\n    await this.client.deleteMessage({\n      QueueUrl: this.queueUrl,\n      ReceiptHandle: message.ReceiptHandle,\n    });\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,140 @@
+import { Envelope, IncomingEnvelope } from '@babelqueue/core';
+
+/**
+ * Amazon SQS adapter for BabelQueue.
+ *
+ * A canonical-envelope **publisher** and a URN-routed **consumer** over Amazon SQS,
+ * so an SQS-based Node service speaks the same contract (envelope shape, URN
+ * identity, trace propagation) as the PHP/Laravel, Python, Go, Java and .NET SDKs.
+ *
+ *     import { SQS } from "@aws-sdk/client-sqs";
+ *     import { SqsPublisher, SqsConsumer } from "@babelqueue/sqs";
+ *
+ *     const sqs = new SQS({ region: "eu-central-1" });
+ *     const url = "https://sqs.eu-central-1.amazonaws.com/123456789012/orders";
+ *
+ *     await new SqsPublisher(sqs, url).publish("urn:babel:orders:created", { order_id: 1042 });
+ *
+ *     const consumer = new SqsConsumer(sqs, url, {
+ *       "urn:babel:orders:created": async (env) => { ... },
+ *     });
+ *     await consumer.run();
+ *
+ * This implements §3 of the broker-bindings contract: the canonical envelope is the
+ * message body, projected onto native SQS `MessageAttributes`. The envelope is
+ * unchanged (`schema_version` stays 1); SQS is purely additive. Retry is SQS-native
+ * (a failed handler leaves the message for visibility-timeout redelivery); the
+ * authoritative attempt count is `ApproximateReceiveCount`, surfaced to handlers as
+ * `attempts = count − 1`.
+ */
+
+interface SqsMessageAttributeValue {
+    DataType: string;
+    StringValue?: string;
+}
+interface SqsMessage {
+    Body?: string;
+    ReceiptHandle?: string;
+    MessageAttributes?: Record<string, SqsMessageAttributeValue>;
+    Attributes?: Record<string, string>;
+}
+interface SendMessageInput {
+    QueueUrl: string;
+    MessageBody: string;
+    MessageAttributes?: Record<string, SqsMessageAttributeValue>;
+    MessageGroupId?: string;
+    MessageDeduplicationId?: string;
+}
+interface ReceiveMessageInput {
+    QueueUrl: string;
+    MaxNumberOfMessages?: number;
+    WaitTimeSeconds?: number;
+    VisibilityTimeout?: number;
+    MessageAttributeNames?: string[];
+    AttributeNames?: string[];
+}
+/**
+ * The subset of the AWS SQS client this adapter calls. The aggregated `SQS` class
+ * from `@aws-sdk/client-sqs` satisfies it structurally; a fake satisfies it in tests.
+ */
+interface SqsApi {
+    sendMessage(input: SendMessageInput): Promise<{
+        MessageId?: string;
+    } | unknown>;
+    receiveMessage(input: ReceiveMessageInput): Promise<{
+        Messages?: SqsMessage[];
+    }>;
+    deleteMessage(input: {
+        QueueUrl: string;
+        ReceiptHandle: string;
+    }): Promise<unknown>;
+}
+/**
+ * Project the envelope's contract fields onto native SQS `MessageAttributes` — a
+ * redundant, routable view of the body (the body stays authoritative).
+ */
+declare function toMessageAttributes(envelope: Envelope): Record<string, SqsMessageAttributeValue>;
+/** Options for {@link SqsPublisher}. */
+interface SqsPublisherOptions {
+    /** Treat the queue as FIFO: set `MessageGroupId` and (unless content dedup) `MessageDeduplicationId`. */
+    fifo?: boolean;
+    /** FIFO ordering group (default: the queue name from the URL). */
+    messageGroupId?: string;
+    /** Use the queue's content-based dedup instead of `meta.id` as the dedup id. */
+    contentDedup?: boolean;
+}
+/** Options for {@link SqsPublisher.publish}. */
+interface PublishOptions {
+    /** Reuse an existing trace id (trace continuation). */
+    traceId?: string;
+}
+/** Sends canonical-envelope messages to one SQS queue with the §3 attribute projection. */
+declare class SqsPublisher {
+    private readonly client;
+    private readonly queueUrl;
+    private readonly options;
+    constructor(client: SqsApi, queueUrl: string, options?: SqsPublisherOptions);
+    /**
+     * Build the canonical envelope for `(urn, data)`, send it as the message body with
+     * the projected `MessageAttributes`, and return the message id (`meta.id`).
+     */
+    publish(urn: string, data: Record<string, unknown>, options?: PublishOptions): Promise<string>;
+}
+/** A URN handler. Receives the validated envelope and the raw SQS message. */
+type BabelHandler = (envelope: Envelope, message: SqsMessage) => unknown | Promise<unknown>;
+/** A map of URN → handler. */
+type BabelHandlers = Record<string, BabelHandler>;
+/** Options for {@link SqsConsumer}. */
+interface SqsConsumerOptions {
+    /** Called instead of erroring when a message's URN has no handler (then the message is deleted). */
+    onUnknownUrn?: (envelope: IncomingEnvelope, message: SqsMessage) => 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: SqsMessage) => void;
+    /** Long-poll wait seconds (default 20). */
+    waitTimeSeconds?: number;
+    /** Reservation window applied on receive (seconds). */
+    visibilityTimeout?: number;
+    /** Max messages per receive (default 10). */
+    maxMessages?: number;
+}
+/**
+ * Polls an SQS queue, decodes + validates each message, routes it to the handler
+ * registered for its URN, and deletes it on success. A throwing handler leaves the
+ * message undeleted — SQS redelivers it after the visibility timeout (at-least-once);
+ * `attempts` is reconciled to `ApproximateReceiveCount − 1` for the handler.
+ */
+declare class SqsConsumer {
+    private readonly client;
+    private readonly queueUrl;
+    private readonly handlers;
+    private readonly options;
+    constructor(client: SqsApi, queueUrl: string, handlers: BabelHandlers, options?: SqsConsumerOptions);
+    /** Receive one batch, route each message, delete the ones handled. Returns the batch size. */
+    poll(): Promise<number>;
+    /** Poll until `signal` aborts (each poll long-polls, so this does not busy-loop). */
+    run(signal?: AbortSignal): Promise<void>;
+    private handle;
+    private delete;
+}
+
+export { type BabelHandler, type BabelHandlers, type PublishOptions, type ReceiveMessageInput, type SendMessageInput, type SqsApi, SqsConsumer, type SqsConsumerOptions, type SqsMessage, type SqsMessageAttributeValue, SqsPublisher, type SqsPublisherOptions, toMessageAttributes };

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+import { Envelope, IncomingEnvelope } from '@babelqueue/core';
+
+/**
+ * Amazon SQS adapter for BabelQueue.
+ *
+ * A canonical-envelope **publisher** and a URN-routed **consumer** over Amazon SQS,
+ * so an SQS-based Node service speaks the same contract (envelope shape, URN
+ * identity, trace propagation) as the PHP/Laravel, Python, Go, Java and .NET SDKs.
+ *
+ *     import { SQS } from "@aws-sdk/client-sqs";
+ *     import { SqsPublisher, SqsConsumer } from "@babelqueue/sqs";
+ *
+ *     const sqs = new SQS({ region: "eu-central-1" });
+ *     const url = "https://sqs.eu-central-1.amazonaws.com/123456789012/orders";
+ *
+ *     await new SqsPublisher(sqs, url).publish("urn:babel:orders:created", { order_id: 1042 });
+ *
+ *     const consumer = new SqsConsumer(sqs, url, {
+ *       "urn:babel:orders:created": async (env) => { ... },
+ *     });
+ *     await consumer.run();
+ *
+ * This implements §3 of the broker-bindings contract: the canonical envelope is the
+ * message body, projected onto native SQS `MessageAttributes`. The envelope is
+ * unchanged (`schema_version` stays 1); SQS is purely additive. Retry is SQS-native
+ * (a failed handler leaves the message for visibility-timeout redelivery); the
+ * authoritative attempt count is `ApproximateReceiveCount`, surfaced to handlers as
+ * `attempts = count − 1`.
+ */
+
+interface SqsMessageAttributeValue {
+    DataType: string;
+    StringValue?: string;
+}
+interface SqsMessage {
+    Body?: string;
+    ReceiptHandle?: string;
+    MessageAttributes?: Record<string, SqsMessageAttributeValue>;
+    Attributes?: Record<string, string>;
+}
+interface SendMessageInput {
+    QueueUrl: string;
+    MessageBody: string;
+    MessageAttributes?: Record<string, SqsMessageAttributeValue>;
+    MessageGroupId?: string;
+    MessageDeduplicationId?: string;
+}
+interface ReceiveMessageInput {
+    QueueUrl: string;
+    MaxNumberOfMessages?: number;
+    WaitTimeSeconds?: number;
+    VisibilityTimeout?: number;
+    MessageAttributeNames?: string[];
+    AttributeNames?: string[];
+}
+/**
+ * The subset of the AWS SQS client this adapter calls. The aggregated `SQS` class
+ * from `@aws-sdk/client-sqs` satisfies it structurally; a fake satisfies it in tests.
+ */
+interface SqsApi {
+    sendMessage(input: SendMessageInput): Promise<{
+        MessageId?: string;
+    } | unknown>;
+    receiveMessage(input: ReceiveMessageInput): Promise<{
+        Messages?: SqsMessage[];
+    }>;
+    deleteMessage(input: {
+        QueueUrl: string;
+        ReceiptHandle: string;
+    }): Promise<unknown>;
+}
+/**
+ * Project the envelope's contract fields onto native SQS `MessageAttributes` — a
+ * redundant, routable view of the body (the body stays authoritative).
+ */
+declare function toMessageAttributes(envelope: Envelope): Record<string, SqsMessageAttributeValue>;
+/** Options for {@link SqsPublisher}. */
+interface SqsPublisherOptions {
+    /** Treat the queue as FIFO: set `MessageGroupId` and (unless content dedup) `MessageDeduplicationId`. */
+    fifo?: boolean;
+    /** FIFO ordering group (default: the queue name from the URL). */
+    messageGroupId?: string;
+    /** Use the queue's content-based dedup instead of `meta.id` as the dedup id. */
+    contentDedup?: boolean;
+}
+/** Options for {@link SqsPublisher.publish}. */
+interface PublishOptions {
+    /** Reuse an existing trace id (trace continuation). */
+    traceId?: string;
+}
+/** Sends canonical-envelope messages to one SQS queue with the §3 attribute projection. */
+declare class SqsPublisher {
+    private readonly client;
+    private readonly queueUrl;
+    private readonly options;
+    constructor(client: SqsApi, queueUrl: string, options?: SqsPublisherOptions);
+    /**
+     * Build the canonical envelope for `(urn, data)`, send it as the message body with
+     * the projected `MessageAttributes`, and return the message id (`meta.id`).
+     */
+    publish(urn: string, data: Record<string, unknown>, options?: PublishOptions): Promise<string>;
+}
+/** A URN handler. Receives the validated envelope and the raw SQS message. */
+type BabelHandler = (envelope: Envelope, message: SqsMessage) => unknown | Promise<unknown>;
+/** A map of URN → handler. */
+type BabelHandlers = Record<string, BabelHandler>;
+/** Options for {@link SqsConsumer}. */
+interface SqsConsumerOptions {
+    /** Called instead of erroring when a message's URN has no handler (then the message is deleted). */
+    onUnknownUrn?: (envelope: IncomingEnvelope, message: SqsMessage) => 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: SqsMessage) => void;
+    /** Long-poll wait seconds (default 20). */
+    waitTimeSeconds?: number;
+    /** Reservation window applied on receive (seconds). */
+    visibilityTimeout?: number;
+    /** Max messages per receive (default 10). */
+    maxMessages?: number;
+}
+/**
+ * Polls an SQS queue, decodes + validates each message, routes it to the handler
+ * registered for its URN, and deletes it on success. A throwing handler leaves the
+ * message undeleted — SQS redelivers it after the visibility timeout (at-least-once);
+ * `attempts` is reconciled to `ApproximateReceiveCount − 1` for the handler.
+ */
+declare class SqsConsumer {
+    private readonly client;
+    private readonly queueUrl;
+    private readonly handlers;
+    private readonly options;
+    constructor(client: SqsApi, queueUrl: string, handlers: BabelHandlers, options?: SqsConsumerOptions);
+    /** Receive one batch, route each message, delete the ones handled. Returns the batch size. */
+    poll(): Promise<number>;
+    /** Poll until `signal` aborts (each poll long-polls, so this does not busy-loop). */
+    run(signal?: AbortSignal): Promise<void>;
+    private handle;
+    private delete;
+}
+
+export { type BabelHandler, type BabelHandlers, type PublishOptions, type ReceiveMessageInput, type SendMessageInput, type SqsApi, SqsConsumer, type SqsConsumerOptions, type SqsMessage, type SqsMessageAttributeValue, SqsPublisher, type SqsPublisherOptions, toMessageAttributes };

package/dist/index.js

@@ -0,0 +1,147 @@
+// src/index.ts
+import { BabelQueueError, EnvelopeCodec, UnknownUrnError } from "@babelqueue/core";
+var str = (value) => ({
+  DataType: "String",
+  StringValue: String(value)
+});
+var num = (value) => ({
+  DataType: "Number",
+  StringValue: String(value)
+});
+function toMessageAttributes(envelope) {
+  const attrs = {};
+  if (envelope.job) attrs["bq-job"] = str(envelope.job);
+  if (envelope.trace_id) attrs["bq-trace-id"] = str(envelope.trace_id);
+  if (envelope.meta.id) attrs["bq-message-id"] = str(envelope.meta.id);
+  if (envelope.meta.schema_version != null) {
+    attrs["bq-schema-version"] = num(envelope.meta.schema_version);
+  }
+  if (envelope.meta.lang) attrs["bq-source-lang"] = str(envelope.meta.lang);
+  if (envelope.meta.created_at != null) {
+    attrs["bq-created-at"] = num(envelope.meta.created_at);
+  }
+  return attrs;
+}
+function queueNameFromUrl(queueUrl) {
+  const segments = queueUrl.split("/").filter(Boolean);
+  return segments[segments.length - 1] ?? "default";
+}
+var SqsPublisher = class {
+  constructor(client, queueUrl, options = {}) {
+    this.client = client;
+    this.queueUrl = queueUrl;
+    this.options = options;
+  }
+  client;
+  queueUrl;
+  options;
+  /**
+   * Build the canonical envelope for `(urn, data)`, send it as the message body with
+   * the projected `MessageAttributes`, and return the message id (`meta.id`).
+   */
+  async publish(urn, data, options = {}) {
+    const envelope = EnvelopeCodec.make(urn, data, {
+      queue: queueNameFromUrl(this.queueUrl),
+      traceId: options.traceId
+    });
+    const input = {
+      QueueUrl: this.queueUrl,
+      MessageBody: EnvelopeCodec.encode(envelope),
+      MessageAttributes: toMessageAttributes(envelope)
+    };
+    if (this.options.fifo) {
+      input.MessageGroupId = this.options.messageGroupId ?? queueNameFromUrl(this.queueUrl);
+      if (!this.options.contentDedup) {
+        input.MessageDeduplicationId = envelope.meta.id;
+      }
+    }
+    await this.client.sendMessage(input);
+    return envelope.meta.id;
+  }
+};
+var SqsConsumer = class {
+  constructor(client, queueUrl, handlers, options = {}) {
+    this.client = client;
+    this.queueUrl = queueUrl;
+    this.handlers = handlers;
+    this.options = options;
+  }
+  client;
+  queueUrl;
+  handlers;
+  options;
+  /** Receive one batch, route each message, delete the ones handled. Returns the batch size. */
+  async poll() {
+    const input = {
+      QueueUrl: this.queueUrl,
+      MaxNumberOfMessages: this.options.maxMessages ?? 10,
+      WaitTimeSeconds: this.options.waitTimeSeconds ?? 20,
+      MessageAttributeNames: ["All"],
+      AttributeNames: ["ApproximateReceiveCount"]
+    };
+    if (this.options.visibilityTimeout != null) {
+      input.VisibilityTimeout = this.options.visibilityTimeout;
+    }
+    const result = await this.client.receiveMessage(input);
+    const messages = result.Messages ?? [];
+    for (const message of messages) {
+      await this.handle(message);
+    }
+    return messages.length;
+  }
+  /** Poll until `signal` aborts (each poll long-polls, so this does not busy-loop). */
+  async run(signal) {
+    while (signal?.aborted !== true) {
+      await this.poll();
+    }
+  }
+  async handle(message) {
+    const envelope = EnvelopeCodec.decode(message.Body ?? "");
+    const receiveCount = message.Attributes?.["ApproximateReceiveCount"];
+    if (receiveCount !== void 0) {
+      const native = Number.parseInt(receiveCount, 10) - 1;
+      const current = typeof envelope.attempts === "number" ? envelope.attempts : 0;
+      if (Number.isFinite(native) && native > current) {
+        envelope.attempts = native;
+      }
+    }
+    if (!EnvelopeCodec.accepts(envelope)) {
+      this.options.onError?.(
+        new BabelQueueError("Rejected a non-conformant BabelQueue envelope from SQS."),
+        envelope,
+        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.delete(message);
+      } else {
+        this.options.onError?.(new UnknownUrnError(urn), envelope, message);
+      }
+      return;
+    }
+    try {
+      await handler(envelope, message);
+      await this.delete(message);
+    } catch (error) {
+      this.options.onError?.(error, envelope, message);
+    }
+  }
+  async delete(message) {
+    if (!message.ReceiptHandle) return;
+    await this.client.deleteMessage({
+      QueueUrl: this.queueUrl,
+      ReceiptHandle: message.ReceiptHandle
+    });
+  }
+};
+export {
+  SqsConsumer,
+  SqsPublisher,
+  toMessageAttributes
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * Amazon SQS adapter for BabelQueue.\n *\n * A canonical-envelope **publisher** and a URN-routed **consumer** over Amazon SQS,\n * so an SQS-based Node service speaks the same contract (envelope shape, URN\n * identity, trace propagation) as the PHP/Laravel, Python, Go, Java and .NET SDKs.\n *\n *     import { SQS } from \"@aws-sdk/client-sqs\";\n *     import { SqsPublisher, SqsConsumer } from \"@babelqueue/sqs\";\n *\n *     const sqs = new SQS({ region: \"eu-central-1\" });\n *     const url = \"https://sqs.eu-central-1.amazonaws.com/123456789012/orders\";\n *\n *     await new SqsPublisher(sqs, url).publish(\"urn:babel:orders:created\", { order_id: 1042 });\n *\n *     const consumer = new SqsConsumer(sqs, url, {\n *       \"urn:babel:orders:created\": async (env) => { ... },\n *     });\n *     await consumer.run();\n *\n * This implements §3 of the broker-bindings contract: the canonical envelope is the\n * message body, projected onto native SQS `MessageAttributes`. The envelope is\n * unchanged (`schema_version` stays 1); SQS is purely additive. Retry is SQS-native\n * (a failed handler leaves the message for visibility-timeout redelivery); the\n * authoritative attempt count is `ApproximateReceiveCount`, surfaced to handlers as\n * `attempts = count − 1`.\n */\n\nimport { BabelQueueError, EnvelopeCodec, UnknownUrnError } from \"@babelqueue/core\";\nimport type { Envelope, IncomingEnvelope } from \"@babelqueue/core\";\n\n// --- Minimal SQS shapes (a structural subset of @aws-sdk/client-sqs) -----------\n\nexport interface SqsMessageAttributeValue {\n  DataType: string;\n  StringValue?: string;\n}\n\nexport interface SqsMessage {\n  Body?: string;\n  ReceiptHandle?: string;\n  MessageAttributes?: Record<string, SqsMessageAttributeValue>;\n  Attributes?: Record<string, string>;\n}\n\nexport interface SendMessageInput {\n  QueueUrl: string;\n  MessageBody: string;\n  MessageAttributes?: Record<string, SqsMessageAttributeValue>;\n  MessageGroupId?: string;\n  MessageDeduplicationId?: string;\n}\n\nexport interface ReceiveMessageInput {\n  QueueUrl: string;\n  MaxNumberOfMessages?: number;\n  WaitTimeSeconds?: number;\n  VisibilityTimeout?: number;\n  MessageAttributeNames?: string[];\n  AttributeNames?: string[];\n}\n\n/**\n * The subset of the AWS SQS client this adapter calls. The aggregated `SQS` class\n * from `@aws-sdk/client-sqs` satisfies it structurally; a fake satisfies it in tests.\n */\nexport interface SqsApi {\n  sendMessage(input: SendMessageInput): Promise<{ MessageId?: string } | unknown>;\n  receiveMessage(input: ReceiveMessageInput): Promise<{ Messages?: SqsMessage[] }>;\n  deleteMessage(input: { QueueUrl: string; ReceiptHandle: string }): Promise<unknown>;\n}\n\n// --- Attribute projection (contract §3.2) --------------------------------------\n\nconst str = (value: unknown): SqsMessageAttributeValue => ({\n  DataType: \"String\",\n  StringValue: String(value),\n});\nconst num = (value: unknown): SqsMessageAttributeValue => ({\n  DataType: \"Number\",\n  StringValue: String(value),\n});\n\n/**\n * Project the envelope's contract fields onto native SQS `MessageAttributes` — a\n * redundant, routable view of the body (the body stays authoritative).\n */\nexport function toMessageAttributes(envelope: Envelope): Record<string, SqsMessageAttributeValue> {\n  const attrs: Record<string, SqsMessageAttributeValue> = {};\n  if (envelope.job) attrs[\"bq-job\"] = str(envelope.job);\n  if (envelope.trace_id) attrs[\"bq-trace-id\"] = str(envelope.trace_id);\n  if (envelope.meta.id) attrs[\"bq-message-id\"] = str(envelope.meta.id);\n  if (envelope.meta.schema_version != null) {\n    attrs[\"bq-schema-version\"] = num(envelope.meta.schema_version);\n  }\n  if (envelope.meta.lang) attrs[\"bq-source-lang\"] = str(envelope.meta.lang);\n  if (envelope.meta.created_at != null) {\n    attrs[\"bq-created-at\"] = num(envelope.meta.created_at);\n  }\n  return attrs;\n}\n\nfunction queueNameFromUrl(queueUrl: string): string {\n  const segments = queueUrl.split(\"/\").filter(Boolean);\n  return segments[segments.length - 1] ?? \"default\";\n}\n\n// --- Publisher -----------------------------------------------------------------\n\n/** Options for {@link SqsPublisher}. */\nexport interface SqsPublisherOptions {\n  /** Treat the queue as FIFO: set `MessageGroupId` and (unless content dedup) `MessageDeduplicationId`. */\n  fifo?: boolean;\n  /** FIFO ordering group (default: the queue name from the URL). */\n  messageGroupId?: string;\n  /** Use the queue's content-based dedup instead of `meta.id` as the dedup id. */\n  contentDedup?: boolean;\n}\n\n/** Options for {@link SqsPublisher.publish}. */\nexport interface PublishOptions {\n  /** Reuse an existing trace id (trace continuation). */\n  traceId?: string;\n}\n\n/** Sends canonical-envelope messages to one SQS queue with the §3 attribute projection. */\nexport class SqsPublisher {\n  constructor(\n    private readonly client: SqsApi,\n    private readonly queueUrl: string,\n    private readonly options: SqsPublisherOptions = {},\n  ) {}\n\n  /**\n   * Build the canonical envelope for `(urn, data)`, send it as the message body with\n   * the projected `MessageAttributes`, and return the message id (`meta.id`).\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: queueNameFromUrl(this.queueUrl),\n      traceId: options.traceId,\n    });\n    const input: SendMessageInput = {\n      QueueUrl: this.queueUrl,\n      MessageBody: EnvelopeCodec.encode(envelope),\n      MessageAttributes: toMessageAttributes(envelope),\n    };\n    if (this.options.fifo) {\n      input.MessageGroupId = this.options.messageGroupId ?? queueNameFromUrl(this.queueUrl);\n      if (!this.options.contentDedup) {\n        input.MessageDeduplicationId = envelope.meta.id;\n      }\n    }\n    await this.client.sendMessage(input);\n    return envelope.meta.id;\n  }\n}\n\n// --- Consumer ------------------------------------------------------------------\n\n/** A URN handler. Receives the validated envelope and the raw SQS message. */\nexport type BabelHandler = (envelope: Envelope, message: SqsMessage) => unknown | Promise<unknown>;\n\n/** A map of URN → handler. */\nexport type BabelHandlers = Record<string, BabelHandler>;\n\n/** Options for {@link SqsConsumer}. */\nexport interface SqsConsumerOptions {\n  /** Called instead of erroring when a message's URN has no handler (then the message is deleted). */\n  onUnknownUrn?: (envelope: IncomingEnvelope, message: SqsMessage) => 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: SqsMessage) => void;\n  /** Long-poll wait seconds (default 20). */\n  waitTimeSeconds?: number;\n  /** Reservation window applied on receive (seconds). */\n  visibilityTimeout?: number;\n  /** Max messages per receive (default 10). */\n  maxMessages?: number;\n}\n\n/**\n * Polls an SQS queue, decodes + validates each message, routes it to the handler\n * registered for its URN, and deletes it on success. A throwing handler leaves the\n * message undeleted — SQS redelivers it after the visibility timeout (at-least-once);\n * `attempts` is reconciled to `ApproximateReceiveCount − 1` for the handler.\n */\nexport class SqsConsumer {\n  constructor(\n    private readonly client: SqsApi,\n    private readonly queueUrl: string,\n    private readonly handlers: BabelHandlers,\n    private readonly options: SqsConsumerOptions = {},\n  ) {}\n\n  /** Receive one batch, route each message, delete the ones handled. Returns the batch size. */\n  async poll(): Promise<number> {\n    const input: ReceiveMessageInput = {\n      QueueUrl: this.queueUrl,\n      MaxNumberOfMessages: this.options.maxMessages ?? 10,\n      WaitTimeSeconds: this.options.waitTimeSeconds ?? 20,\n      MessageAttributeNames: [\"All\"],\n      AttributeNames: [\"ApproximateReceiveCount\"],\n    };\n    if (this.options.visibilityTimeout != null) {\n      input.VisibilityTimeout = this.options.visibilityTimeout;\n    }\n    const result = await this.client.receiveMessage(input);\n    const messages = result.Messages ?? [];\n    for (const message of messages) {\n      await this.handle(message);\n    }\n    return messages.length;\n  }\n\n  /** Poll until `signal` aborts (each poll long-polls, so this does not busy-loop). */\n  async run(signal?: AbortSignal): Promise<void> {\n    while (signal?.aborted !== true) {\n      await this.poll();\n    }\n  }\n\n  private async handle(message: SqsMessage): Promise<void> {\n    const envelope = EnvelopeCodec.decode(message.Body ?? \"\");\n\n    const receiveCount = message.Attributes?.[\"ApproximateReceiveCount\"];\n    if (receiveCount !== undefined) {\n      const native = Number.parseInt(receiveCount, 10) - 1;\n      const current = typeof envelope.attempts === \"number\" ? envelope.attempts : 0;\n      if (Number.isFinite(native) && native > current) {\n        envelope.attempts = native;\n      }\n    }\n\n    if (!EnvelopeCodec.accepts(envelope)) {\n      this.options.onError?.(\n        new BabelQueueError(\"Rejected a non-conformant BabelQueue envelope from SQS.\"),\n        envelope,\n        message,\n      );\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.delete(message);\n      } else {\n        this.options.onError?.(new UnknownUrnError(urn), envelope, message);\n      }\n      return;\n    }\n\n    try {\n      await handler(envelope, message);\n      await this.delete(message);\n    } catch (error) {\n      // Leave the message undeleted — SQS redelivers after the visibility timeout.\n      this.options.onError?.(error, envelope, message);\n    }\n  }\n\n  private async delete(message: SqsMessage): Promise<void> {\n    if (!message.ReceiptHandle) return;\n    await this.client.deleteMessage({\n      QueueUrl: this.queueUrl,\n      ReceiptHandle: message.ReceiptHandle,\n    });\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@babelqueue/sqs",
+  "version": "1.0.0",
+  "description": "Amazon SQS adapter for BabelQueue — canonical-envelope publisher and a URN-routed consumer.",
+  "keywords": ["babelqueue", "sqs", "aws", "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/sqs"
+  },
+  "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": {
+    "@aws-sdk/client-sqs": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-sqs": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}