@zlink-systems/stream-connector 0.10.0

package/LICENSE

@@ -0,0 +1,105 @@
+# Functional Source License, Version 1.1, ALv2 Future License
+
+## Abbreviation
+
+FSL-1.1-ALv2
+
+## Notice
+
+Copyright 2026 ZLink Systems
+
+## Terms and Conditions
+
+### Licensor ("We")
+
+The party offering the Software under these Terms and Conditions.
+
+### The Software
+
+The "Software" is each version of the software that we make available under
+these Terms and Conditions, as indicated by our inclusion of these Terms and
+Conditions with the Software.
+
+### License Grant
+
+Subject to your compliance with this License Grant and the Patents,
+Redistribution and Trademark clauses below, we hereby grant you the right to
+use, copy, modify, create derivative works, publicly perform, publicly display
+and redistribute the Software for any Permitted Purpose identified below.
+
+### Permitted Purpose
+
+A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
+means making the Software available to others in a commercial product or
+service that:
+
+1. substitutes for the Software;
+
+2. substitutes for any other product or service we offer using the Software
+   that exists as of the date we make the Software available; or
+
+3. offers the same or substantially similar functionality as the Software.
+
+Permitted Purposes specifically include using the Software:
+
+1. for your internal use and access;
+
+2. for non-commercial education;
+
+3. for non-commercial research; and
+
+4. in connection with professional services that you provide to a licensee
+   using the Software in accordance with these Terms and Conditions.
+
+### Patents
+
+To the extent your use for a Permitted Purpose would necessarily infringe our
+patents, the license grant above includes a license under our patents. If you
+make a claim against any party that the Software infringes or contributes to
+the infringement of any patent, then your patent license to the Software ends
+immediately.
+
+### Redistribution
+
+The Terms and Conditions apply to all copies, modifications and derivatives of
+the Software.
+
+If you redistribute any copies, modifications or derivatives of the Software,
+you must include a copy of or a link to these Terms and Conditions and not
+remove any copyright notices provided in or with the Software.
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
+PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
+
+IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
+SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
+EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
+
+### Trademarks
+
+Except for displaying the License Details and identifying us as the origin of
+the Software, you have no right under these Terms and Conditions to use our
+trademarks, trade names, service marks or product names.
+
+## Grant of Future License
+
+We hereby irrevocably grant you an additional license to use the Software under
+the Apache License, Version 2.0 that is effective on the second anniversary of
+the date we make the Software available. On or after that date, you may use the
+Software under the Apache License, Version 2.0, in which case the following
+will apply:
+
+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
+
+http://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.

package/dist/browser/Contracts/Calls/ZlinkStreamCalls.d.ts

@@ -0,0 +1,35 @@
+import type { ZlinkStreamMetadata } from '../ZlinkStreamMetadata';
+import type { ZlinkStreamEncodedPayload, ZlinkStreamFlow, ZlinkStreamMessage, ZlinkStreamResultOf } from '../ZlinkStreamModels';
+export interface ZlinkStreamSendCall {
+    packetName(name: string): ZlinkStreamSendCall;
+    metadata(key: string, value: string): ZlinkStreamSendCall;
+    metadata(metadata: ZlinkStreamMetadata): ZlinkStreamSendCall;
+    compress(): ZlinkStreamSendCall;
+    flowFrom(flow: ZlinkStreamFlow): ZlinkStreamSendCall;
+    submit(): Promise<void>;
+}
+export interface ZlinkStreamRequestCall {
+    packetName(name: string): ZlinkStreamRequestCall;
+    metadata(key: string, value: string): ZlinkStreamRequestCall;
+    metadata(metadata: ZlinkStreamMetadata): ZlinkStreamRequestCall;
+    timeout(timeoutMs: number): ZlinkStreamRequestCall;
+    compress(): ZlinkStreamRequestCall;
+    flowFrom(flow: ZlinkStreamFlow): ZlinkStreamRequestCall;
+    submit<TReply = unknown>(signal?: AbortSignal): Promise<TReply>;
+    submitEncoded(signal?: AbortSignal): Promise<ZlinkStreamEncodedPayload>;
+    submit(callback: (result: ZlinkStreamResultOf<ZlinkStreamEncodedPayload>) => void): void;
+}
+export interface ZlinkStreamWaitCall<TPayload = ZlinkStreamEncodedPayload> {
+    where(predicate: (message: ZlinkStreamMessage<TPayload>) => boolean): ZlinkStreamWaitCall<TPayload>;
+    timeout(timeoutMs: number): ZlinkStreamWaitCall<TPayload>;
+    submit(signal?: AbortSignal): Promise<ZlinkStreamMessage<TPayload>>;
+}
+export interface ZlinkStreamExpectNoneCall<TPayload = ZlinkStreamEncodedPayload> {
+    within(windowMs: number): ZlinkStreamExpectNoneCall<TPayload>;
+    run(signal?: AbortSignal): Promise<void>;
+}
+export interface ZlinkStreamSequenceCall<TPayload = ZlinkStreamEncodedPayload> {
+    expect(predicate: (payload: TPayload) => boolean): ZlinkStreamSequenceCall<TPayload>;
+    timeout(timeoutMs: number): ZlinkStreamSequenceCall<TPayload>;
+    run(signal?: AbortSignal): Promise<readonly TPayload[]>;
+}

