keri-ts 1.0.0 → 2.0.0

package/types/app/mailbox/mailbox-director.d.ts

@@ -0,0 +1,252 @@
+/**
+ * Runtime-composed mailbox publication, query, and stream coordination.
+ *
+ * KERIpy correspondence:
+ * - gathers responsibilities that KERIpy spreads across `Mailboxer`,
+ *   mailbox iterables, and indirect-mode query handling
+ *
+ * Boundary rule:
+ * - this module is mailbox storage/query infrastructure, not the general
+ *   responder path
+ * - non-`stream` cue delivery such as `reply`, `replay`, `receipt`, and
+ *   `witness` belongs in `Respondant`
+ *
+ * Current `keri-ts` difference:
+ * - one runtime host receives an explicit mailbox sidecar instead of
+ *   discovering mailbox storage through `Habery`
+ */
+import type { AgentCue, StreamCue } from "../../core/cues.js";
+import { Deck } from "../../core/deck.js";
+import type { MbxTopicCursor } from "../../core/mailbox/mailbox-topics.js";
+import type { Mailboxer } from "../../db/mailbox/mailboxing.js";
+import type { Habery } from "../identity/habbing.js";
+/**
+ * Provider SSE response timing; these settings do not control remote poll consumers.
+ */
+interface MailboxStreamOptions {
+    /**
+     * SSE reconnect hint in milliseconds; default 5000, zero allowed.
+     */
+    retryMs?: number;
+    /**
+     * Native timer interval for new local rows/cues; default 50 milliseconds, strictly positive.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Direct-stream idle expiry in milliseconds; default 2000, null disables expiry.
+     */
+    idleTimeoutMs?: number | null;
+    /**
+     * Emit the initial retry hint; default true. Nested query readers suppress a duplicate hint.
+     */
+    emitRetryHeader?: boolean;
+}
+/**
+ * Mailbox topic director for one runtime host.
+ *
+ * Responsibilities:
+ * - retain mailbox stream requests so protocol hosts can answer `mbx` queries
+ * - expose ordered topic iteration backed by the dedicated `Mailboxer` and
+ *   durable remote cursor state in `tops.`
+ * - publish only explicitly forwarded mailbox payloads such as authorized
+ *   `/fwd` deliveries
+ *
+ * Non-responsibilities:
+ * - do not absorb generic non-`stream` cue emissions as implicit local mailbox
+ *   side effects
+ * - do not replace `Respondant` / `Poster` endpoint delivery
+ *
+ * KERIpy correspondence:
+ * - coordinates the storage/query slice around `Mailboxer` and
+ *   `MailboxIterable`
+ */
+export declare class MailboxDirector {
+    /**
+     * Borrowed local identities and accepted-state stores.
+     */
+    readonly hby: Habery;
+    /**
+     * Borrowed provider mailbox store, or null when this host cannot serve stored messages.
+     */
+    readonly mailboxer: Mailboxer | null;
+    /** Exclusive correlation ownership; external producers append but do not take/release query owners. */
+    readonly queryCues: Deck<AgentCue>;
+    /**
+     * Registered protocol topics, copied from construction input and extended by registerTopic.
+     */
+    readonly topics: Set<string>;
+    /**
+     * Live response finalizers joined before the provider store can close.
+     */
+    private readonly streamCleanups;
+    /**
+     * Terminal stream/correlation admission state.
+     */
+    private closed;
+    /**
+     * Compose provider publication and request-owned stream tracking.
+     * Absent mailboxer disables storage/serving; correlation and topic registration
+     * remain available. A new query Deck is created only when none is supplied.
+     *
+     * @param hby Borrowed local identities and accepted-state stores.
+     * @param options Optional borrowed mailbox store, exclusive query-cue Deck and initial topics; no store is opened.
+     */
+    constructor(hby: Habery, { mailboxer, queryCues, topics, }?: {
+        mailboxer?: Mailboxer;
+        queryCues?: Deck<AgentCue>;
+        topics?: readonly string[];
+    });
+    /**
+     * Register one mailbox topic this runtime should poll/stream.
+     *
+     * @param topic Protocol mailbox topic; leading slash is normalized where required.
+     */
+    registerTopic(topic: string): void;
+    /**
+     * Snapshot the currently configured mailbox topic set.
+     *
+     * @returns Independent array snapshot of the configured topic set.
+     */
+    registeredTopics(): string[];
+    /** Stop every request-owned mailbox stream before its backing store closes. */
+    close(): Promise<void>;
+    /**
+     * Validate exact cursor ordinals before copying the caller's query positions.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param topics Topic-to-next-wanted ordinal map; each value must be a nonnegative safe integer.
+     * @returns A copied cursor map owned by this response.
+     * @throws RangeError for malformed prefix/map/ordinals.
+     */
+    private cursor;
+    /**
+     * Queue a query cue for correlation with its mailbox response.
+     *
+     * @param cue Authorized stream request produced by protocol processing; the director owns later correlation consumption.
+     */
+    retainQueryCue(cue: StreamCue): void;
+    /**
+     * Persist one outbound mailbox payload under the ordered topic bucket for
+     * `pre/topic`.
+     *
+     * The returned index is the newly assigned mailbox event id for that topic.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param topic Protocol mailbox topic; leading slash is normalized where required.
+     * @param msg Complete already-authorized wire message to persist under this recipient/topic.
+     * @returns Assigned mailbox index; persistence is not remote consumption.
+     */
+    publish(pre: string, topic: string, msg: Uint8Array): number;
+    /**
+     * Return the latest stored publication index for one topic, or `-1`.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param topic Protocol mailbox topic; leading slash is normalized where required.
+     * @returns Latest stored insertion ordinal, or -1 for an empty topic.
+     */
+    lastIndex(pre: string, topic: string): number;
+    /**
+     * Return ordered topic payloads starting at the provided insertion index.
+     *
+     * The returned index is the mailbox event id that should be reflected in the
+     * SSE `id:` field for the emitted message.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param topic Protocol mailbox topic; leading slash is normalized where required.
+     * @param from Inclusive insertion ordinal; default zero.
+     * @returns Synchronous iterator of ordinal/message pairs in storage order.
+     */
+    topicIter(pre: string, topic: string, from?: number): Generator<{
+        idx: number;
+        msg: Uint8Array;
+    }>;
+    /**
+     * Return a server-sent-event stream over mailbox topics until the idle window
+     * expires.
+     *
+     * SSE policy:
+     * - emit one initial `retry:` hint
+     * - stream ordered mailbox payloads as `id/event/data`
+     * - close once the idle window expires without new mailbox traffic
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param topicCursor Next wanted insertion ordinal for each requested topic; copied before streaming.
+     * @param options SSE retry hint, local polling interval, optional idle expiry and initial hint selection.
+     * @returns Demand-driven response tracked until EOF, cancellation or director close.
+     */
+    streamMailbox(pre: string, topicCursor: MbxTopicCursor, options?: MailboxStreamOptions): ReadableStream<Uint8Array>;
+    /**
+     * Own one demand-driven mailbox reader; query responses join their nested reader themselves.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param cursors Response-owned next-wanted ordinals, advanced as rows are framed.
+     * @param options Millisecond retry/poll/idle settings; null idle timeout keeps the response open.
+     * @param tracked Track direct responses here; nested query responses are joined by their outer owner.
+     * @returns SSE bytes in 64 KiB chunks; database iterators close before awaiting HTTP demand.
+     */
+    private mailboxStream;
+    /**
+     * Return a KERIpy-style long-lived SSE response for one posted `qry`.
+     *
+     * Correlation rule:
+     * - emit the initial `retry:` hint immediately
+     * - wait until a matching `stream` cue for the query SAID appears
+     * - once matched, proxy the normal mailbox iterable for that cue
+     *
+     * This mirrors KERIpy `QryRpyMailboxIterable` ownership closely: the HTTP
+     * route does not guess mailbox topics itself; it waits for mailbox query
+     * correlation to tell it what to stream.
+     *
+     * @param said Query SAID used to locate an already-authorized stream cue; correlation alone is not authorization.
+     * @param options Retry hint and query-cue polling interval in milliseconds; defaults 5000 and 50.
+     * @returns Request-owned SSE response that waits for its cue then proxies an unbounded mailbox reader.
+     */
+    streamQueryResponse(said: string, { retryMs, pollIntervalMs }?: Pick<MailboxStreamOptions, "retryMs" | "pollIntervalMs">): ReadableStream<Uint8Array>;
+    /**
+     * Build the next `mbx` query cursor map for one `(pre, witness)` pair.
+     *
+     * Stored cursor rows track the last seen index, while the wire query asks for
+     * the next wanted index.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param witness Remote mailbox/witness endpoint AID, not the local signer.
+     * @returns Next-wanted ordinals (last consumed + 1, or zero) for registered topics.
+     */
+    remoteQueryCursor(pre: string, witness: string): Record<string, number>;
+    /**
+     * Persist one consumed remote mailbox index for one `(pre, witness, topic)`.
+     *
+     * @param pre AID whose mailbox or accepted state is addressed.
+     * @param witness Remote endpoint AID.
+     * @param topic Protocol mailbox topic; leading slash is normalized where required.
+     * @param idx Last successfully consumed insertion ordinal, not the next requested ordinal.
+     */
+    updateRemoteCursor(pre: string, witness: string, topic: string, idx: number): void;
+    /**
+     * Check whether the runtime has seen a matching `stream` cue for one query
+     * SAID without discarding other pending query cues.
+     *
+     * This keeps query correlation observable without consuming cues that later
+     * host work still needs.
+     *
+     * @param said Exact query SAID whose stream request is sought.
+     * @returns Whether a matching request exists.
+     */
+    hasQueryCue(said: string): boolean;
+    /**
+     * Select the first matching owner without re-admission or changing preceding cue order.
+     *
+     * @param said Exact query SAID whose stream request is sought.
+     * @returns Removed matching cue, or null; other cues retain their order.
+     */
+    private takeQueryCue;
+    /**
+     * Require provider mailbox storage for publication or mailbox serving.
+     *
+     * @returns Borrowed provider store.
+     * @throws ValidationError when storage is absent.
+     */
+    private requireMailboxer;
+}
+export {};
+//# sourceMappingURL=mailbox-director.d.ts.map

