@spine-event-engine/delivery-client 2.0.0-snapshot.2

package/dist/client/shard-observation.js

@@ -0,0 +1,178 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+var _a;
+import { DeliveryProtocolError, DeliveryShardObservationError, ShardObservationOverflowError, } from "./types.js";
+/**
+ * Buffers one bounded, reconnecting remote shard-observation stream.
+ */
+export class ShardObservationStream {
+    config;
+    #values = [];
+    #waiters = [];
+    #error;
+    #done = false;
+    /**
+     * Creates and begins an observation stream.
+     * @param config Supplies bounded transport, decoding, and cleanup operations.
+     */
+    constructor(config) {
+        this.config = config;
+        void this.#pump();
+    }
+    /**
+     * Cancels this stream and releases its local resources.
+     */
+    cancel() {
+        if (this.#done)
+            return;
+        this.config.cancel();
+        this.#finish();
+    }
+    /**
+     * Returns this stream's async iterator.
+     * @returns An iterator that yields detached observations.
+     */
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => this.#next(),
+            return: () => {
+                this.cancel();
+                return Promise.resolve({ done: true, value: undefined });
+            },
+        };
+    }
+    async #pump() {
+        try {
+            for (let attempt = 0;; attempt++) {
+                try {
+                    await this.#observeAttempt();
+                }
+                catch (error) {
+                    if (this.config.signal.aborted)
+                        return;
+                    if (error instanceof DeliveryProtocolError ||
+                        error instanceof ShardObservationOverflowError)
+                        throw error;
+                    if (attempt === this.config.reconnects)
+                        throw new DeliveryShardObservationError();
+                    await _a.#pause(this.config.reconnectBackoffMs, this.config.signal);
+                }
+            }
+        }
+        catch (error) {
+            if (!this.config.signal.aborted)
+                this.#error = error instanceof Error ? error : new DeliveryShardObservationError();
+        }
+        finally {
+            this.#finish();
+        }
+    }
+    async #observeAttempt() {
+        const setup = new AbortController();
+        const abort = () => {
+            setup.abort(this.config.signal.reason);
+        };
+        this.config.signal.addEventListener("abort", abort, { once: true });
+        const timeout = setTimeout(() => {
+            setup.abort(new DeliveryShardObservationError());
+        }, this.config.setupTimeoutMs);
+        try {
+            let acknowledged = false;
+            for await (const frame of this.config.open(setup.signal)) {
+                if (!acknowledged) {
+                    if (!this.config.acknowledge(frame))
+                        throw new DeliveryProtocolError();
+                    acknowledged = true;
+                    clearTimeout(timeout);
+                    continue;
+                }
+                this.#push(this.config.decodeUpdate(frame));
+            }
+            throw new DeliveryShardObservationError();
+        }
+        finally {
+            clearTimeout(timeout);
+            this.config.signal.removeEventListener("abort", abort);
+        }
+    }
+    #push(value) {
+        if (this.#waiters.length > 0) {
+            const waiter = this.#waiters.shift();
+            if (waiter === undefined)
+                throw new DeliveryShardObservationError();
+            waiter({ done: false, value });
+            return;
+        }
+        if (this.#values.length >= this.config.capacity)
+            throw new ShardObservationOverflowError();
+        this.#values.push(value);
+    }
+    #next() {
+        if (this.#error !== undefined)
+            return Promise.reject(this.#error);
+        const value = this.#values.shift();
+        if (value !== undefined)
+            return Promise.resolve({ done: false, value });
+        if (this.#done)
+            return Promise.resolve({ done: true, value: undefined });
+        if (this.#waiters.length >= this.config.capacity) {
+            const error = new ShardObservationOverflowError();
+            this.#error = error;
+            this.config.cancel();
+            this.#finish();
+            return Promise.reject(error);
+        }
+        return new Promise((resolve) => this.#waiters.push(resolve)).then((result) => {
+            if (this.#error !== undefined)
+                throw this.#error;
+            return result;
+        });
+    }
+    #finish() {
+        if (this.#done)
+            return;
+        this.#done = true;
+        this.config.finish();
+        const result = { done: true, value: undefined };
+        for (const resolve of this.#waiters.splice(0))
+            resolve(result);
+    }
+    static #pause(delay, signal) {
+        if (delay === 0)
+            return signal.aborted
+                ? Promise.reject(signal.reason instanceof Error
+                    ? signal.reason
+                    : new Error("Delivery observation aborted."))
+                : Promise.resolve();
+        return new Promise((resolve, reject) => {
+            const finish = (reason) => {
+                signal.removeEventListener("abort", abort);
+                if (reason === undefined)
+                    resolve();
+                else
+                    reject(reason);
+            };
+            const timer = setTimeout(finish, delay);
+            const abort = () => {
+                clearTimeout(timer);
+                finish(signal.reason instanceof Error
+                    ? signal.reason
+                    : new Error("Delivery observation aborted."));
+            };
+            signal.addEventListener("abort", abort, { once: true });
+        });
+    }
+}
+_a = ShardObservationStream;
+//# sourceMappingURL=shard-observation.js.map

package/dist/client/shard-observation.js.map

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

package/dist/client/types.d.ts

@@ -0,0 +1,229 @@
+import { ShardIndex } from "@spine-event-engine/server";
+/**
+ * Stable public worker identity represented by the frozen `WorkerId` wire type.
+ * `nodeId` and `value` must be non-blank and together occupy at most 128 UTF-8 bytes.
+ */
+export interface DeliveryWorkerId {
+    /**
+     * Identifies the application node that owns this worker.
+     */
+    readonly nodeId: string;
+    /**
+     * Identifies this worker within its application node.
+     */
+    readonly value: string;
+}
+/**
+ * A remote exclusive shard session that can be released by this client.
+ */
+export interface RemoteShardSession {
+    /**
+     * Identifies the exclusive session kind accepted by the remote service.
+     */
+    readonly kind: "EXCLUSIVE";
+    /**
+     * Identifies the shard held by this session.
+     */
+    readonly shard: ShardIndex;
+    /**
+     * Identifies the worker that acquired this session.
+     */
+    readonly worker: DeliveryWorkerId;
+    /**
+     * Records when the remote service granted the session.
+     */
+    readonly whenPicked: Date;
+}
+/**
+ * A detached observation of a session released for inactivity.
+ */
+export interface ReleasedShardSession extends RemoteShardSession {
+    /**
+     * Records when the remote service released the inactive session.
+     */
+    readonly whenReleased: Date;
+}
+/**
+ * A detached Admin observation of one remote delivery shard.
+ */
+export interface RemoteShardObservation {
+    /**
+     * Identifies the observed shard.
+     */
+    readonly shard: ShardIndex;
+    /**
+     * Describes whether the shard is currently held.
+     */
+    readonly status: "PICKED" | "NOT_PICKED";
+    /**
+     * Records the most recent pickup when the server provides it.
+     */
+    readonly lastPicked?: Date;
+    /**
+     * Counts messages currently reported for the shard.
+     */
+    readonly messages: number;
+}
+/**
+ * Maximum serialized command or event envelope accepted from the delivery server.
+ */
+export declare const MAX_INBOX_PAYLOAD_BYTES: 1048576;
+/**
+ * Hard maximum number of messages accepted by one delivery batch mutation.
+ */
+export declare const MAX_DELIVERY_BATCH_MESSAGES = 100;
+/**
+ * Maximum serialized delivery RPC request or page response accepted by this client.
+ */
+export declare const MAX_DELIVERY_RPC_BYTES: 4194304;
+/**
+ * Maximum shard observations accepted from the in-memory delivery server.
+ */
+export declare const MAX_DELIVERY_TRACKED_SHARDS = 1000;
+/**
+ * Maximum combined UTF-8 bytes of one worker and node identity.
+ */
+export declare const MAX_DELIVERY_WORKER_BYTES = 128;
+/**
+ * Raised when a frozen delivery-server response cannot be represented safely.
+ */
+export declare class DeliveryProtocolError extends Error {
+    /**
+     * Creates an error for an invalid delivery-server response.
+     */
+    constructor();
+}
+/**
+ * Raised when the timestamp-only delivery wire page cannot continue without loss.
+ */
+export declare class DeliveryPagingError extends Error {
+    /**
+     * Creates an error for a page that cannot continue safely.
+     */
+    constructor();
+}
+/**
+ * Raised when a slow observer exceeds the bounded shard-update buffer.
+ */
+export declare class ShardObservationOverflowError extends Error {
+    /**
+     * Creates an error for a full shard-observation buffer.
+     */
+    constructor();
+}
+/**
+ * Raised when a shard observation stream ends without a usable recovery.
+ */
+export declare class DeliveryShardObservationError extends Error {
+    /**
+     * Creates an error for a failed shard-observation stream.
+     */
+    constructor();
+}
+/**
+ * Raised when a write may have reached the delivery server but its result was lost.
+ */
+export declare class DeliveryOutcomeUnknownError extends Error {
+    /**
+     * Identifies the mutation whose remote outcome could not be established.
+     */
+    readonly operation: "WRITE_ONE" | "WRITE_MANY" | "REMOVE_ONE" | "REMOVE_MANY" | "PICK_UP_SHARD" | "RELEASE_SHARD" | "RELEASE_EXPIRED";
+    /**
+     * Identifies the observation required to reconcile the mutation outcome.
+     */
+    readonly reconciliation: Readonly<{
+        readonly kind: "FIND_MESSAGE";
+        readonly messageIds: readonly string[];
+    } | {
+        readonly kind: "OBSERVE_SHARD";
+        readonly shards: readonly ShardIndex[];
+    } | {
+        readonly kind: "OBSERVE_SHARD";
+        readonly scope: "ALL_SHARDS";
+    }>;
+    /**
+     * Creates an error with the safe observation required before further action.
+     *
+     * @param operation Identifies the mutation with an unknown outcome.
+     * @param reconciliation Identifies messages or shards that must be observed.
+     */
+    constructor(operation: DeliveryOutcomeUnknownError["operation"], reconciliation: readonly string[] | readonly ShardIndex[] | "ALL_SHARDS");
+}
+/**
+ * Options for constructing a delivery client.
+ */
+export interface DeliveryClientOptions {
+    /**
+     * Limits messages requested in one read page.
+     */
+    readonly pageSize?: number;
+    /**
+     * Limits retries for safe read operations.
+     */
+    readonly readRetries?: number;
+    /**
+     * Delays each safe-read retry in milliseconds.
+     */
+    readonly retryBackoffMs?: number;
+    /**
+     * Limits reconnects for a shard-observation stream.
+     */
+    readonly observationReconnects?: number;
+    /**
+     * Delays each observation reconnect in milliseconds.
+     */
+    readonly observationReconnectBackoffMs?: number;
+    /**
+     * Limits queued observations and pending consumers.
+     */
+    readonly observationBufferSize?: number;
+}
+/**
+ * A cancellable, bounded stream of detached remote shard observations.
+ */
+export interface DeliveryShardObservationStream extends AsyncIterable<RemoteShardObservation> {
+    /**
+     * Cancels the observation stream and releases its local listeners.
+     */
+    cancel(): void;
+}
+/**
+ * Options for one side-effect-free read operation.
+ */
+export interface DeliveryFindOneOptions {
+    /**
+     * Cancels the operation when the caller no longer needs its result.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Limits finite reads and stream setup in milliseconds; it never limits an acknowledged active stream.
+     */
+    readonly timeoutMs?: number;
+}
+/**
+ * A bounded read page request; the wire contract can continue only by timestamp.
+ */
+export interface DeliveryReadPageOptions extends DeliveryFindOneOptions {
+    /**
+     * Continues a timestamp-ordered page after this received time.
+     */
+    readonly sinceWhen?: Date;
+    /**
+     * Limits messages requested for this page.
+     */
+    readonly pageSize?: number;
+}
+/**
+ * Options for one non-idempotent delivery mutation.
+ */
+export interface DeliveryMutationOptions {
+    /**
+     * Cancels the mutation before its transport call completes.
+     */
+    readonly signal?: AbortSignal;
+    /**
+     * Limits the mutation duration in milliseconds.
+     */
+    readonly timeoutMs?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

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

package/dist/client/types.js

@@ -0,0 +1,128 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+import { ShardIndex } from "@spine-event-engine/server";
+/**
+ * Maximum serialized command or event envelope accepted from the delivery server.
+ */
+export const MAX_INBOX_PAYLOAD_BYTES = 1_048_576;
+/**
+ * Hard maximum number of messages accepted by one delivery batch mutation.
+ */
+export const MAX_DELIVERY_BATCH_MESSAGES = 100;
+/**
+ * Maximum serialized delivery RPC request or page response accepted by this client.
+ */
+export const MAX_DELIVERY_RPC_BYTES = 4_194_304;
+/**
+ * Maximum shard observations accepted from the in-memory delivery server.
+ */
+export const MAX_DELIVERY_TRACKED_SHARDS = 1_000;
+/**
+ * Maximum combined UTF-8 bytes of one worker and node identity.
+ */
+export const MAX_DELIVERY_WORKER_BYTES = 128;
+/**
+ * Raised when a frozen delivery-server response cannot be represented safely.
+ */
+export class DeliveryProtocolError extends Error {
+    // prettier-ignore
+    /**
+     * Creates an error for an invalid delivery-server response.
+     */
+    constructor() {
+        super("Delivery server returned an invalid inbox message.");
+        this.name = "DeliveryProtocolError";
+    }
+}
+/**
+ * Raised when the timestamp-only delivery wire page cannot continue without loss.
+ */
+export class DeliveryPagingError extends Error {
+    // prettier-ignore
+    /**
+     * Creates an error for a page that cannot continue safely.
+     */
+    constructor() {
+        super("Delivery server page cannot be continued safely.");
+        this.name = "DeliveryPagingError";
+    }
+}
+/**
+ * Raised when a slow observer exceeds the bounded shard-update buffer.
+ */
+export class ShardObservationOverflowError extends Error {
+    // prettier-ignore
+    /**
+     * Creates an error for a full shard-observation buffer.
+     */
+    constructor() {
+        super("Delivery shard observation buffer overflowed.");
+        this.name = "ShardObservationOverflowError";
+    }
+}
+/**
+ * Raised when a shard observation stream ends without a usable recovery.
+ */
+export class DeliveryShardObservationError extends Error {
+    // prettier-ignore
+    /**
+     * Creates an error for a failed shard-observation stream.
+     */
+    constructor() {
+        super("Delivery shard observation stream failed.");
+        this.name = "DeliveryShardObservationError";
+    }
+}
+/**
+ * Raised when a write may have reached the delivery server but its result was lost.
+ */
+export class DeliveryOutcomeUnknownError extends Error {
+    // prettier-ignore
+    /**
+     * Identifies the mutation whose remote outcome could not be established.
+     */
+    operation;
+    /**
+     * Identifies the observation required to reconcile the mutation outcome.
+     */
+    reconciliation;
+    /**
+     * Creates an error with the safe observation required before further action.
+     *
+     * @param operation Identifies the mutation with an unknown outcome.
+     * @param reconciliation Identifies messages or shards that must be observed.
+     */
+    constructor(operation, reconciliation) {
+        super(operation === "WRITE_ONE" || operation === "WRITE_MANY"
+            ? "Delivery write outcome is unknown."
+            : operation === "REMOVE_ONE" || operation === "REMOVE_MANY"
+                ? "Delivery removal outcome is unknown."
+                : "Delivery shard operation outcome is unknown.");
+        this.name = "DeliveryOutcomeUnknownError";
+        this.operation = operation;
+        if (typeof reconciliation === "string")
+            this.reconciliation = Object.freeze({ kind: "OBSERVE_SHARD", scope: reconciliation });
+        else if (operation === "PICK_UP_SHARD" || operation === "RELEASE_SHARD")
+            this.reconciliation = Object.freeze({
+                kind: "OBSERVE_SHARD",
+                shards: Object.freeze(reconciliation.map((value) => new ShardIndex(value.index, value.ofTotal))),
+            });
+        else
+            this.reconciliation = Object.freeze({
+                kind: "FIND_MESSAGE",
+                messageIds: Object.freeze([...reconciliation]),
+            });
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAsFxD;;GAEG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAY,SAAS,CAAC;AAE1D;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,CAAC;AAE/C;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAY,SAAS,CAAC;AAEzD;;GAEG;AACH,MAAM,CAAC,MAAM,2BAA2B,GAAG,KAAK,CAAC;AAEjD;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,GAAG,CAAC;AAE7C;;GAEG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,kBAAkB;IAElB;;OAEG;IACH;QACE,KAAK,CAAC,oDAAoD,CAAC,CAAC;QAC5D,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAC5C,kBAAkB;IAElB;;OAEG;IACH;QACE,KAAK,CAAC,kDAAkD,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACtD,kBAAkB;IAElB;;OAEG;IACH;QACE,KAAK,CAAC,+CAA+C,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IACtD,kBAAkB;IAElB;;OAEG;IACH;QACE,KAAK,CAAC,2CAA2C,CAAC,CAAC;QACnD,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IACpD,kBAAkB;IAElB;;OAEG;IACM,SAAS,CAOI;IAEtB;;OAEG;IACM,cAAc,CAIrB;IAEF;;;;;OAKG;IACH,YACE,SAAmD,EACnD,cAAwE;QAExE,KAAK,CACH,SAAS,KAAK,WAAW,IAAI,SAAS,KAAK,YAAY;YACrD,CAAC,CAAC,oCAAoC;YACtC,CAAC,CAAC,SAAS,KAAK,YAAY,IAAI,SAAS,KAAK,aAAa;gBACzD,CAAC,CAAC,sCAAsC;gBACxC,CAAC,CAAC,8CAA8C,CACrD,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;QAC1C,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,IAAI,OAAO,cAAc,KAAK,QAAQ;YACpC,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAC;aACnF,IAAI,SAAS,KAAK,eAAe,IAAI,SAAS,KAAK,eAAe;YACrE,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;gBAClC,IAAI,EAAE,eAAe;gBACrB,MAAM,EAAE,MAAM,CAAC,MAAM,CAClB,cAAwC,CAAC,GAAG,CAC3C,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,CACtD,CACF;aACF,CAAC,CAAC;;YAEH,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC;gBAClC,IAAI,EAAE,cAAc;gBACpB,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAI,cAAoC,CAAC,CAAC;aACtE,CAAC,CAAC;IACP,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Public facade for the Node delivery-server client.
+ */
+export { DeliveryClient, DeliveryOutcomeUnknownError, DeliveryPagingError, DeliveryProtocolError, DeliveryShardObservationError, ShardObservationOverflowError, MAX_DELIVERY_BATCH_MESSAGES, MAX_DELIVERY_RPC_BYTES, MAX_INBOX_PAYLOAD_BYTES, } from "./client/client.js";
+export { RemoteInbox, RemoteWorkRegistry } from "./remote/adapters.js";
+export { RemoteDelivery, type RemoteDeliveryConfig } from "./remote/remote-delivery.js";
+export type { DeliveryClientOptions, DeliveryFindOneOptions, DeliveryMutationOptions, DeliveryReadPageOptions, DeliveryShardObservationStream, DeliveryWorkerId, ReleasedShardSession, RemoteShardObservation, RemoteShardSession, } from "./client/client.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":"AAcA;;GAEG;AACH,OAAO,EACL,cAAc,EACd,2BAA2B,EAC3B,mBAAmB,EACnB,qBAAqB,EACrB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,KAAK,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAExF,YAAY,EACV,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,uBAAuB,EACvB,8BAA8B,EAC9B,gBAAgB,EAChB,oBAAoB,EACpB,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -0,0 +1,20 @@
+/*
+ * Copyright 2026, CodeMatters. All rights reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
+ * in compliance with the License. You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under the License
+ * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+ * or implied. See the License for the specific language governing permissions and limitations under
+ * the License.
+ */
+/**
+ * Public facade for the Node delivery-server client.
+ */
+export { DeliveryClient, DeliveryOutcomeUnknownError, DeliveryPagingError, DeliveryProtocolError, DeliveryShardObservationError, ShardObservationOverflowError, MAX_DELIVERY_BATCH_MESSAGES, MAX_DELIVERY_RPC_BYTES, MAX_INBOX_PAYLOAD_BYTES, } from "./client/client.js";
+export { RemoteInbox, RemoteWorkRegistry } from "./remote/adapters.js";
+export { RemoteDelivery } from "./remote/remote-delivery.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;;;;;;;;;;;;GAYG;AAEH;;GAEG;AACH,OAAO,EACL,cAAc,EACd,2BAA2B,EAC3B,mBAAmB,EACnB,qBAAqB,EACrB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,sBAAsB,EACtB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,EAAE,cAAc,EAA6B,MAAM,6BAA6B,CAAC"}