package/dist/browser/Contracts/IZlinkStreamConnector.d.ts

@@ -0,0 +1,38 @@
+import type { Disposable } from './ZlinkStreamInterfaces';
+import type { RequiredZlinkStreamConnectorOptions } from './ZlinkStreamConnectorOptions';
+import type { ZlinkStreamRequestCall, ZlinkStreamSendCall, ZlinkStreamExpectNoneCall, ZlinkStreamSequenceCall, ZlinkStreamWaitCall } from './Calls/ZlinkStreamCalls';
+import type { ZlinkStreamConnectionStateChanged, ZlinkStreamEncodedPayload, ZlinkStreamError, ZlinkStreamInboundObservation, ZlinkStreamMessage } from './ZlinkStreamModels';
+import type { ZlinkStreamCloseReason, ZlinkStreamConnectionState, ZlinkStreamDiagnosticsLevel } from './ZlinkStreamEnums';
+export interface ZlinkStreamConnector {
+    readonly isConnected: boolean;
+    readonly state: ZlinkStreamConnectionState;
+    readonly closeReason?: ZlinkStreamCloseReason;
+    readonly options: RequiredZlinkStreamConnectorOptions;
+    readonly pendingDispatchCount: number;
+    /**
+     * Current diagnostics level (spec 26 §4.1, spec stream-connector 32 §13).
+     * Always equal to `options.diagnosticsLevel`.
+     */
+    readonly diagnosticsLevel: ZlinkStreamDiagnosticsLevel;
+    /**
+     * Changes the diagnostics level at runtime without recreating the
+     * connector (spec 26 §4.1, spec stream-connector 32 §13). Applies to
+     * processing points that read the level after this call returns; never
+     * applied retroactively to frames already built. Rejects unknown values
+     * with {@link import('./ZlinkStreamEnums').ZlinkStreamErrorCode.ConfigurationError}.
+     */
+    setDiagnosticsLevel(level: ZlinkStreamDiagnosticsLevel): void;
+    onErrorReceived(handler: (error: ZlinkStreamError, signal?: AbortSignal) => Promise<void> | void): Disposable;
+    onDisconnected(handler: (signal?: AbortSignal) => Promise<void> | void): Disposable;
+    onConnectionStateChanged(handler: (change: ZlinkStreamConnectionStateChanged, signal?: AbortSignal) => Promise<void> | void): Disposable;
+    connect(signal?: AbortSignal): Promise<void>;
+    close(signal?: AbortSignal): Promise<void>;
+    dispatch(signal?: AbortSignal): Promise<void>;
+    send(payload: unknown, messageType?: Function): ZlinkStreamSendCall;
+    request(payload: unknown, messageType?: Function): ZlinkStreamRequestCall;
+    observeInbound(observer: (observation: ZlinkStreamInboundObservation, signal?: AbortSignal) => Promise<void> | void): Disposable;
+    on<TPayload = ZlinkStreamEncodedPayload>(name: string, handler: (message: ZlinkStreamMessage<TPayload>, signal?: AbortSignal) => Promise<void> | void, messageType?: Function): Disposable;
+    waitFor<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamWaitCall<TPayload>;
+    expectNone<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamExpectNoneCall<TPayload>;
+    waitForSequence<TPayload = ZlinkStreamEncodedPayload>(name: string): ZlinkStreamSequenceCall<TPayload>;
+}