package/types/app/mailbox/mailbox-director.d.ts.map

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

package/types/app/mailbox/mailbox-poller.d.ts

@@ -0,0 +1,149 @@
+/** Recipient mailbox polling: signed queries, awaited SSE intake and persisted cursor progression. */
+import { type Operation } from "effection";
+import type { Habery } from "../identity/habbing.js";
+import type { RuntimeClock } from "../runtime/runtime-clock.js";
+import type { HttpClient } from "../transport/http-client.js";
+import type { MailboxDirector } from "./mailbox-director.js";
+/**
+ * Scalar polling policy overrides; dependencies are constructor arguments.
+ */
+interface MailboxPollerOptions {
+    /**
+     * Optional millisecond header and poll-window overrides.
+     */
+    timeouts?: Partial<MailboxPollingTimeoutPolicy>;
+}
+/**
+ * Retrieve recipient messages from remote mailbox or witness endpoints over HTTP/SSE.
+ *
+ * Each endpoint has an independent worker and durable progress in the director.
+ * Retrieved records are lent to the awaited consumer; protocol intake stays outside.
+ * A provider store in the same runtime is never scanned for local recipient input.
+ */
+export declare class MailboxPoller {
+    /**
+     * Default header acquisition (5 seconds) and absolute poll window (30 seconds).
+     */
+    static readonly DefaultTimeoutPolicy: Readonly<MailboxPollingTimeoutPolicy>;
+    /**
+     * Idle read window after the first complete event, in milliseconds.
+     */
+    static readonly ReadIdleTimeoutMs = 500;
+    /** Borrowed habitat collection used to select mailbox signers. */
+    readonly hby: Habery;
+    /** Shared provider topics and persisted remote cursors. */
+    readonly mailboxDirector: MailboxDirector;
+    /** Existing request-open and SSE-window settings, normalized once. */
+    readonly timeoutPolicy: Readonly<MailboxPollingTimeoutPolicy>;
+    /** Borrowed HTTP client passed to each polling attempt. */
+    readonly http: HttpClient;
+    /** Borrowed clock for this owner's actual network deadlines. */
+    readonly clock: RuntimeClock;
+    /**
+     * Bind polling inputs and dependencies without starting workers or acquiring stores.
+     *
+     * @param hby Borrowed local identities and accepted-state stores.
+     * @param mailboxDirector Borrowed provider/topic/cursor owner.
+     * @param http Borrowed HTTP implementation selected by composition.
+     * @param clock Borrowed clock with epoch-millisecond now and millisecond timer delays.
+     * @param options Optional timeout overrides; finite positive values are floored with a 1 ms minimum. Missing/nonpositive/nonfinite values use 5-second headers and 30-second poll windows.
+     */
+    constructor(hby: Habery, mailboxDirector: MailboxDirector, http: HttpClient, clock: RuntimeClock, options?: MailboxPollerOptions);
+    /**
+     * Register one mailbox topic that this poller should retrieve.
+     *
+     * @param topic Protocol mailbox topic; leading slash is normalized where required.
+     */
+    registerTopic(topic: string): void;
+    /**
+     * Poll forever, streaming typed batches into one sink.
+     *
+     * Each remote endpoint progresses independently, and awaits the consumer before
+     * reading the next event or advancing its persisted cursor.
+     *
+     * @param onBatch Awaited endpoint-batch consumer; the durable event cursor advances only after it succeeds. Failure or cancellation leaves that event available for later retrieval.
+     * @throws Consumer/transport failures propagate; endpoint workers are joined on scope exit.
+     */
+    pollDo(onBatch: (batch: MailboxPollBatch) => void | Operation<void>): Operation<never>;
+    /**
+     * Stream one remote response through its consumer before recording cursor progress.
+     *
+     * @param target Mailbox subject habitat plus the actual local signer (a member for groups).
+     * @param endpoint Selected remote endpoint AID and HTTP(S) URL.
+     * @param onBatch Awaited consumer; successful completion precedes durable cursor advancement.
+     */
+    private pollRemoteEndpointOnce;
+    /**
+     * Keep one long-lived worker running for each currently configured remote endpoint.
+     *
+     * @param remoteWorkers Owned worker map, mutated to match current endpoint selection.
+     * @param onBatch Shared awaited consumer used independently by each endpoint worker.
+     * @param topics Current registered topics; no topics means no remote workers.
+     */
+    private syncRemoteWorkers;
+    /**
+     * Poll one remote endpoint continuously in the long-lived runtime shape.
+     *
+     * This keeps KERIpy's "one poller per endpoint" behavior while preserving
+     * `keri-ts`'s split between mailbox transport and runtime parser ownership.
+     *
+     * @param target Mailbox subject habitat plus the actual local signer (a member for groups).
+     * @param endpoint Selected remote endpoint AID and HTTP(S) URL.
+     * @param onBatch Awaited consumer; successful completion precedes durable cursor advancement.
+     */
+    private remoteEndpointWorker;
+    /**
+     * Select locally pollable subjects without substituting the group for its member signer.
+     *
+     * @returns Local subject/signing pairs; groups without an available local member are omitted.
+     */
+    private remotePollTargets;
+    /**
+     * Choose the actual local signer for a subject's mailbox query.
+     *
+     * @param hab Local subject habitat, possibly a group.
+     * @returns The habitat itself, or its available local group member; null when unresolved.
+     */
+    private pollSignerHab;
+}
+/** Mailbox polling windows in milliseconds; the poller floors positive overrides with a 1 ms minimum. */
+export interface MailboxPollingTimeoutPolicy {
+    /** Abort the HTTP request when no response headers arrive before this deadline. */
+    requestOpenTimeoutMs: number;
+    /** Stop reading one mailbox SSE response after this long-poll window. */
+    maxPollDurationMs: number;
+}
+/** One remote mailbox batch, consumed before its provider cursor advances. */
+export interface MailboxPollBatch {
+    /**
+     * Mailbox subject AID, possibly distinct from the signing member.
+     */
+    pre: string;
+    /**
+     * Mailbox provider AID that supplied this batch; distinct from the subject and query signer.
+     */
+    eid: string;
+    /**
+     * Complete wire messages passed to the awaited batch consumer in order.
+     */
+    messages: Uint8Array[];
+}
+/**
+ * Per-attempt header and SSE window settings in milliseconds.
+ */
+export interface MailboxFetchTimeoutPolicy {
+    /**
+     * Header acquisition deadline in milliseconds.
+     */
+    requestOpenTimeoutMs: number;
+    /**
+     * Absolute SSE read window in milliseconds.
+     */
+    maxReadDurationMs: number;
+    /**
+     * Idle read deadline after a complete event, in milliseconds.
+     */
+    readIdleTimeoutMs: number;
+}
+export {};
+//# sourceMappingURL=mailbox-poller.d.ts.map

