@agirails/sdk 4.4.9 → 4.5.2

package/dist/delivery/RelayDeliveryChannel.js

@@ -0,0 +1,377 @@
+"use strict";
+/**
+ * AIP-16 Delivery Surface — RelayDeliveryChannel (Phase 2b)
+ * ===========================================================
+ *
+ * HTTP-backed {@link DeliveryChannel} implementation that talks to the
+ * AGIRAILS relay (or any compatible relay implementing the same REST
+ * surface) for posting and observing delivery setup + envelope wire
+ * objects.
+ *
+ * Mirrors the design of `src/negotiation/RelayChannel.ts`:
+ *
+ *  - POST / GET endpoints follow the same `/api/v1/delivery/...` shape
+ *    as the negotiation relay's `/api/v1/negotiations/...` endpoints.
+ *  - Subscriptions poll on a fixed interval (1000ms by default — slightly
+ *    faster than negotiation since delivery is the final-mile step the
+ *    requester is actively waiting on).
+ *  - Cursor pagination on GETs so a polling subscriber only sees new
+ *    items per tick.
+ *  - SSRF guard on `baseUrl` so a misconfigured agent cannot be steered
+ *    at cloud-metadata services, RFC1918 hosts, or loopback addresses
+ *    in production. `allowPrivateHosts: true` bypasses for dev / tests.
+ *  - 8-second timeout on every POST + GET via AbortController so a
+ *    hung relay cannot wedge the SDK indefinitely.
+ *  - Dedup-after-verify on read: each item is verified BEFORE its
+ *    identifier is added to the dedup set. An attacker who posts a
+ *    valid-looking-but-malformed wire to the relay cannot poison the
+ *    dedup set and suppress later legitimate items.
+ *  - Subscriber errors are caught + logged so one bad subscriber cannot
+ *    halt the polling loop.
+ *
+ * @module delivery/RelayDeliveryChannel
+ * @see {@link DeliveryChannel}
+ * @see ../negotiation/RelayChannel — reference pattern this mirrors.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelayDeliveryChannel = exports.REQUEST_TIMEOUT_MS = exports.POLL_INTERVAL_MS = void 0;
+const QuoteChannel_1 = require("../transport/QuoteChannel");
+const channelLog_1 = require("./channelLog");
+const envelopeBuilder_1 = require("./envelopeBuilder");
+const setupBuilder_1 = require("./setupBuilder");
+// ============================================================================
+// Constants
+// ============================================================================
+/**
+ * Default polling cadence for `subscribeSetups` / `subscribeEnvelopes`,
+ * in milliseconds. 1000ms balances snappy delivery (p95 latency below 1s
+ * per round trip) against poll-amplification cost when many parallel
+ * subscriptions are armed.
+ */
+exports.POLL_INTERVAL_MS = 1000;
+/**
+ * Default request timeout for POSTs and GETs to the relay, in milliseconds.
+ * 8000ms is short enough that a hung relay surfaces quickly but long
+ * enough that genuinely slow networks (mobile, satellite) don't
+ * spurious-abort under normal load.
+ */
+exports.REQUEST_TIMEOUT_MS = 8000;
+/** Default base URL — production AGIRAILS relay. */
+const DEFAULT_BASE_URL = 'https://agirails.app';
+// ============================================================================
+// RelayDeliveryChannel
+// ============================================================================
+/**
+ * HTTP relay-backed delivery channel. Production transport for AIP-16
+ * setups + envelopes.
+ *
+ * @example
+ * ```typescript
+ * const channel = new RelayDeliveryChannel({
+ *   baseUrl: 'https://agirails.app',
+ * });
+ * await channel.publishSetup(setupWire);
+ * const sub = await channel.subscribeEnvelopes(txId, async (env) => {
+ *   await processEnvelope(env);
+ * });
+ * // …later
+ * await sub.close();
+ * await channel.close();
+ * ```
+ */
+class RelayDeliveryChannel {
+    constructor(opts = {}) {
+        this.pollStates = new Set();
+        this.closed = false;
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
+        (0, QuoteChannel_1.assertSafePeerUrl)(this.baseUrl, opts.allowPrivateHosts ?? false);
+        this.pollIntervalMs = opts.pollIntervalMs ?? exports.POLL_INTERVAL_MS;
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? exports.REQUEST_TIMEOUT_MS;
+        this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.log = opts.log ?? channelLog_1.noopLog;
+        this.expectedKernelAddress = opts.expectedKernelAddress;
+        this.expectedChainId = opts.expectedChainId;
+        this.nowFn = opts.now;
+    }
+    // --------------------------------------------------------------------------
+    // publish
+    // --------------------------------------------------------------------------
+    async publishSetup(setup) {
+        if (this.closed) {
+            throw new Error('RelayDeliveryChannel: channel is closed');
+        }
+        const url = `${this.baseUrl}/api/v1/delivery/setup`;
+        await this.postJson(url, setup);
+    }
+    async publishEnvelope(envelope) {
+        if (this.closed) {
+            throw new Error('RelayDeliveryChannel: channel is closed');
+        }
+        const url = `${this.baseUrl}/api/v1/delivery`;
+        await this.postJson(url, envelope);
+    }
+    // --------------------------------------------------------------------------
+    // get
+    // --------------------------------------------------------------------------
+    async getSetups(txId, after) {
+        const url = new URL(`${this.baseUrl}/api/v1/delivery/setup/${encodeURIComponent(txId)}`);
+        if (after) {
+            url.searchParams.set('after', after);
+        }
+        const items = await this.getJson(url.toString());
+        return (items.items ?? []).map((item) => item.wire);
+    }
+    async getEnvelopes(txId, after) {
+        const url = new URL(`${this.baseUrl}/api/v1/delivery/${encodeURIComponent(txId)}`);
+        if (after) {
+            url.searchParams.set('after', after);
+        }
+        const items = await this.getJson(url.toString());
+        return (items.items ?? []).map((item) => item.wire);
+    }
+    // --------------------------------------------------------------------------
+    // subscribe
+    // --------------------------------------------------------------------------
+    async subscribeSetups(txId, callback) {
+        if (this.closed) {
+            throw new Error('RelayDeliveryChannel: channel is closed');
+        }
+        const state = {
+            cursor: null,
+            delivered: new Set(),
+            cancelled: false,
+        };
+        this.pollStates.add(state);
+        const pollOnce = async () => {
+            if (state.cancelled)
+                return;
+            try {
+                const url = new URL(`${this.baseUrl}/api/v1/delivery/setup/${encodeURIComponent(txId)}`);
+                if (state.cursor) {
+                    url.searchParams.set('after', state.cursor);
+                }
+                const body = await this.getJson(url.toString());
+                for (const item of body.items ?? []) {
+                    if (state.cancelled)
+                        break;
+                    await this.deliverSetup(item, state, callback);
+                    state.cursor = item.cursor;
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                this.log('warn', 'RelayDeliveryChannel: setup poll error', {
+                    txId,
+                    error: msg,
+                });
+            }
+            if (!state.cancelled) {
+                state.timer = setTimeout(pollOnce, this.pollIntervalMs);
+                // Allow process to exit even if subscription is still armed.
+                const t = state.timer;
+                if (typeof t.unref === 'function')
+                    t.unref();
+            }
+        };
+        state.timer = setTimeout(pollOnce, 0);
+        const t = state.timer;
+        if (typeof t.unref === 'function')
+            t.unref();
+        return {
+            close: () => {
+                state.cancelled = true;
+                if (state.timer)
+                    clearTimeout(state.timer);
+                this.pollStates.delete(state);
+            },
+        };
+    }
+    async subscribeEnvelopes(txId, callback) {
+        if (this.closed) {
+            throw new Error('RelayDeliveryChannel: channel is closed');
+        }
+        const state = {
+            cursor: null,
+            delivered: new Set(),
+            cancelled: false,
+        };
+        this.pollStates.add(state);
+        const pollOnce = async () => {
+            if (state.cancelled)
+                return;
+            try {
+                const url = new URL(`${this.baseUrl}/api/v1/delivery/${encodeURIComponent(txId)}`);
+                if (state.cursor) {
+                    url.searchParams.set('after', state.cursor);
+                }
+                const body = await this.getJson(url.toString());
+                for (const item of body.items ?? []) {
+                    if (state.cancelled)
+                        break;
+                    await this.deliverEnvelope(item, state, callback);
+                    state.cursor = item.cursor;
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                this.log('warn', 'RelayDeliveryChannel: envelope poll error', {
+                    txId,
+                    error: msg,
+                });
+            }
+            if (!state.cancelled) {
+                state.timer = setTimeout(pollOnce, this.pollIntervalMs);
+                const t = state.timer;
+                if (typeof t.unref === 'function')
+                    t.unref();
+            }
+        };
+        state.timer = setTimeout(pollOnce, 0);
+        const t = state.timer;
+        if (typeof t.unref === 'function')
+            t.unref();
+        return {
+            close: () => {
+                state.cancelled = true;
+                if (state.timer)
+                    clearTimeout(state.timer);
+                this.pollStates.delete(state);
+            },
+        };
+    }
+    // --------------------------------------------------------------------------
+    // close
+    // --------------------------------------------------------------------------
+    async close() {
+        this.closed = true;
+        for (const state of this.pollStates) {
+            state.cancelled = true;
+            if (state.timer)
+                clearTimeout(state.timer);
+        }
+        this.pollStates.clear();
+    }
+    // --------------------------------------------------------------------------
+    // Internals
+    // --------------------------------------------------------------------------
+    /**
+     * Deliver a single setup item — verify, dedup-after-verify, isolate
+     * subscriber errors.
+     */
+    async deliverSetup(item, state, callback) {
+        // Verify FIRST — dedup AFTER verify so a malformed sig cannot
+        // poison the dedup set.
+        const verifyResult = setupBuilder_1.DeliverySetupBuilder.verify(item.wire, {
+            expectedKernelAddress: this.expectedKernelAddress ?? item.wire.signed.kernelAddress,
+            expectedChainId: this.expectedChainId ?? item.wire.signed.chainId,
+            now: this.nowFn?.(),
+        });
+        if (!verifyResult.ok) {
+            this.log('warn', 'RelayDeliveryChannel: dropping unverified setup', {
+                code: verifyResult.code,
+                error: verifyResult.error,
+                txId: item.wire.signed.txId,
+            });
+            return;
+        }
+        const hash = setupBuilder_1.DeliverySetupBuilder.computeHash(item.wire);
+        if (state.delivered.has(hash))
+            return;
+        state.delivered.add(hash);
+        try {
+            await callback(item.wire);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.log('warn', 'RelayDeliveryChannel: setup subscriber threw', {
+                error: msg,
+                txId: item.wire.signed.txId,
+            });
+        }
+    }
+    /**
+     * Deliver a single envelope item — verify, dedup-after-verify, isolate
+     * subscriber errors.
+     */
+    async deliverEnvelope(item, state, callback) {
+        const verifyResult = envelopeBuilder_1.DeliveryEnvelopeBuilder.verify(item.wire, {
+            expectedKernelAddress: this.expectedKernelAddress ?? item.wire.signed.kernelAddress,
+            expectedChainId: this.expectedChainId ?? item.wire.signed.chainId,
+            now: this.nowFn?.(),
+        });
+        if (!verifyResult.ok) {
+            this.log('warn', 'RelayDeliveryChannel: dropping unverified envelope', {
+                code: verifyResult.code,
+                error: verifyResult.error,
+                txId: item.wire.signed.txId,
+            });
+            return;
+        }
+        const hash = envelopeBuilder_1.DeliveryEnvelopeBuilder.computeHash(item.wire);
+        if (state.delivered.has(hash))
+            return;
+        state.delivered.add(hash);
+        try {
+            await callback(item.wire);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            this.log('warn', 'RelayDeliveryChannel: envelope subscriber threw', {
+                error: msg,
+                txId: item.wire.signed.txId,
+            });
+        }
+    }
+    /**
+     * Issue a POST with JSON body and an AbortController-driven timeout.
+     * Resolves on 2xx, rejects on non-2xx with the response body as the
+     * error message.
+     */
+    async postJson(url, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+        try {
+            const res = await this.fetchImpl(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                this.log('warn', 'RelayDeliveryChannel: POST non-2xx', {
+                    url,
+                    status: res.status,
+                    body: text.slice(0, 256),
+                });
+                throw new Error(`RelayDeliveryChannel POST ${res.status}: ${text.slice(0, 200)}`);
+            }
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    /**
+     * Issue a GET and decode JSON, with an AbortController-driven timeout.
+     */
+    async getJson(url) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.requestTimeoutMs);
+        try {
+            const res = await this.fetchImpl(url, {
+                method: 'GET',
+                signal: controller.signal,
+            });
+            if (!res.ok) {
+                const text = await res.text().catch(() => '');
+                throw new Error(`RelayDeliveryChannel GET ${res.status}: ${text.slice(0, 200)}`);
+            }
+            return (await res.json());
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+exports.RelayDeliveryChannel = RelayDeliveryChannel;
+//# sourceMappingURL=RelayDeliveryChannel.js.map

package/dist/delivery/RelayDeliveryChannel.js.map

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

package/dist/delivery/channel.d.ts

@@ -0,0 +1,282 @@
+/**
+ * AIP-16 Delivery Surface — Channel Abstraction (Phase 2b)
+ * =========================================================
+ *
+ * Transport-agnostic interface for posting and observing delivery
+ * setup + envelope wire objects between requester and provider.
+ *
+ * The delivery channel is the wire-level boundary between the two
+ * participants of an AIP-16 delivery exchange. It does NOT participate
+ * in any cryptographic verification — its only job is to transport
+ * already-signed {@link DeliverySetupWireV1} and {@link DeliveryEnvelopeWireV1}
+ * objects between participants.
+ *
+ * ## Concrete implementations
+ *
+ *  - **MockDeliveryChannel** — in-process loopback used by tests and
+ *    MockRuntime flows. Implements dedup-after-verify on the read side
+ *    (see {@link MockChannel} in `src/negotiation/` for the reference
+ *    pattern). Useful for end-to-end tests without network setup.
+ *  - **RelayDeliveryChannel** — HTTP client against the AGIRAILS relay
+ *    (or any compatible relay implementing the same REST surface). Uses
+ *    cursor pagination, polling at `POLL_INTERVAL_MS = 1000`, and an
+ *    SSRF guard on the relay URL (see {@link RelayChannel} in
+ *    `src/negotiation/` for the reference pattern).
+ *
+ * ## Security invariants (binding on ALL implementations)
+ *
+ * 1. **Dedup AFTER verify.** Implementations that deduplicate
+ *    incoming setups/envelopes MUST verify signatures BEFORE adding any
+ *    identifier (txId, sig hash, etc.) to a dedup set. Otherwise an
+ *    attacker can post malformed signatures to permanently suppress
+ *    the legitimate signed object that arrives later.
+ *
+ * 2. **Subscriber error isolation.** Subscriber callbacks may throw
+ *    arbitrary errors (consumer code is not the channel's problem).
+ *    Implementations MUST catch and silently swallow callback errors —
+ *    NEVER propagate them into the channel's read loop, since one bad
+ *    subscriber would otherwise halt delivery for all other subscribers
+ *    sharing the same channel.
+ *
+ * 3. **No verification at the channel layer.** Channels do NOT call
+ *    `recoverSetupSigner` / `recoverEnvelopeSigner` or any other
+ *    cryptographic check. Verification is the consumer's responsibility
+ *    (typically via {@link DeliverySetupBuilder.verify} /
+ *    {@link DeliveryEnvelopeBuilder.verify}). The channel is a dumb pipe.
+ *
+ * 4. **Address comparison case-insensitivity.** Where addresses appear
+ *    in dedup keys (e.g. `signerAddress`), implementations MUST normalize
+ *    to lowercase on both sides of any comparison.
+ *
+ * ## Subscription semantics
+ *
+ *  - `subscribeSetups` / `subscribeEnvelopes` are scoped to a single
+ *    `txId`. A subscription begins emitting from "now" — that is, from
+ *    objects that are NOT already known to the channel at subscribe time
+ *    are guaranteed to be delivered; objects that ARE already known MAY
+ *    or MAY NOT be re-delivered depending on the implementation. Code
+ *    that needs the full historical set should call the optional
+ *    `getSetups` / `getEnvelopes` methods.
+ *
+ *  - Returning a {@link DeliverySubscription} whose `close()` is invoked
+ *    MUST stop further callbacks from firing on that subscription. It
+ *    SHOULD also free any underlying transport (polling timer, HTTP
+ *    connection, etc.).
+ *
+ *  - Multiple subscribers on the same `txId` MUST each receive all
+ *    matching objects (fan-out, not steal). One subscriber's `close()`
+ *    MUST NOT affect other subscribers.
+ *
+ * @module delivery/channel
+ * @see {@link DeliverySetupWireV1}
+ * @see {@link DeliveryEnvelopeWireV1}
+ */
+import type { DeliverySetupWireV1, DeliveryEnvelopeWireV1 } from './types';
+/**
+ * Handle returned from a `subscribe*` call. Calling `close()` cancels
+ * the subscription — the corresponding callback will not fire again.
+ *
+ * `close()` is idempotent: calling it multiple times is safe and a no-op
+ * after the first call. It MAY return a Promise (e.g. when the
+ * implementation needs to await an in-flight HTTP request); callers
+ * SHOULD `await` it when they need to confirm teardown completed
+ * before, e.g., asserting that no further callbacks fire.
+ *
+ * @example
+ * ```typescript
+ * const sub = await channel.subscribeEnvelopes(txId, async (env) => {
+ *   await processEnvelope(env);
+ * });
+ * // …later
+ * await sub.close();
+ * ```
+ */
+export interface DeliverySubscription {
+    /**
+     * Cancel this subscription. Idempotent. MAY return a Promise that
+     * resolves once the underlying transport (polling timer, HTTP
+     * connection) has been torn down.
+     */
+    close(): void | Promise<void>;
+}
+/**
+ * Callback fired for each verified-then-deduped setup observed on the
+ * channel for the subscribed `txId`.
+ *
+ * NOTE: "verified-then-deduped" is the dedup-after-verify ordering
+ * invariant — implementations call this callback only for setups whose
+ * signature has been verified (and which have not already been delivered
+ * to this subscriber).
+ *
+ * The callback MAY be async. Errors thrown from the callback (sync or
+ * async) MUST be caught and swallowed by the channel implementation —
+ * see security invariant #2 in the module-level JSDoc.
+ */
+export type SetupCallback = (setup: DeliverySetupWireV1) => void | Promise<void>;
+/**
+ * Callback fired for each verified-then-deduped envelope observed on
+ * the channel for the subscribed `txId`.
+ *
+ * Same semantics as {@link SetupCallback}: dedup-after-verify ordering,
+ * may be async, errors are isolated by the channel.
+ */
+export type EnvelopeCallback = (envelope: DeliveryEnvelopeWireV1) => void | Promise<void>;
+/**
+ * Transport-agnostic delivery channel.
+ *
+ * Implementations are responsible for transporting already-signed
+ * setup and envelope wire objects between requester and provider. The
+ * channel does NOT verify signatures, hashes, or schemes; that is the
+ * caller's responsibility (see the builder `verify()` methods).
+ *
+ * ## Contract summary
+ *
+ *  - `publishSetup` / `publishEnvelope` post a wire object to the
+ *    channel. Implementations MAY perform best-effort validation (e.g.
+ *    rejecting obviously malformed `txId` strings) but MUST NOT make
+ *    cryptographic verification a precondition of publish — the channel
+ *    is dumb on the write side, just as it is on the read side.
+ *
+ *  - `subscribeSetups` / `subscribeEnvelopes` register a callback that
+ *    fires for each verified-then-deduped object observed on the
+ *    channel for the given `txId`. Returns a {@link DeliverySubscription}
+ *    whose `close()` cancels the subscription.
+ *
+ *  - `getSetups` / `getEnvelopes` (optional) return the full set of
+ *    objects the channel currently knows about for a given `txId`.
+ *    Useful for "catch up to current state" flows where a participant
+ *    starts late and needs to see what was already posted. Implementations
+ *    that cannot enumerate prior state (e.g. fire-and-forget transports)
+ *    MAY omit these methods.
+ *
+ *  - `close()` (optional) releases all channel-level resources (e.g.
+ *    open HTTP connections, polling timers shared across subscriptions).
+ *    Implementations that have no global state MAY omit it.
+ *
+ * @example In-process loopback (MockRuntime tests)
+ * ```typescript
+ * const channel: DeliveryChannel = new MockDeliveryChannel();
+ *
+ * await channel.publishSetup(setupWire);
+ * const sub = await channel.subscribeEnvelopes(txId, async (env) => {
+ *   const result = await envelopeBuilder.verify(env);
+ *   if (result.valid) await consumeEnvelope(env);
+ * });
+ * // …later
+ * await sub.close();
+ * ```
+ *
+ * @example HTTP relay
+ * ```typescript
+ * const channel: DeliveryChannel = new RelayDeliveryChannel({
+ *   baseUrl: 'https://relay.agirails.io',
+ *   relayId: 'agirails-relay-v1',
+ * });
+ * await channel.publishEnvelope(envelopeWire);
+ * await channel.close?.();
+ * ```
+ */
+export interface DeliveryChannel {
+    /**
+     * Post a fully-signed {@link DeliverySetupWireV1} to the channel.
+     *
+     * Implementations SHOULD:
+     *  - Perform shape validation (txId is a 32-byte hex, signature is
+     *    65 bytes, etc.) and reject early on obvious malformations.
+     *  - NOT perform cryptographic verification — that is the verifier's
+     *    job, and pushing it down into the channel layer would tie the
+     *    transport to a specific kernel address / chainId universe.
+     *  - Surface transport-level errors as rejected Promises with a
+     *    structured `DeliveryError` of code `channel_post_failed` or
+     *    `channel_unreachable`, depending on the failure class.
+     *
+     * @param setup The setup wire object to publish.
+     * @returns A Promise that resolves once the channel has accepted
+     *   the publish (in a relay-backed implementation, after the relay
+     *   acknowledges the POST; in a loopback implementation, after the
+     *   in-memory write completes).
+     */
+    publishSetup(setup: DeliverySetupWireV1): Promise<void>;
+    /**
+     * Post a fully-signed {@link DeliveryEnvelopeWireV1} to the channel.
+     *
+     * Same contract as {@link publishSetup} — shape validation OK,
+     * crypto verification NOT permitted at this layer, transport errors
+     * surfaced as rejected Promises.
+     *
+     * @param envelope The envelope wire object to publish.
+     * @returns A Promise that resolves once the channel has accepted
+     *   the publish.
+     */
+    publishEnvelope(envelope: DeliveryEnvelopeWireV1): Promise<void>;
+    /**
+     * Subscribe to setups observed on the channel for a given `txId`.
+     *
+     * The callback fires once per verified-then-deduped setup
+     * (dedup-after-verify ordering, see module JSDoc). Multiple
+     * subscriptions on the same `txId` each receive all matching
+     * setups (fan-out).
+     *
+     * Callback errors are isolated per security invariant #2 — the
+     * channel MUST catch and swallow them, never propagating into its
+     * own read loop or affecting other subscribers.
+     *
+     * @param txId The transaction id to scope the subscription to,
+     *   as a `bytes32` hex-encoded string (`0x` + 64 hex chars).
+     * @param callback Invoked for each setup observed.
+     * @returns A {@link DeliverySubscription} whose `close()` cancels.
+     */
+    subscribeSetups(txId: `0x${string}`, callback: SetupCallback): Promise<DeliverySubscription>;
+    /**
+     * Subscribe to envelopes observed on the channel for a given `txId`.
+     *
+     * Same semantics as {@link subscribeSetups}.
+     *
+     * @param txId The transaction id to scope the subscription to.
+     * @param callback Invoked for each envelope observed.
+     * @returns A {@link DeliverySubscription} whose `close()` cancels.
+     */
+    subscribeEnvelopes(txId: `0x${string}`, callback: EnvelopeCallback): Promise<DeliverySubscription>;
+    /**
+     * Optional: return all setups the channel currently knows about for
+     * a given `txId`.
+     *
+     * Useful when a participant joins late and needs to see historical
+     * state. The returned array MUST be ordered by channel-observation
+     * order (oldest first) so callers can implement "process all then
+     * subscribe to new" flows deterministically.
+     *
+     * Implementations that cannot enumerate prior state (e.g.
+     * fire-and-forget transports, transports without server-side
+     * storage) MAY omit this method. Consumers MUST check for its
+     * presence (`if (channel.getSetups)`).
+     *
+     * @param txId The transaction id to fetch setups for.
+     * @returns All known setups for `txId`, oldest first.
+     */
+    getSetups?(txId: `0x${string}`): Promise<DeliverySetupWireV1[]>;
+    /**
+     * Optional: return all envelopes the channel currently knows about
+     * for a given `txId`. Same contract as {@link getSetups}.
+     *
+     * @param txId The transaction id to fetch envelopes for.
+     * @returns All known envelopes for `txId`, oldest first.
+     */
+    getEnvelopes?(txId: `0x${string}`): Promise<DeliveryEnvelopeWireV1[]>;
+    /**
+     * Optional: release any channel-level resources (HTTP connections,
+     * polling timers shared across subscriptions, etc.).
+     *
+     * After `close()` resolves, the channel MUST NOT fire any further
+     * subscriber callbacks and SHOULD reject any subsequent `publish*`
+     * call with `channel_unreachable`.
+     *
+     * Implementations with no global state (e.g. a pure in-memory
+     * loopback that closes per-subscription only) MAY omit this method.
+     *
+     * `close()` is idempotent: calling it multiple times is safe and
+     * a no-op after the first call.
+     */
+    close?(): void | Promise<void>;
+}
+//# sourceMappingURL=channel.d.ts.map

package/dist/delivery/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../../src/delivery/channel.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,SAAS,CAAC;AAMjB;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,oBAAoB;IACnC;;;;OAIG;IACH,KAAK,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAMD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjF;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,QAAQ,EAAE,sBAAsB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAM1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsDG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;;;;;;;;;;;;;OAkBG;IACH,YAAY,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;;;;;;;;OAUG;IACH,eAAe,CAAC,QAAQ,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjE;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,CACb,IAAI,EAAE,KAAK,MAAM,EAAE,EACnB,QAAQ,EAAE,aAAa,GACtB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEjC;;;;;;;;OAQG;IACH,kBAAkB,CAChB,IAAI,EAAE,KAAK,MAAM,EAAE,EACnB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAEjC;;;;;;;;;;;;;;;;OAgBG;IACH,SAAS,CAAC,CAAC,IAAI,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAEhE;;;;;;OAMG;IACH,YAAY,CAAC,CAAC,IAAI,EAAE,KAAK,MAAM,EAAE,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAAC;IAEtE;;;;;;;;;;;;;OAaG;IACH,KAAK,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC"}