package/dist/browser/Contracts/ZlinkStreamConnectorOptions.d.ts

@@ -0,0 +1,99 @@
+import type { ZlinkStreamCompression, ZlinkStreamDiagnosticsLevel, ZlinkStreamDispatchMode, ZlinkStreamTransport } from './ZlinkStreamEnums';
+import type { ZlinkStreamEncodedPayload } from './ZlinkStreamModels';
+export interface ZlinkStreamConnectorOptions {
+    readonly endpoint: string;
+    readonly codec?: ZlinkStreamPayloadCodec;
+    readonly transport?: ZlinkStreamTransport;
+    readonly transportFactory?: ZlinkStreamTransportFactory;
+    readonly connectTimeoutMs?: number;
+    readonly requestTimeoutMs?: number;
+    readonly waitTimeoutMs?: number;
+    readonly heartbeat?: ZlinkStreamHeartbeatOptions;
+    readonly reconnect?: ZlinkStreamReconnectOptions;
+    readonly maxSendPayloadSize?: number;
+    readonly maxReceivePayloadSize?: number;
+    readonly maxReceivedMessages?: number;
+    readonly maxInboundObserverNotifications?: number;
+    readonly maxInboundObserverPayloadPreviewBytes?: number;
+    readonly dispatchMode?: ZlinkStreamDispatchMode;
+    readonly compression?: ZlinkStreamCompression;
+    readonly compressionCodec?: ZlinkStreamCompressionCodec;
+    readonly nameResolver?: ZlinkStreamPacketNameResolver;
+    readonly meterProvider?: ZlinkStreamMeterProvider;
+    /**
+     * Initial diagnostics level (spec 26 §4); defaults to
+     * {@link ZlinkStreamDiagnosticsLevel.Errors}, which preserves the current
+     * wire behavior. `Off` suppresses all observation-only flow handling
+     * (spec 27 §4). This is only the level at construction time — spec 26
+     * §4.1 / spec stream-connector 32 §13 require runtime read/write, provided
+     * by `ZlinkStreamConnector.diagnosticsLevel` / `setDiagnosticsLevel(...)`.
+     */
+    readonly diagnosticsLevel?: ZlinkStreamDiagnosticsLevel;
+}
+export interface ZlinkStreamMeterProvider {
+    getMeter(name: string): {
+        createCounter(name: string, options?: {
+            readonly unit?: string;
+        }): {
+            add(value: number, attributes?: Readonly<Record<string, string | number | boolean>>): void;
+        };
+        createHistogram(name: string, options?: {
+            readonly unit?: string;
+        }): {
+            record(value: number, attributes?: Readonly<Record<string, string | number | boolean>>): void;
+        };
+    };
+}
+export interface ZlinkStreamHeartbeatOptions {
+    readonly enabled?: boolean;
+    readonly intervalMs?: number;
+    readonly timeoutMs?: number;
+}
+export interface ZlinkStreamReconnectOptions {
+    readonly enabled?: boolean;
+    readonly initialDelayMs?: number;
+    readonly maxDelayMs?: number;
+    readonly backoffFactor?: number;
+    readonly maxAttempts?: number;
+}
+export interface ZlinkStreamPacketNameResolver {
+    resolve(payloadType: Function): string;
+}
+export interface ZlinkStreamPayloadCodec {
+    encode(payload: unknown, messageType?: Function): ZlinkStreamEncodedPayload;
+    decode<T = unknown>(payload: ZlinkStreamEncodedPayload, messageType?: Function): T;
+}
+export interface ZlinkStreamCompressionCodec {
+    compress(payload: Uint8Array): Uint8Array;
+    decompress(payload: Uint8Array, maxDecompressedSize: number): Uint8Array;
+}
+export interface ZlinkStreamTransportFactory {
+    connect(options: RequiredZlinkStreamConnectorOptions, signal?: AbortSignal): Promise<ZlinkStreamConnection>;
+}
+export interface ZlinkStreamConnection {
+    write(frame: Uint8Array, signal?: AbortSignal): Promise<void>;
+    read?(signal?: AbortSignal): Promise<Uint8Array | undefined>;
+    close(signal?: AbortSignal): Promise<void>;
+}
+export interface RequiredZlinkStreamConnectorOptions {
+    readonly endpoint: string;
+    readonly transport: ZlinkStreamTransport;
+    readonly connectTimeoutMs: number;
+    readonly requestTimeoutMs: number;
+    readonly waitTimeoutMs: number;
+    readonly heartbeat: Required<ZlinkStreamHeartbeatOptions>;
+    readonly reconnect: Required<ZlinkStreamReconnectOptions>;
+    readonly maxSendPayloadSize: number;
+    readonly maxReceivePayloadSize: number;
+    readonly maxReceivedMessages: number;
+    readonly maxInboundObserverNotifications: number;
+    readonly maxInboundObserverPayloadPreviewBytes: number;
+    readonly dispatchMode: ZlinkStreamDispatchMode;
+    readonly compression: ZlinkStreamCompression;
+    readonly compressionCodec?: ZlinkStreamCompressionCodec;
+    readonly nameResolver: ZlinkStreamPacketNameResolver;
+    readonly transportFactory: ZlinkStreamTransportFactory;
+    readonly codec?: ZlinkStreamPayloadCodec;
+    readonly meterProvider?: ZlinkStreamMeterProvider;
+    readonly diagnosticsLevel: ZlinkStreamDiagnosticsLevel;
+}