package/types/app/mailbox/mailbox-poller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox-poller.d.ts","sourceRoot":"","sources":["../../../src/app/mailbox/mailbox-poller.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,OAAO,EAAQ,KAAK,SAAS,EAA4B,MAAM,WAAW,CAAC;AAC3E,OAAO,KAAK,EAAO,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAIhE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAC;AAE9D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAI7D;;GAEG;AACH,UAAU,oBAAoB;IAC5B;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACjD;AAED;;;;;;GAMG;AACH,qBAAa,aAAa;IACxB;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,oBAAoB,EAAE,QAAQ,CAAC,2BAA2B,CAAC,CAGxE;IACH;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,iBAAiB,OAAO;IAExC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,sEAAsE;IACtE,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,2BAA2B,CAAC,CAAC;IAC9D,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAE7B;;;;;;;;OAQG;gBAED,GAAG,EAAE,MAAM,EACX,eAAe,EAAE,eAAe,EAChC,IAAI,EAAE,UAAU,EAChB,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,oBAAyB;IAUpC;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIlC;;;;;;;;OAQG;IACF,MAAM,CACL,OAAO,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,GAC3D,SAAS,CAAC,KAAK,CAAC;IAiBnB;;;;;;OAMG;IACH,OAAO,CAAE,sBAAsB;IA2B/B;;;;;;OAMG;IACH,OAAO,CAAE,iBAAiB;IA8B1B;;;;;;;;;OASG;IACH,OAAO,CAAE,oBAAoB;IAW7B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAYzB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;CAUtB;AAoBD,yGAAyG;AACzG,MAAM,WAAW,2BAA2B;IAC1C,mFAAmF;IACnF,oBAAoB,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,QAAQ,EAAE,UAAU,EAAE,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;IAC1B;;OAEG;IACH,iBAAiB,EAAE,MAAM,CAAC;CAC3B"}

