@hexok/integration-events 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,136 @@
-# Temporary Holding Version
+# @hexok/integration-events
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Versioned events that cross a product or service boundary. Install with `npm i @hexok/integration-events`. It publishes and subscribes through the `@hexok/queue` port, so any `Queue` adapter carries it, such as `@hexok/queue-redis`.
+
+A domain event is internal to one application and changes with it. An integration event is a published contract between applications that deploy on their own. Map a domain event to an integration event at the edge. Do not publish the domain event.
+
+## Define the contract
+
+The producing product owns the contract. The contract file imports `@hexok/integration-events`, a schema library, and nothing else from the product. Consumers import it from a package the producer publishes, from a shared workspace, or from a copy.
+
+```ts
+import { Contract, Message } from '@hexok/integration-events';
+import { z } from 'zod';
+
+export class InvoicePaid extends Message('invoice.paid', 1, z.object({
+  invoiceId: z.string(),
+  amountCents: z.number().int(),
+})) {}
+
+export class InvoiceVoided extends Message('invoice.voided', 1, z.object({
+  invoiceId: z.string(),
+})) {}
+
+export class Billing extends Contract('billing', {
+  invoices: [InvoicePaid, InvoiceVoided],
+}) {}
+```
+
+`Message(type, version, schema)` is a hexok `Event` with a static and instance `version`. `parse` and `EventHandler` work on it.
+
+`Contract(name, topics)` maps each key to the message classes on that topic. The queue topic is `<name>.<key>`, here `billing.invoices`. Names match `/^[A-Za-z0-9_-]+$/`. `Contract` throws when a topic is empty, when a class is not a `Message`, when a class is in two topics, or when two classes share a type and version in one topic.
+
+## Publish
+
+```ts
+import { IntegrationPublisher } from '@hexok/integration-events';
+
+const billing = new IntegrationPublisher(Billing, { queue });
+await billing.publish(new InvoicePaid({ invoiceId: 'inv_1', amountCents: 500 }));
+```
+
+`publish` takes any message in the contract and finds its topic. It validates the payload and throws `CodedError` `VALIDATION` before anything is sent. It resolves the envelope `id`.
+
+Pass `{ id, time, subject }` to set those envelope attributes. `id` defaults to a random UUID. Pass a stable id, such as an outbox row id, so a retried publish carries the same id. `subject` is usually the aggregate id.
+
+Use cases depend on a port. `ContractEvent<typeof Billing>` is the union of messages the publisher accepts.
+
+```ts
+abstract publish(event: ContractEvent<typeof Billing>): Promise<string>;
+```
+
+## Subscribe
+
+```ts
+import { EventHandler } from 'hexok';
+import { IntegrationSubscriber, type IntegrationMeta } from '@hexok/integration-events';
+import { Billing, InvoicePaid } from '@acme/billing-contract';
+
+class SyncInvoice extends EventHandler('sync-invoice', InvoicePaid) {
+  async handle(event: InvoicePaid, meta?: IntegrationMeta): Promise<void> {
+    // meta.id to dedupe, meta.time and meta.subject to order
+  }
+}
+
+const billing = new IntegrationSubscriber(Billing, { queue, service: 'crm' });
+await billing.subscribe({ maxDeliveries: 10, handlers: [new SyncInvoice(deps)] });
+```
+
+`service` names the consuming application. Each handler subscribes to the topic of its message with its own consumer group, `<service>:<handler token>`. Two services never share a group, so each receives every event. A failing handler does not redeliver to the others.
+
+`subscribe` checks every handler before it subscribes any. It throws when a handler's message is not in the contract, or when two handlers would share a group on one topic. It resolves `{ topic, group, type, version }` for each subscription. `maxDeliveries` and `startFrom` pass through to `Queue.subscribe`.
+
+For each delivery:
+
+- An event of another type or version is acked and skipped.
+- A payload that is not an envelope, or data the message schema rejects, is logged, parked, and dropped. Pass a structural `logger` and `quarantine`. `@hexok/logger` and `@hexok/quarantine` fit them. A parked record has `source: 'integration-events'`, `operation: 'deliver'`, `subject` `topic:id`, and `context.group`. A schema rejection has `error.code` `VALIDATION`.
+- `handle` receives the event and an `IntegrationMeta` of `{ id, source, time, subject }`. A throw follows the queue's retry rules.
+
+Delivery is at least once. Make handlers idempotent with `meta.id`.
+
+## Versions
+
+An additive change, such as a new optional field, keeps the version. Consumer schemas must accept unknown fields. Zod, Valibot, and TypeBox objects accept them by default.
+
+A breaking change is a new version of the same type, with a downgrade to the previous version.
+
+```ts
+export class InvoicePaidV2 extends Message('invoice.paid', 2, z.object({
+  invoiceId: z.string(),
+  amount: z.object({ cents: z.number().int(), currency: z.string() }),
+}), {
+  downgrade: {
+    to: InvoicePaid,
+    map: (v2) => ({ invoiceId: v2.invoiceId, amountCents: v2.amount.cents }),
+  },
+}) {}
+
+export class Billing extends Contract('billing', {
+  invoices: [InvoicePaid, InvoicePaidV2, InvoiceVoided],
+}) {}
+```
+
+`map` is typed from both schemas. One `publish` of v2 sends v2, then v1. Every copy has the same `id`, `time`, and `subject`. Each payload is validated before it is downgraded, and a failure throws before anything is sent. A queue failure rejects `publish`, and copies already sent stay sent.
+
+`publish` accepts only the newest version. An older version is a type error, and it throws at runtime. `ContractEvent` leaves it out.
+
+The versions of one type in a topic form a chain. Each version downgrades to the one before it. `Contract` throws when a version has no downgrade, skips a version, or downgrades to a version that is not in the topic.
+
+To retire v1, move every consumer to v2. Then remove v1 from the topic and the downgrade from v2. Publish that as a major version of the contract.
+
+## Envelope
+
+The queue payload is a CloudEvents 1.0 event in structured JSON mode, with a `version` extension attribute. Applications in other languages read it as JSON.
+
+```json
+{
+  "specversion": "1.0",
+  "id": "7f8d3a5e-…",
+  "source": "billing",
+  "type": "invoice.paid",
+  "version": 1,
+  "time": "2026-11-05T12:00:00.000Z",
+  "subject": "inv_1",
+  "data": { "invoiceId": "inv_1", "amountCents": 500 }
+}
+```
+
+`subject` is present only when the publisher passed one.
+
+## What it leaves to the application
+
+- Retention. The queue adapter decides how long entries stay. With `@hexok/queue-redis`, the publisher's `retentionMs` and `maxLen` decide it, and a consumer that is down longer loses entries.
+- Backfill. A new consumer reaches only the entries the queue still holds. Load earlier state from the producer another way.
+- Order. A queue can redeliver an entry after newer ones. Put an aggregate version or timestamp in the payload, and ignore a change older than the state you hold.
+- The outbox. A crash between a database commit and `publish` loses the event. A transactional outbox prevents that. Pass the outbox row id as `id`.
+- Topic ownership. Grant the producer write access to its topics and consumers read access, in the broker.