package/dist/browser/Contracts/ZlinkStreamEnums.d.ts

@@ -0,0 +1,69 @@
+export declare enum ZlinkStreamTransport {
+    WebSocket = "webSocket",
+    WebSocketSecure = "webSocketSecure"
+}
+export { ZlinkStreamCodec } from '@zlink-systems/stream-wire';
+export declare enum ZlinkStreamCompression {
+    None = "none",
+    Lz4 = "lz4"
+}
+export declare enum ZlinkStreamDispatchMode {
+    Manual = "manual",
+    Immediate = "immediate"
+}
+/**
+ * Connector diagnostics level (spec 26 §4). `Errors` is the default and
+ * preserves the connector's established wire behavior (outbound frames carry
+ * the flow pair). `Off` applies spec 27 §4: no flow id is generated or
+ * attached to outbound frames (header flag 0x10 stays clear), inbound flow
+ * fields are neither validated nor installed into received messages
+ * (structural length checks are kept), and no trace-only work runs.
+ */
+export declare enum ZlinkStreamDiagnosticsLevel {
+    Off = "off",
+    Errors = "errors",
+    Normal = "normal",
+    Detailed = "detailed"
+}
+export declare enum ZlinkStreamMessageKind {
+    Send = 1,
+    Request = 2,
+    Response = 3,
+    Error = 4,
+    Control = 5
+}
+export declare enum ZlinkStreamHeaderFlags {
+    None = 0,
+    HasRequestSeq = 1,
+    HasMetadata = 2,
+    PayloadCompressed = 4,
+    HasCorrelationId = 8,
+    HasFlowId = 16
+}
+export type ZlinkFlowOrigin = 'Inbound' | 'Timer' | 'Application' | 'Lifecycle';
+export type ZlinkStreamCloseReason = 'ClientClose' | 'IdleTimeout' | 'HeartbeatTimeout' | 'ServerDrain' | 'ProtocolError' | 'TransportError';
+export declare enum ZlinkStreamErrorCode {
+    Disconnected = "disconnected",
+    ConfigurationError = "configurationError",
+    ValidationFailed = "validationFailed",
+    RequestTimeout = "requestTimeout",
+    ConnectTimeout = "connectTimeout",
+    FrameDecodeFailed = "frameDecodeFailed",
+    FrameTooLarge = "frameTooLarge",
+    SendFailed = "sendFailed",
+    CompressionFailed = "compressionFailed",
+    DecompressionFailed = "decompressionFailed",
+    UserCallbackFailed = "userCallbackFailed",
+    ObserverFailed = "observer-failed",
+    ObserverDropped = "observer-dropped",
+    ReceivedMessageDropped = "received-message-dropped",
+    RemoteError = "remoteError"
+}
+export declare enum ZlinkStreamConnectionState {
+    Created = "created",
+    Connecting = "connecting",
+    Connected = "connected",
+    Reconnecting = "reconnecting",
+    Disconnected = "disconnected",
+    Closed = "closed"
+}

package/dist/browser/Contracts/ZlinkStreamInterfaces.d.ts

@@ -0,0 +1,3 @@
+export interface Disposable {
+    dispose(): void;
+}

package/dist/browser/Contracts/ZlinkStreamJsonCodec.d.ts