package/types/app/mailbox/mailbox-sse.d.ts

@@ -0,0 +1,63 @@
+import { type Operation } from "effection";
+import { type RuntimeClock } from "../runtime/runtime-clock.js";
+import type { HttpStreamResponse } from "../transport/http-client.js";
+/** One parsed mailbox SSE payload with its ordered topic metadata. */
+export interface MailboxSseMessage {
+    /**
+     * Nonnegative insertion ordinal supplied by the provider SSE id.
+     */
+    idx: number;
+    /**
+     * UTF-8 bytes from the complete joined SSE data fields.
+     */
+    msg: Uint8Array;
+    /**
+     * Provider event/topic name associated with the ordinal.
+     */
+    topic: string;
+}
+/** Poll timing and cancellation; complete events are delivered to the awaited consumer. */
+export interface MailboxSseOptions {
+    /** End an idle poll after its first complete event; default 500 ms. */
+    idleTimeoutMs?: number;
+    /** Absolute lifetime of one long poll, including its first event; default 30 seconds. */
+    maxDurationMs?: number;
+    /** External cancellation remains separate from a successful poll timeout. */
+    signal?: AbortSignal;
+}
+/**
+ * Consume complete mailbox events with backpressure from the awaited consumer.
+ * Returning false stops the poll without acknowledging an unread event. Timeout,
+ * EOF, and cancellation discard an incomplete final event so its cursor can retry.
+ * The consumer is immediately awaited in this read owner, not scheduled or queued.
+ * Keeping consumer failure inside this scope lets cleanup retain both failures;
+ * a borrowed pull iterator alone cannot observe a later consumer exception.
+ *
+ * @param response Borrowed streaming HTTP response; caller keeps its scope open through this operation.
+ * @param controller Body cancellation owner aborted when the poll window ends.
+ * @param consume Awaited complete-event consumer; false stops the poll and errors propagate before remote cursor advancement.
+ * @param clock Borrowed clock with epoch-millisecond now and millisecond timer delays.
+ * @param options Positive idle/absolute windows in milliseconds and optional upstream signal; defaults 500 and 30000.
+ * @throws External cancellation and genuine read/consumer/cleanup errors remain visible; owned window expiry ends the poll.
+ */
+export declare function consumeMailboxSse(response: HttpStreamResponse, controller: AbortController, consume: (message: MailboxSseMessage) => Operation<boolean | void>, clock: RuntimeClock, options?: MailboxSseOptions): Operation<void>;
+/**
+ * Collect a raw SSE diagnostic report for one poll window. Production polling
+ * uses consumeMailboxSse to deliver complete events as they arrive.
+ *
+ * @param response Borrowed streaming HTTP response; caller keeps its scope open through this operation.
+ * @param controller Body cancellation owner aborted when the poll window ends.
+ * @param clock Borrowed clock with epoch-millisecond now and millisecond timer delays.
+ * @param options Positive idle/absolute windows in milliseconds and optional upstream signal; defaults 500 and 30000.
+ * @returns Collected text from this bounded diagnostic window.
+ * @throws External cancellation and genuine read/consumer/cleanup errors remain visible; owned window expiry ends the poll.
+ */
+export declare function readMailboxSseBody(response: HttpStreamResponse, controller: AbortController, clock: RuntimeClock, options?: MailboxSseOptions): Operation<string>;
+/**
+ * Parse only terminated events from an already finite diagnostic report.
+ *
+ * @param text Finite diagnostic response text; an unterminated final block is ignored.
+ * @returns Complete valid mailbox events in received order.
+ */
+export declare function parseMailboxSse(text: string): MailboxSseMessage[];
+//# sourceMappingURL=mailbox-sse.d.ts.map

package/types/app/mailbox/mailbox-sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mailbox-sse.d.ts","sourceRoot":"","sources":["../../../src/app/mailbox/mailbox-sse.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,SAAS,EAAY,MAAM,WAAW,CAAC;AAE3D,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAKtE,sEAAsE;AACtE,MAAM,WAAW,iBAAiB;IAChC;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ;;OAEG;IACH,GAAG,EAAE,UAAU,CAAC;IAChB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;CACf;AAED,2FAA2F;AAC3F,MAAM,WAAW,iBAAiB;IAChC,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,yFAAyF;IACzF,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAgDD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,EAAE,eAAe,EAC3B,OAAO,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,SAAS,CAAC,OAAO,GAAG,IAAI,CAAC,EAClE,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,iBAAsB,GAC9B,SAAS,CAAC,IAAI,CAAC,CAyCjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,kBAAkB,EAC5B,UAAU,EAAE,eAAe,EAC3B,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,iBAAsB,GAC9B,SAAS,CAAC,MAAM,CAAC,CAgCnB;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAIjE"}