package/dist/contract.d.ts

@@ -0,0 +1,49 @@
+import type { MessageConstructor } from './message.js';
+/** A topic as a {@link Contract} stores it. `name` is the queue topic. */
+export interface ContractTopic<Name extends string = string, Messages extends readonly MessageConstructor[] = readonly MessageConstructor[]> {
+    readonly name: Name;
+    readonly messages: Messages;
+}
+/** What `IntegrationPublisher` and `IntegrationSubscriber` read. */
+export interface ContractDefinition {
+    readonly token: string;
+    readonly topics: Readonly<Record<string, ContractTopic>>;
+}
+type ResolvedTopics<Name extends string, Topics extends Record<string, readonly MessageConstructor[]>> = {
+    readonly [K in keyof Topics & string]: ContractTopic<`${Name}.${K}`, Topics[K]>;
+};
+/** Every message class in a contract. */
+export type ContractMessage<C extends ContractDefinition> = C['topics'][keyof C['topics']]['messages'][number];
+type Superseded<M> = M extends {
+    readonly downgrade: {
+        readonly to: infer To;
+    };
+} ? To : never;
+/**
+ * Instance of a message a publisher accepts: every message in the contract
+ * except a version that a newer version downgrades to.
+ *
+ * ```ts
+ * abstract publish(event: ContractEvent<typeof Billing>): Promise<string>
+ * ```
+ */
+export type ContractEvent<C extends ContractDefinition> = InstanceType<Exclude<ContractMessage<C>, Superseded<ContractMessage<C>>>>;
+/**
+ * The published events of one product. Each key is a topic. Its queue topic is
+ * `<name>.<key>`. Each message class belongs to one topic. Versions of one type
+ * in a topic form a chain, where each version downgrades to the one before it.
+ *
+ * ```ts
+ * class Billing extends Contract('billing', {
+ *   invoices: [InvoicePaid, InvoiceVoided],
+ * }) {}
+ * ```
+ */
+export declare function Contract<const Name extends string, const Topics extends Record<string, readonly MessageConstructor[]>>(name: Name, topics: Topics): (abstract new () => {}) & {
+    /** Contract name. The envelope `source` and the queue topic prefix. */
+    readonly token: Name;
+    /** Topics by key. Each has its queue topic `name` and its `messages`. */
+    readonly topics: ResolvedTopics<Name, Topics>;
+};
+export {};
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIvD,0EAA0E;AAC1E,MAAM,WAAW,aAAa,CAC5B,IAAI,SAAS,MAAM,GAAG,MAAM,EAC5B,QAAQ,SACN,SAAS,kBAAkB,EAAE,GAAG,SAAS,kBAAkB,EAAE;IAE/D,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;CAC7B;AAED,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC,CAAC;CAC1D;AAED,KAAK,cAAc,CACjB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC,IAC1D;IACF,QAAQ,EAAE,CAAC,IAAI,MAAM,MAAM,GAAG,MAAM,GAAG,aAAa,CAClD,GAAG,IAAI,IAAI,CAAC,EAAE,EACd,MAAM,CAAC,CAAC,CAAC,CACV;CACF,CAAC;AAEF,yCAAyC;AACzC,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,kBAAkB,IACtD,CAAC,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,KAAK,UAAU,CAAC,CAAC,IAAI,CAAC,SAAS;IAC7B,QAAQ,CAAC,SAAS,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAC/C,GACG,EAAE,GACF,KAAK,CAAC;AAEV;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,kBAAkB,IAAI,YAAY,CACpE,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAC5D,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,QAAQ,CACtB,KAAK,CAAC,IAAI,SAAS,MAAM,EACzB,KAAK,CAAC,MAAM,SAAS,MAAM,CAAC,MAAM,EAAE,SAAS,kBAAkB,EAAE,CAAC,EAClE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM;IA+BxB,uEAAuE;oBAChD,IAAI;IAC3B,yEAAyE;qBACjD,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC;EAIvD"}