@@ -0,0 +1,12 @@
+import type { ZlinkStreamPayloadCodec } from './ZlinkStreamConnectorOptions';
+import type { ZlinkStreamEncodedPayload } from './ZlinkStreamModels';
+export declare const zlinkStreamJsonCodecName = "json";
+export interface ZlinkStreamJsonCodecOptions {
+    readonly replacer?: (this: unknown, key: string, value: unknown) => unknown;
+    readonly reviver?: (this: unknown, key: string, value: unknown) => unknown;
+}
+export declare const zlinkStreamJsonCodec: ZlinkStreamPayloadCodec & {
+    configure(options: ZlinkStreamJsonCodecOptions): void;
+};
+export declare function toJson<T>(value: T, messageType?: Function): ZlinkStreamEncodedPayload;
+export declare function fromJson<T>(payload: ZlinkStreamEncodedPayload): T;

package/dist/browser/Contracts/ZlinkStreamMetadata.d.ts

@@ -0,0 +1,18 @@
+export interface ZlinkStreamMetadata {
+    readonly count: number;
+    readonly values: ReadonlyMap<string, string>;
+    get(key: string): string | undefined;
+    with(key: string, value: string): ZlinkStreamMetadata;
+    withMany(values: Iterable<readonly [string, string]>): ZlinkStreamMetadata;
+}
+export declare class ZlinkStreamMetadataMap implements ZlinkStreamMetadata {
+    readonly values: ReadonlyMap<string, string>;
+    static readonly empty: ZlinkStreamMetadata;
+    private constructor();
+    get count(): number;
+    get(key: string): string | undefined;
+    with(key: string, value: string): ZlinkStreamMetadata;
+    withMany(values: Iterable<readonly [string, string]>): ZlinkStreamMetadata;
+    static from(values: Iterable<readonly [string, string]>): ZlinkStreamMetadata;
+}
+export declare function validateMetadataKey(key: string): void;

package/dist/browser/Contracts/ZlinkStreamModels.d.ts

@@ -0,0 +1,68 @@
+import type { ZlinkStreamCodec, ZlinkStreamConnectionState, ZlinkStreamErrorCode, ZlinkStreamHeaderFlags, ZlinkStreamMessageKind, ZlinkFlowOrigin } from './ZlinkStreamEnums';
+import type { ZlinkStreamMetadata } from './ZlinkStreamMetadata';
+export interface ZlinkStreamEncodedPayload {
+    readonly codec: ZlinkStreamCodec;
+    readonly payload: Uint8Array;
+    readonly messageType?: Function;
+}
+export interface ZlinkStreamFlow {
+    readonly flowId: string;
+    readonly flowOrigin: ZlinkFlowOrigin;
+}
+export interface ZlinkStreamMessage<TPayload = unknown> {
+    readonly name: string;
+    readonly metadata: ZlinkStreamMetadata;
+    readonly payload: TPayload;
+    /**
+     * Present while diagnostics are enabled (the default). With
+     * `diagnosticsLevel: Off` inbound flow fields are neither read nor
+     * installed (spec 27 §4), so delivered messages carry no flow pair.
+     */
+    readonly flowId?: string;
+    readonly flowOrigin?: ZlinkFlowOrigin;
+}
+export interface ZlinkStreamHeader {
+    readonly kind: ZlinkStreamMessageKind;
+    readonly codec: ZlinkStreamCodec;
+    readonly flags: ZlinkStreamHeaderFlags;
+    readonly requestSeq?: bigint;
+    readonly name: string;
+    readonly metadata: ZlinkStreamMetadata;
+    readonly correlationId?: string;
+    readonly flowId?: string;
+    readonly flowOrigin?: ZlinkFlowOrigin;
+}
+export interface ZlinkStreamError {
+    readonly code: ZlinkStreamErrorCode;
+    readonly message: string;
+    readonly cause?: unknown;
+}
+export interface ZlinkStreamConnectionStateChanged {
+    readonly previous: ZlinkStreamConnectionState;
+    readonly current: ZlinkStreamConnectionState;
+    readonly error?: ZlinkStreamError;
+}
+export interface ZlinkStreamInboundObservation {
+    readonly kind: ZlinkStreamMessageKind;
+    readonly name: string;
+    readonly codec: ZlinkStreamCodec;
+    readonly requestSeq?: bigint;
+    readonly flowId?: string;
+    readonly flowOrigin?: ZlinkFlowOrigin;
+    readonly metadata: ZlinkStreamMetadata;
+    readonly payloadLength: number;
+    readonly isCompressed: boolean;
+    readonly receivedAt: Date;
+    readonly payloadPreview: Uint8Array;
+}
+export interface ZlinkStreamResult {
+    readonly isSuccess: boolean;
+    readonly error?: ZlinkStreamError;
+}
+export interface ZlinkStreamResultOf<T> extends ZlinkStreamResult {
+    readonly value?: T;
+}
+export declare class ZlinkStreamException extends Error {
+    readonly error: ZlinkStreamError;
+    constructor(error: ZlinkStreamError);
+}

package/dist/browser/Contracts/index.d.ts

@@ -0,0 +1,10 @@
+export { ZlinkStreamTransport, ZlinkStreamCodec, ZlinkStreamCompression, ZlinkStreamDiagnosticsLevel, ZlinkStreamDispatchMode, ZlinkStreamMessageKind, ZlinkStreamHeaderFlags, ZlinkStreamErrorCode, ZlinkStreamConnectionState } from './ZlinkStreamEnums';
+export type { ZlinkFlowOrigin, ZlinkStreamCloseReason } from './ZlinkStreamEnums';
+export * from './ZlinkStreamConnectorOptions';
+export * from './ZlinkStreamInterfaces';
+export * from './ZlinkStreamMetadata';
+export type { ZlinkStreamEncodedPayload, ZlinkStreamFlow, ZlinkStreamMessage, ZlinkStreamError, ZlinkStreamConnectionStateChanged, ZlinkStreamInboundObservation, ZlinkStreamResult, ZlinkStreamResultOf } from './ZlinkStreamModels';
+export { ZlinkStreamException } from './ZlinkStreamModels';
+export * from './ZlinkStreamJsonCodec';
+export * from './IZlinkStreamConnector';
+export * from './Calls/ZlinkStreamCalls';

package/dist/browser/Runtime/Calls/ZlinkStreamCallBuilders.d.ts

@@ -0,0 +1,48 @@
+import { RequiredZlinkStreamConnectorOptions, ZlinkStreamEncodedPayload, ZlinkStreamFlow, ZlinkStreamMessage, ZlinkStreamMessageKind, ZlinkStreamMetadata, type ZlinkStreamRequestCall, type ZlinkStreamResultOf, type ZlinkStreamSendCall, type ZlinkStreamWaitCall } from '../../Contracts';
+interface ZlinkStreamConnectorSubmitter {
+    readonly options: RequiredZlinkStreamConnectorOptions;
+    sendEncoded(kind: ZlinkStreamMessageKind, name: string, payload: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata, compress: boolean, requestSeq: bigint | undefined, signal?: AbortSignal, flow?: ZlinkStreamFlow): Promise<void>;
+    requestEncoded(name: string, payload: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata, compress: boolean, timeoutMs: number, signal?: AbortSignal, flow?: ZlinkStreamFlow): Promise<ZlinkStreamEncodedPayload>;
+    waitForMessage<TPayload>(name: string, timeoutMs: number, predicate: (message: ZlinkStreamMessage<TPayload>) => boolean, signal?: AbortSignal): Promise<ZlinkStreamMessage<TPayload>>;
+}
+export declare class ZlinkStreamSendBuilder implements ZlinkStreamSendCall {
+    private readonly connector;
+    private readonly payload;
+    private readonly state;
+    constructor(connector: ZlinkStreamConnectorSubmitter, name: string | undefined, payload: ZlinkStreamEncodedPayload);
+    packetName(name: string): this;
+    metadata(key: string, value: string): this;
+    metadata(metadata: ZlinkStreamMetadata): this;
+    compress(): this;
+    flowFrom(flow: ZlinkStreamFlow): this;
+    submit(signal?: AbortSignal): Promise<void>;
+}
+export declare class ZlinkStreamRequestBuilder implements ZlinkStreamRequestCall {
+    private readonly connector;
+    private readonly payload;
+    private readonly state;
+    constructor(connector: ZlinkStreamConnectorSubmitter, name: string | undefined, payload: ZlinkStreamEncodedPayload);
+    packetName(name: string): this;
+    metadata(key: string, value: string): this;
+    metadata(metadata: ZlinkStreamMetadata): this;
+    timeout(timeoutMs: number): this;
+    compress(): this;
+    flowFrom(flow: ZlinkStreamFlow): this;
+    submit<TReply = unknown>(signal?: AbortSignal): Promise<TReply>;
+    submit(callback: (result: ZlinkStreamResultOf<ZlinkStreamEncodedPayload>) => void): void;
+    submitEncoded(signal?: AbortSignal): Promise<ZlinkStreamEncodedPayload>;
+}
+export declare class ZlinkStreamWaitBuilder<TPayload = ZlinkStreamEncodedPayload> implements ZlinkStreamWaitCall<TPayload> {
+    private readonly connector;
+    private readonly name;
+    private executed;
+    private timeoutMs;
+    private predicate;
+    constructor(connector: ZlinkStreamConnectorSubmitter, name: string);
+    where(predicate: (message: ZlinkStreamMessage<TPayload>) => boolean): this;
+    timeout(timeoutMs: number): this;
+    submit(signal?: AbortSignal): Promise<ZlinkStreamMessage<TPayload>>;
+    private ensureConfigurable;
+    private markExecuted;
+}
+export {};