package/dist/contract.js

@@ -0,0 +1,84 @@
+const namePattern = /^[A-Za-z0-9_-]+$/;
+/**
+ * The published events of one product. Each key is a topic. Its queue topic is
+ * `<name>.<key>`. Each message class belongs to one topic. Versions of one type
+ * in a topic form a chain, where each version downgrades to the one before it.
+ *
+ * ```ts
+ * class Billing extends Contract('billing', {
+ *   invoices: [InvoicePaid, InvoiceVoided],
+ * }) {}
+ * ```
+ */
+export function Contract(name, topics) {
+    assertName('contract', name);
+    const owner = new Map();
+    const resolved = {};
+    for (const [key, messages] of Object.entries(topics)) {
+        assertName('topic', key);
+        const topic = `${name}.${key}`;
+        if (messages.length === 0) {
+            throw new Error(`integration-events: topic "${topic}" has no messages`);
+        }
+        for (const message of messages) {
+            assertMessage(topic, message);
+            const previous = owner.get(message);
+            if (previous !== undefined) {
+                throw new Error(`integration-events: "${message.token}" v${message.version} is in topics "${previous}" and "${topic}"`);
+            }
+            owner.set(message, topic);
+        }
+        assertVersionChains(topic, messages);
+        resolved[key] = Object.freeze({
+            name: topic,
+            messages: Object.freeze([...messages]),
+        });
+    }
+    const frozen = Object.freeze(resolved);
+    class ContractClass {
+        /** Contract name. The envelope `source` and the queue topic prefix. */
+        static token = name;
+        /** Topics by key. Each has its queue topic `name` and its `messages`. */
+        static topics = frozen;
+    }
+    return ContractClass;
+}
+function assertName(kind, name) {
+    if (typeof name !== 'string' || !namePattern.test(name)) {
+        throw new Error(`integration-events: ${kind} name "${String(name)}" must match ${namePattern}`);
+    }
+}
+function assertMessage(topic, message) {
+    const candidate = message;
+    if (typeof message !== 'function' ||
+        typeof candidate.token !== 'string' ||
+        typeof candidate.version !== 'number' ||
+        !('downgrade' in candidate)) {
+        throw new Error(`integration-events: topic "${topic}" holds a class that is not a Message`);
+    }
+}
+function assertVersionChains(topic, messages) {
+    const byType = new Map();
+    for (const message of messages) {
+        const versions = byType.get(message.token) ?? [];
+        versions.push(message);
+        byType.set(message.token, versions);
+    }
+    for (const [type, versions] of byType) {
+        versions.sort((a, b) => a.version - b.version);
+        versions.forEach((message, index) => {
+            const previous = versions[index - 1];
+            if (previous?.version === message.version) {
+                throw new Error(`integration-events: "${type}" v${message.version} is in topic "${topic}" twice`);
+            }
+            const to = message.downgrade?.to;
+            if (previous === undefined && to !== undefined) {
+                throw new Error(`integration-events: "${type}" v${message.version} downgrades to v${to.version}, which is not in topic "${topic}"`);
+            }
+            if (previous !== undefined && to !== previous) {
+                throw new Error(`integration-events: "${type}" v${message.version} must downgrade to the v${previous.version} in topic "${topic}"`);
+            }
+        });
+    }
+}
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"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"}

package/dist/envelope.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The queue payload of one integration event. It is a CloudEvents 1.0 event in
+ * structured JSON mode, with the `version` extension attribute.
+ */
+export interface IntegrationEnvelope {
+    readonly specversion: '1.0';
+    /** Shared by every version that one `publish` emits. */
+    readonly id: string;
+    /** Contract name. */
+    readonly source: string;
+    /** Message type. */
+    readonly type: string;
+    /** Message version. */
+    readonly version: number;
+    /** ISO 8601 timestamp. */
+    readonly time: string;
+    /** Present only when the publisher passed one, such as an aggregate id. */
+    readonly subject?: string;
+    readonly data: unknown;
+}
+/** Envelope attributes a handler receives as its second argument. */
+export interface IntegrationMeta {
+    readonly id: string;
+    readonly source: string;
+    readonly time: string;
+    readonly subject?: string;
+}
+/** The envelope, or `undefined` when `value` is not one. */
+export declare function readEnvelope(value: unknown): IntegrationEnvelope | undefined;
+export declare function metaOf(envelope: IntegrationEnvelope): IntegrationMeta;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/envelope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.d.ts","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,WAAW,EAAE,KAAK,CAAC;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oBAAoB;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uBAAuB;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0BAA0B;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,qEAAqE;AACrE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,4DAA4D;AAC5D,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,GAAG,SAAS,CAa5E;AAED,wBAAgB,MAAM,CAAC,QAAQ,EAAE,mBAAmB,GAAG,eAAe,CASrE"}