package/dist/browser/Runtime/Calls/ZlinkStreamObservationBuilders.d.ts

@@ -0,0 +1,29 @@
+import { type RequiredZlinkStreamConnectorOptions, type ZlinkStreamExpectNoneCall, type ZlinkStreamMessage, type ZlinkStreamSequenceCall } from '../../Contracts';
+export interface ZlinkStreamMessageWaiter {
+    readonly options: RequiredZlinkStreamConnectorOptions;
+    waitForMessage<TPayload>(name: string, timeoutMs: number, predicate: (message: ZlinkStreamMessage<TPayload>) => boolean, signal?: AbortSignal): Promise<ZlinkStreamMessage<TPayload>>;
+}
+export declare class ZlinkStreamExpectNoneBuilder<TPayload> implements ZlinkStreamExpectNoneCall<TPayload> {
+    private readonly connector;
+    private readonly name;
+    private windowMs;
+    private executed;
+    constructor(connector: ZlinkStreamMessageWaiter, name: string);
+    within(windowMs: number): this;
+    run(signal?: AbortSignal): Promise<void>;
+    private ensureConfigurable;
+    private markExecuted;
+}
+export declare class ZlinkStreamSequenceBuilder<TPayload> implements ZlinkStreamSequenceCall<TPayload> {
+    private readonly connector;
+    private readonly name;
+    private readonly predicates;
+    private timeoutMs;
+    private executed;
+    constructor(connector: ZlinkStreamMessageWaiter, name: string);
+    expect(predicate: (payload: TPayload) => boolean): this;
+    timeout(timeoutMs: number): this;
+    run(signal?: AbortSignal): Promise<readonly TPayload[]>;
+    private ensureConfigurable;
+    private markExecuted;
+}

package/dist/browser/Runtime/Protocol/Compression/ZlinkStreamCompressionCodec.d.ts

@@ -0,0 +1,5 @@
+import { type ZlinkStreamCompressionCodec, ZlinkStreamCompression } from '../../../Contracts';
+import type { ZlinkStreamHeader } from '../../../Contracts/ZlinkStreamModels';
+export declare const zlinkStreamLz4CompressionCodec: ZlinkStreamCompressionCodec;
+export declare function compressPayload(payload: Uint8Array, compression: ZlinkStreamCompression, compressionCodec: ZlinkStreamCompressionCodec | undefined): Uint8Array;
+export declare function decompressIfNeeded(header: ZlinkStreamHeader, payload: Uint8Array, compression: ZlinkStreamCompression, compressionCodec: ZlinkStreamCompressionCodec | undefined, maxDecompressedSize: number): Uint8Array;

package/dist/browser/Runtime/Protocol/ZlinkSessionClosing.d.ts

@@ -0,0 +1,7 @@
+import type { ZlinkStreamCloseReason } from '../../Contracts';
+export declare const ZLINK_SESSION_CLOSING = "session-closing";
+export declare function decodeSessionClosing(payload: Uint8Array): {
+    readonly closeReason: ZlinkStreamCloseReason;
+    readonly diagnostic?: string;
+};
+export declare function encodeSessionClosing(reason: ZlinkStreamCloseReason, diagnostic?: string): Uint8Array;

package/dist/browser/Runtime/Protocol/ZlinkStreamFrameCodec.d.ts

@@ -0,0 +1,8 @@
+export declare class ZlinkStreamFrameCodec {
+    static encode(header: Uint8Array, payload: Uint8Array, maxPayloadSize?: number): Uint8Array;
+    static decode(frame: Uint8Array): {
+        header: Uint8Array;
+        payload: Uint8Array;
+    };
+}
+export declare function splitZlinkStreamFrames(chunk: Uint8Array): readonly Uint8Array[];

package/dist/browser/Runtime/Protocol/ZlinkStreamFrameProtocol.d.ts

@@ -0,0 +1,23 @@
+import type { RequiredZlinkStreamConnectorOptions, ZlinkStreamEncodedPayload, ZlinkStreamMetadata } from '../../Contracts';
+import { ZlinkStreamMessageKind } from '../../Contracts';
+import type { ZlinkStreamHeader } from '../../Contracts/ZlinkStreamModels';
+import type { ZlinkFlowOrigin } from '../../Contracts';
+export declare const ZLINK_STREAM_HEARTBEAT_PING = "$zlink.heartbeat.ping";
+export declare const ZLINK_STREAM_HEARTBEAT_PONG = "$zlink.heartbeat.pong";
+export declare class ZlinkStreamFrameProtocol {
+    private readonly options;
+    constructor(options: RequiredZlinkStreamConnectorOptions);
+    encode(kind: ZlinkStreamMessageKind, name: string, payload: ZlinkStreamEncodedPayload, metadata: ZlinkStreamMetadata, compress: boolean, requestSeq: bigint | undefined, correlationId?: string, flowId?: string, flowOrigin?: ZlinkFlowOrigin): Uint8Array;
+    encodeControl(name: string, payload?: Uint8Array<ArrayBuffer>): Uint8Array;
+    decode(frameBytes: Uint8Array, flowEnabled?: boolean): {
+        readonly header: ZlinkStreamHeader;
+        readonly payload: Uint8Array;
+    };
+    flowEnabled(): boolean;
+    decodeFrames(chunk: Uint8Array, flowEnabled?: boolean): readonly {
+        readonly header: ZlinkStreamHeader;
+        readonly payload: Uint8Array;
+    }[];
+    decodePayload(header: ZlinkStreamHeader, payload: Uint8Array): Uint8Array;
+    private encodeFrame;
+}

package/dist/browser/Runtime/Protocol/ZlinkStreamHeaderCodec.d.ts

@@ -0,0 +1,12 @@
+import { ZlinkStreamCodec, ZlinkStreamMessageKind, ZlinkStreamMetadata } from '../../Contracts';
+import type { ZlinkStreamHeader } from '../../Contracts/ZlinkStreamModels';
+export declare class ZlinkStreamHeaderCodec {
+    static encode(header: ZlinkStreamHeader): Uint8Array;
+    /**
+     * `includeFlow=false` (diagnostics Off, spec 27 §4) skips reading and
+     * validating the inbound flow fields while the structural length checks in
+     * the wire decoder are preserved.
+     */
+    static decode(header: Uint8Array, includeFlow?: boolean): ZlinkStreamHeader;
+}
+export declare function buildHeader(kind: ZlinkStreamMessageKind, name: string, codec: ZlinkStreamCodec, metadata: ZlinkStreamMetadata, compress: boolean, requestSeq: bigint | undefined, correlationId?: string, flowId?: string, flowOrigin?: import('../../Contracts').ZlinkFlowOrigin): ZlinkStreamHeader;

package/dist/browser/Runtime/Protocol/ZlinkStreamMetadataCodec.d.ts

@@ -0,0 +1,7 @@
+import { ZlinkStreamMetadata } from '../../Contracts';
+export declare const ZLINK_STREAM_MAX_METADATA_BYTES = 1024;
+export declare class ZlinkStreamMetadataCodec {
+    static size(metadata: ZlinkStreamMetadata): number;
+    static write(metadata: ZlinkStreamMetadata, destination: Uint8Array): void;
+    static decode(metadata: Uint8Array): ZlinkStreamMetadata;
+}

package/dist/browser/Runtime/Protocol/ZlinkStreamPacketNameValidator.d.ts

@@ -0,0 +1 @@
+export declare function validateName(name: string, allowReserved?: boolean): void;