package/dist/envelope.js

@@ -0,0 +1,31 @@
+/** The envelope, or `undefined` when `value` is not one. */
+export function readEnvelope(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const entry = value;
+    if (entry.specversion !== '1.0')
+        return undefined;
+    for (const key of ['id', 'source', 'type', 'time']) {
+        if (typeof entry[key] !== 'string')
+            return undefined;
+    }
+    if (!Number.isSafeInteger(entry.version))
+        return undefined;
+    if (entry.subject !== undefined && typeof entry.subject !== 'string') {
+        return undefined;
+    }
+    if (!('data' in entry))
+        return undefined;
+    return value;
+}
+export function metaOf(envelope) {
+    const meta = {
+        id: envelope.id,
+        source: envelope.source,
+        time: envelope.time,
+    };
+    return envelope.subject === undefined
+        ? meta
+        : { ...meta, subject: envelope.subject };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/envelope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"envelope.js","sourceRoot":"","sources":["../src/envelope.ts"],"names":[],"mappings":"AA6BA,4DAA4D;AAC5D,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IAClE,MAAM,KAAK,GAAG,KAAgC,CAAC;IAC/C,IAAI,KAAK,CAAC,WAAW,KAAK,KAAK;QAAE,OAAO,SAAS,CAAC;IAClD,KAAK,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAU,EAAE,CAAC;QAC5D,IAAI,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;IACvD,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3D,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACrE,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACzC,OAAO,KAA4B,CAAC;AACtC,CAAC;AAED,MAAM,UAAU,MAAM,CAAC,QAA6B;IAClD,MAAM,IAAI,GAAG;QACX,EAAE,EAAE,QAAQ,CAAC,EAAE;QACf,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,IAAI,EAAE,QAAQ,CAAC,IAAI;KACpB,CAAC;IACF,OAAO,QAAQ,CAAC,OAAO,KAAK,SAAS;QACnC,CAAC,CAAC,IAAI;QACN,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;AAC7C,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { Contract, type ContractDefinition, type ContractEvent, type ContractMessage, type ContractTopic, } from './contract.js';
+export type { IntegrationEnvelope, IntegrationMeta } from './envelope.js';
+export { type Downgrade, Message, type MessageConstructor, type MessageInstance, type MessageOptions, type MessagePayload, } from './message.js';
+export { IntegrationPublisher, type PublishOptions } from './publisher.js';
+export { type IntegrationHandler, IntegrationSubscriber, type LogSink, type ParkInput, type ParkSink, type SubscribeOptions, type Subscription, } from './subscriber.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EACL,KAAK,SAAS,EACd,OAAO,EACP,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EACL,KAAK,kBAAkB,EACvB,qBAAqB,EACrB,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACrB,KAAK,YAAY,GAClB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { Contract, } from './contract.js';
+export { Message, } from './message.js';
+export { IntegrationPublisher } from './publisher.js';
+export { IntegrationSubscriber, } from './subscriber.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,GAKT,MAAM,eAAe,CAAC;AAEvB,OAAO,EAEL,OAAO,GAKR,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,oBAAoB,EAAuB,MAAM,gBAAgB,CAAC;AAC3E,OAAO,EAEL,qBAAqB,GAMtB,MAAM,iBAAiB,CAAC"}

package/dist/message.d.ts

@@ -0,0 +1,70 @@
+import { Event, type InferSchema, type SchemaSource, type StandardSchemaV1 } from 'hexok';
+/** Instance of a {@link Message} class. */
+export interface MessageInstance {
+    readonly token: string;
+    readonly version: number;
+    readonly payload: unknown;
+}
+/** A class made with {@link Message}. */
+export interface MessageConstructor {
+    /** Message type. The same type across versions. */
+    readonly token: string;
+    /** Positive integer. A breaking change is a new version. */
+    readonly version: number;
+    /** Payload schema. */
+    readonly schema: StandardSchemaV1;
+    /** How a payload of this version becomes the previous version. */
+    readonly downgrade: Downgrade | undefined;
+    /** Validate `value` and construct the message. */
+    parse(value: unknown): object;
+    new (...args: any[]): MessageInstance;
+}
+/** A downgrade as {@link MessageConstructor} stores it. */
+export interface Downgrade {
+    readonly to: MessageConstructor;
+    readonly map: (payload: never) => unknown;
+}
+/** Payload of a message class. */
+export type MessagePayload<M extends MessageConstructor> = InstanceType<M>['payload'];
+/**
+ * `to` is the previous version of the same type. `map` turns a payload of
+ * this version into a payload of `to`.
+ */
+export interface MessageOptions<S extends SchemaSource, To extends MessageConstructor> {
+    readonly downgrade: {
+        readonly to: To;
+        readonly map: (payload: InferSchema<S>) => MessagePayload<To>;
+    };
+}
+type DowngradeOf<S extends SchemaSource, To extends MessageConstructor> = [
+    To
+] extends [never] ? undefined : MessageOptions<S, To>['downgrade'];
+type EventBase<Type extends string, S extends SchemaSource> = ReturnType<typeof Event<Type, S>>;
+/**
+ * The class {@link Message} returns. It is the hexok `Event` class for `Type`
+ * and `S`, with a static and instance `version` and a static `downgrade`.
+ */
+export type MessageClass<Type extends string, Version extends number, S extends SchemaSource, To extends MessageConstructor> = {
+    new (payload: InferSchema<S>): InstanceType<EventBase<Type, S>> & {
+        readonly version: Version;
+    };
+} & Omit<EventBase<Type, S>, 'prototype'> & {
+    /** Version. Literal type of the number passed to {@link Message}. */
+    readonly version: Version;
+    /** The previous version and how to reach it. `undefined` without one. */
+    readonly downgrade: DowngradeOf<S, To>;
+};
+/**
+ * A versioned event that crosses a product or service boundary. It is a hexok
+ * `Event`, so `parse` and `EventHandler` work on it.
+ *
+ * ```ts
+ * class InvoicePaid extends Message('invoice.paid', 1, invoicePaidSchema) {}
+ * class InvoicePaidV2 extends Message('invoice.paid', 2, invoicePaidV2Schema, {
+ *   downgrade: { to: InvoicePaid, map: (v2) => ({ invoiceId: v2.id }) },
+ * }) {}
+ * ```
+ */
+export declare function Message<const Type extends string, const Version extends number, S extends SchemaSource, To extends MessageConstructor = never>(type: Type, version: Version, schema: S, options?: MessageOptions<S, To>): MessageClass<Type, Version, S, To>;
+export {};
+//# sourceMappingURL=message.d.ts.map

package/dist/message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.d.ts","sourceRoot":"","sources":["../src/message.ts"],"names":[],"mappings":"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"}

package/dist/message.js

@@ -0,0 +1,44 @@
+import { Event, } from 'hexok';
+/**
+ * A versioned event that crosses a product or service boundary. It is a hexok
+ * `Event`, so `parse` and `EventHandler` work on it.
+ *
+ * ```ts
+ * class InvoicePaid extends Message('invoice.paid', 1, invoicePaidSchema) {}
+ * class InvoicePaidV2 extends Message('invoice.paid', 2, invoicePaidV2Schema, {
+ *   downgrade: { to: InvoicePaid, map: (v2) => ({ invoiceId: v2.id }) },
+ * }) {}
+ * ```
+ */
+export function Message(type, version, schema, options) {
+    if (typeof type !== 'string' || type === '') {
+        throw new Error('integration-events: message type must be a string');
+    }
+    if (!Number.isSafeInteger(version) || version < 1) {
+        throw new Error(`integration-events: "${type}" version must be a positive integer`);
+    }
+    const downgrade = options?.downgrade;
+    if (downgrade !== undefined) {
+        assertDowngrade(type, version, downgrade);
+    }
+    const stored = (downgrade === undefined ? undefined : Object.freeze({ ...downgrade }));
+    class VersionedEvent extends Event(type, schema) {
+        static version = version;
+        static downgrade = stored;
+        version = version;
+    }
+    return VersionedEvent;
+}
+function assertDowngrade(type, version, downgrade) {
+    const to = downgrade.to;
+    if (typeof downgrade.to !== 'function' ||
+        to.token !== type ||
+        typeof to.version !== 'number' ||
+        to.version >= version) {
+        throw new Error(`integration-events: "${type}" v${version} must downgrade to an earlier version of "${type}"`);
+    }
+    if (typeof downgrade.map !== 'function') {
+        throw new Error(`integration-events: "${type}" v${version} downgrade map must be a function`);
+    }
+}
+//# sourceMappingURL=message.js.map

package/dist/message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.js","sourceRoot":"","sources":["../src/message.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,GAIN,MAAM,OAAO,CAAC;AA+Ef;;;;;;;;;;GAUG;AACH,MAAM,UAAU,OAAO,CAMrB,IAAU,EACV,OAAgB,EAChB,MAAS,EACT,OAA+B;IAE/B,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,KAAK,CACb,wBAAwB,IAAI,sCAAsC,CACnE,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,CAAC;IACrC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;QAC5B,eAAe,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAC5C,CAAC;IACD,MAAM,MAAM,GAAG,CACb,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,GAAG,SAAS,EAAE,CAAC,CAChD,CAAC;IAExB,MAAM,cAAe,SAAQ,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC;QAC9C,MAAM,CAAU,OAAO,GAAY,OAAO,CAAC;QAC3C,MAAM,CAAU,SAAS,GAAuB,MAAM,CAAC;QAC9C,OAAO,GAAY,OAAO,CAAC;;IAGtC,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,SAAS,eAAe,CACtB,IAAY,EACZ,OAAe,EACf,SAA0D;IAE1D,MAAM,EAAE,GAAG,SAAS,CAAC,EAGpB,CAAC;IACF,IACE,OAAO,SAAS,CAAC,EAAE,KAAK,UAAU;QAClC,EAAE,CAAC,KAAK,KAAK,IAAI;QACjB,OAAO,EAAE,CAAC,OAAO,KAAK,QAAQ;QAC9B,EAAE,CAAC,OAAO,IAAI,OAAO,EACrB,CAAC;QACD,MAAM,IAAI,KAAK,CACb,wBAAwB,IAAI,MAAM,OAAO,6CAA6C,IAAI,GAAG,CAC9F,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,SAAS,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QACxC,MAAM,IAAI,KAAK,CACb,wBAAwB,IAAI,MAAM,OAAO,mCAAmC,CAC7E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/publisher.d.ts

@@ -0,0 +1,37 @@
+import type { Queue } from '@hexok/queue';
+import type { ContractDefinition, ContractEvent } from './contract.js';
+/** Envelope attributes the caller may set. */
+export interface PublishOptions {
+    /** Defaults to a random UUID. Pass a stable id, such as an outbox row id, so a retry carries the same id. */
+    readonly id?: string;
+    /** Defaults to now. */
+    readonly time?: Date;
+    /** Such as the aggregate id. Omitted from the envelope when unset. */
+    readonly subject?: string;
+}
+/**
+ * Publishes a contract's messages to its topics through a `Queue`.
+ *
+ * ```ts
+ * const billing = new IntegrationPublisher(Billing, { queue });
+ * await billing.publish(new InvoicePaid({ invoiceId, amountCents }));
+ * ```
+ */
+export declare class IntegrationPublisher<C extends ContractDefinition> {
+    #private;
+    constructor(contract: C, deps: {
+        readonly queue: Queue;
+    });
+    /**
+     * Validate the payload, then publish it and one downgraded copy for each
+     * earlier version in the topic, newest first. Every copy has the same `id`,
+     * `time`, and `subject`. Resolves the `id`.
+     *
+     * Throws when the message is not in the contract, or when it has a newer
+     * version. Throws `CodedError` `VALIDATION` before publishing anything when
+     * a payload or a downgraded payload fails its schema. A queue failure
+     * rejects, and copies already published stay published.
+     */
+    publish(event: ContractEvent<C>, options?: PublishOptions): Promise<string>;
+}
+//# sourceMappingURL=publisher.d.ts.map

package/dist/publisher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publisher.d.ts","sourceRoot":"","sources":["../src/publisher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAE1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAIvE,8CAA8C;AAC9C,MAAM,WAAW,cAAc;IAC7B,6GAA6G;IAC7G,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,uBAAuB;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC;IACrB,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAoB,CAAC,CAAC,SAAS,kBAAkB;;gBAMhD,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;KAAE;IAYxD;;;;;;;;;OASG;IACG,OAAO,CACX,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,MAAM,CAAC;CAiCnB"}

package/dist/publisher.js

@@ -0,0 +1,90 @@
+import { randomUUID } from 'node:crypto';
+import { validate, validationError } from 'hexok';
+/**
+ * Publishes a contract's messages to its topics through a `Queue`.
+ *
+ * ```ts
+ * const billing = new IntegrationPublisher(Billing, { queue });
+ * await billing.publish(new InvoicePaid({ invoiceId, amountCents }));
+ * ```
+ */
+export class IntegrationPublisher {
+    #source;
+    #queue;
+    #topicOf = new Map();
+    #superseded = new Set();
+    constructor(contract, deps) {
+        this.#source = contract.token;
+        this.#queue = deps.queue;
+        for (const topic of Object.values(contract.topics)) {
+            for (const message of topic.messages) {
+                this.#topicOf.set(message, topic.name);
+                const to = message.downgrade?.to;
+                if (to !== undefined)
+                    this.#superseded.add(to);
+            }
+        }
+    }
+    /**
+     * Validate the payload, then publish it and one downgraded copy for each
+     * earlier version in the topic, newest first. Every copy has the same `id`,
+     * `time`, and `subject`. Resolves the `id`.
+     *
+     * Throws when the message is not in the contract, or when it has a newer
+     * version. Throws `CodedError` `VALIDATION` before publishing anything when
+     * a payload or a downgraded payload fails its schema. A queue failure
+     * rejects, and copies already published stay published.
+     */
+    async publish(event, options = {}) {
+        const instance = event;
+        const Newest = instance.constructor;
+        const topic = this.#topicOf.get(Newest);
+        if (topic === undefined) {
+            throw new Error(`integration-events: ${describe(event)} is not in contract "${this.#source}"`);
+        }
+        if (this.#superseded.has(Newest)) {
+            throw new Error(`integration-events: ${describe(event)} has a newer version in topic "${topic}"`);
+        }
+        const versions = chain(Newest, instance.payload);
+        const id = options.id ?? randomUUID();
+        const time = (options.time ?? new Date()).toISOString();
+        for (const { message, payload } of versions) {
+            const envelope = {
+                specversion: '1.0',
+                id,
+                source: this.#source,
+                type: message.token,
+                version: message.version,
+                time,
+                ...(options.subject !== undefined ? { subject: options.subject } : {}),
+                data: payload,
+            };
+            await this.#queue.publish(topic, envelope);
+        }
+        return id;
+    }
+}
+/** The payload at each version, newest first. Each payload is validated before it is downgraded. */
+function chain(newest, payload) {
+    const versions = [];
+    let message = newest;
+    let current = payload;
+    while (message !== undefined) {
+        const parsed = validate(message.schema, current);
+        if (!parsed.ok) {
+            throw validationError(`integration-events: "${message.token}" v${message.version} validation failed`, parsed.issues);
+        }
+        versions.push({ message, payload: current });
+        const downgrade = message.downgrade;
+        if (downgrade === undefined)
+            break;
+        current = downgrade.map(current);
+        message = downgrade.to;
+    }
+    return versions;
+}
+function describe(event) {
+    const { token, version } = event;
+    return `"${String(token)}" v${String(version)}`;
+}
+//# sourceMappingURL=publisher.js.map

package/dist/publisher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publisher.js","sourceRoot":"","sources":["../src/publisher.ts"],"names":[],"mappings":"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"}

package/dist/subscriber.d.ts

@@ -0,0 +1,79 @@
+import type { Queue, QueueMaxDeliveries, QueueStartFrom } from '@hexok/queue';
+import type { ContractDefinition, ContractMessage } from './contract.js';
+/** Structural logger. `@hexok/logger` and `console` fit it. */
+export interface LogSink {
+    error(message: string | Error, fields?: Record<string, unknown>): void;
+}
+/** Structurally `Quarantine.park`. This package does not import `@hexok/quarantine`. */
+export interface ParkInput {
+    readonly source: string;
+    readonly operation: string;
+    readonly subject?: string;
+    readonly payload: unknown;
+    readonly error: {
+        readonly name: string;
+        readonly message: string;
+        readonly code?: string;
+    };
+    readonly occurredAt: Date;
+    readonly context?: Readonly<Record<string, string>>;
+}
+export interface ParkSink {
+    park(input: ParkInput): Promise<{
+        id: string;
+    }>;
+}
+/**
+ * A constructed `EventHandler` for a message in the contract. `handle` is
+ * typed `never` so a mixed array still passes. `EventHandler` types the event.
+ */
+export interface IntegrationHandler<C extends ContractDefinition> {
+    readonly token: string;
+    readonly event: ContractMessage<C>;
+    handle(event: never, meta: never): Promise<void> | void;
+}
+export interface SubscribeOptions<C extends ContractDefinition> {
+    /** Passed to `Queue.subscribe` for each handler. */
+    readonly maxDeliveries: QueueMaxDeliveries;
+    /** Passed to `Queue.subscribe` for each handler. */
+    readonly startFrom?: QueueStartFrom;
+    readonly handlers: readonly IntegrationHandler<C>[];
+}
+/** One queue subscription that {@link IntegrationSubscriber.subscribe} made. */
+export interface Subscription {
+    readonly topic: string;
+    readonly group: string;
+    readonly type: string;
+    readonly version: number;
+}
+/**
+ * Subscribes `EventHandler`s to a contract's topics through a `Queue`. Each
+ * handler gets its own consumer group, `<service>:<handler token>`.
+ *
+ * ```ts
+ * const billing = new IntegrationSubscriber(Billing, { queue, service: 'crm' });
+ * await billing.subscribe({ maxDeliveries: 10, handlers: [new SyncInvoice(deps)] });
+ * ```
+ */
+export declare class IntegrationSubscriber<C extends ContractDefinition> {
+    #private;
+    constructor(contract: C, deps: {
+        readonly queue: Queue;
+        /** Name of the consuming service. Prefixes every consumer group. */
+        readonly service: string;
+        readonly logger?: LogSink;
+        readonly quarantine?: ParkSink;
+    });
+    /**
+     * Subscribe each handler to the topic of its message. Checks every handler
+     * before it subscribes any. Throws when a handler's message is not in the
+     * contract, or when two handlers would share a group on one topic.
+     *
+     * A delivery of another type or version is acked and skipped. A payload
+     * that is not an envelope, or data its schema rejects, is logged, parked
+     * when a quarantine sink is set, and dropped. A throw from `handle` follows
+     * the queue's retry rules.
+     */
+    subscribe(options: SubscribeOptions<C>): Promise<Subscription[]>;
+}
+//# sourceMappingURL=subscriber.d.ts.map

package/dist/subscriber.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriber.d.ts","sourceRoot":"","sources":["../src/subscriber.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,KAAK,EAEL,kBAAkB,EAElB,cAAc,EACf,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAMzE,+DAA+D;AAC/D,MAAM,WAAW,OAAO;IACtB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,KAAK,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACxE;AAED,wFAAwF;AACxF,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF,QAAQ,CAAC,UAAU,EAAE,IAAI,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,SAAS,kBAAkB;IAC9D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACzD;AAED,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,kBAAkB;IAC5D,oDAAoD;IACpD,QAAQ,CAAC,aAAa,EAAE,kBAAkB,CAAC;IAC3C,oDAAoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;IACpC,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC;CACrD;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAQD;;;;;;;;GAQG;AACH,qBAAa,qBAAqB,CAAC,CAAC,SAAS,kBAAkB;;gBAU3D,QAAQ,EAAE,CAAC,EACX,IAAI,EAAE;QACJ,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;QACtB,oEAAoE;QACpE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC;KAChC;IAsBH;;;;;;;;;OASG;IACG,SAAS,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CAoHvE"}

package/dist/subscriber.js

@@ -0,0 +1,145 @@
+import { CodedError } from 'hexok';
+import { metaOf, readEnvelope } from './envelope.js';
+const servicePattern = /^[A-Za-z0-9_-]+$/;
+/**
+ * Subscribes `EventHandler`s to a contract's topics through a `Queue`. Each
+ * handler gets its own consumer group, `<service>:<handler token>`.
+ *
+ * ```ts
+ * const billing = new IntegrationSubscriber(Billing, { queue, service: 'crm' });
+ * await billing.subscribe({ maxDeliveries: 10, handlers: [new SyncInvoice(deps)] });
+ * ```
+ */
+export class IntegrationSubscriber {
+    #contract;
+    #queue;
+    #service;
+    #logger;
+    #quarantine;
+    #topicOf = new Map();
+    #groups = new Set();
+    constructor(contract, deps) {
+        if (typeof deps.service !== 'string' ||
+            !servicePattern.test(deps.service)) {
+            throw new Error(`integration-events: service "${String(deps.service)}" must match ${servicePattern}`);
+        }
+        this.#contract = contract;
+        this.#queue = deps.queue;
+        this.#service = deps.service;
+        this.#logger = deps.logger;
+        this.#quarantine = deps.quarantine;
+        for (const topic of Object.values(contract.topics)) {
+            for (const message of topic.messages) {
+                this.#topicOf.set(message, topic.name);
+            }
+        }
+    }
+    /**
+     * Subscribe each handler to the topic of its message. Checks every handler
+     * before it subscribes any. Throws when a handler's message is not in the
+     * contract, or when two handlers would share a group on one topic.
+     *
+     * A delivery of another type or version is acked and skipped. A payload
+     * that is not an envelope, or data its schema rejects, is logged, parked
+     * when a quarantine sink is set, and dropped. A throw from `handle` follows
+     * the queue's retry rules.
+     */
+    async subscribe(options) {
+        const plans = this.#plan(options.handlers);
+        const subscriptions = [];
+        for (const plan of plans) {
+            const { topic, group } = plan.subscription;
+            await this.#queue.subscribe(topic, {
+                consumerGroup: group,
+                maxDeliveries: options.maxDeliveries,
+                ...(options.startFrom !== undefined
+                    ? { startFrom: options.startFrom }
+                    : {}),
+                handler: (message) => this.#deliver(plan, message),
+            });
+            this.#groups.add(groupKey(topic, group));
+            subscriptions.push(plan.subscription);
+        }
+        return subscriptions;
+    }
+    #plan(handlers) {
+        const planned = new Map();
+        for (const handler of handlers) {
+            const message = handler.event;
+            const topic = this.#topicOf.get(message);
+            if (topic === undefined) {
+                throw new Error(`integration-events: handler "${handler.token}" handles "${message.token}" v${message.version}, which is not in contract "${this.#contract.token}"`);
+            }
+            const group = `${this.#service}:${handler.token}`;
+            const key = groupKey(topic, group);
+            const previous = planned.get(key);
+            if (previous !== undefined || this.#groups.has(key)) {
+                throw new Error(`integration-events: group "${group}" on topic "${topic}" is already subscribed. Give each handler its own token`);
+            }
+            planned.set(key, {
+                handler,
+                message,
+                subscription: {
+                    topic,
+                    group,
+                    type: message.token,
+                    version: message.version,
+                },
+            });
+        }
+        return [...planned.values()];
+    }
+    async #deliver(plan, delivery) {
+        const envelope = readEnvelope(delivery.payload);
+        if (envelope === undefined) {
+            await this.#reject(plan, delivery, new Error('integration-events: entry is not an integration event'));
+            return 'drop';
+        }
+        const { message } = plan;
+        if (envelope.type !== message.token ||
+            envelope.version !== message.version) {
+            return 'ack';
+        }
+        let event;
+        try {
+            event = message.parse(envelope.data);
+        }
+        catch (error) {
+            if (error instanceof CodedError && error.code === 'VALIDATION') {
+                await this.#reject(plan, delivery, error);
+                return 'drop';
+            }
+            throw error;
+        }
+        await plan.handler.handle(event, metaOf(envelope));
+        return 'ack';
+    }
+    async #reject(plan, delivery, error) {
+        const { topic, group } = plan.subscription;
+        this.#logger?.error(error, { topic, group, id: delivery.id });
+        if (this.#quarantine === undefined)
+            return;
+        try {
+            await this.#quarantine.park({
+                source: 'integration-events',
+                operation: 'deliver',
+                subject: `${topic}:${delivery.id}`,
+                payload: delivery.payload,
+                error: error instanceof CodedError
+                    ? { name: error.name, message: error.message, code: error.code }
+                    : { name: error.name, message: error.message },
+                occurredAt: new Date(),
+                context: { group },
+            });
+        }
+        catch (parkError) {
+            this.#logger?.error(parkError instanceof Error
+                ? parkError
+                : new Error('integration-events: park failed'), { topic, group, id: delivery.id });
+        }
+    }
+}
+function groupKey(topic, group) {
+    return `${topic}\0${group}`;
+}
+//# sourceMappingURL=subscriber.js.map

package/dist/subscriber.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscriber.js","sourceRoot":"","sources":["../src/subscriber.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@hexok/integration-events",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Versioned events that cross product and service boundaries, over the hexok queue port.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "keywords": [
+    "hexok",
+    "integration-events",
+    "events",
+    "queue"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crobinson42/hexok.git",
+    "directory": "packages/integration-events"
+  },
+  "homepage": "https://crobinson42.github.io/hexok/",
+  "bugs": {
+    "url": "https://github.com/crobinson42/hexok/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run",
+    "type-check": "tsc --noEmit -p tsconfig.check.json",
+    "lint": "biome check .",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@hexok/queue": "^1.0.0",
+    "hexok": "^2.2.4"
+  },
+  "devDependencies": {
+    "@hexok/queue-redis": "^1.1.3",
+    "zod": "^4.1.5"
+  }
+}