samva 0.17.0 → 0.19.0

package/dist/mailbox-events.d.ts

@@ -5,7 +5,8 @@
  * {@link MailboxEventStream} is an async iterable. The loop body handling an event is the
  * acknowledgement: asking for the next event marks the previous one handled, and the stream
  * resumes from the last handled event whenever it reconnects. Transient closes reconnect by
- * themselves; a close the caller has to act on ends the loop with a {@link MailboxEventStreamError}.
+ * themselves, and a normal close (1000) from the host ends the loop after the events already
+ * received; a close the caller has to act on ends the loop with a {@link MailboxEventStreamError}.
  *
  * This module has no runtime dependencies so the Promise and Effect clients share it.
  */
@@ -29,7 +30,7 @@ export declare const MailboxEventStreamCloseCode: {
     readonly accessUnavailable: 4503;
 };
 /** The event types the stream carries: the `mailbox.*` webhook events. */
-export type MailboxEventType = "mailbox.message.received" | "mailbox.message.sent" | "mailbox.action.pending_approval" | "mailbox.message.quarantined" | "mailbox.message.released" | "mailbox.message.discarded";
+export type MailboxEventType = "mailbox.message.received" | "mailbox.message.sent" | "mailbox.action.pending_approval" | "mailbox.action.resolved" | "mailbox.message.quarantined" | "mailbox.message.released" | "mailbox.message.discarded";
 /** One event, as a webhook delivery of it would carry it, plus its stream position. */
 export interface MailboxEvent {
     /** The stream position of this event. Persist it after handling to resume from here. */
@@ -44,12 +45,19 @@ export interface MailboxEvent {
 /**
  * Why a stream ended, as the `_tag` of its {@link MailboxEventStreamError}. The first nine are the
  * API error tags the events host refuses with, or that a close code stands for. The rest are the
- * client's own: `StreamDisconnectedError` is a close or an unreachable host that was not retried
- * because `reconnect` is `false`, `StreamClientError` is a request this client could not make,
+ * client's own: `StreamDisconnectedError` is a close, an idle timeout, or an unreachable host that
+ * was not retried because `reconnect` is `false`, `StreamClientError` is a request this client could not make,
  * `StreamProtocolError` is a frame from the host it could not read, and `StreamRefusedError` is a refusal whose tag and status this client
  * does not know (`serverTag` carries the tag the host sent).
  */
 export type MailboxEventStreamErrorTag = "UnauthorizedError" | "ForbiddenError" | "ResourceNotFoundError" | "CursorExpiredError" | "ValidationError" | "UpgradeRequiredError" | "RateLimitedError" | "ServiceUnavailableError" | "MethodNotAllowedError" | "StreamDisconnectedError" | "StreamClientError" | "StreamProtocolError" | "StreamRefusedError";
+/**
+ * Why a {@link MailboxEventStreamError} ended a stream, when `_tag` alone does not say.
+ * `idleTimeout`: the client heard no frame, not even a pong, for
+ * {@link MAILBOX_EVENT_STREAM_IDLE_MILLIS}, so it closed the connection itself. No close code
+ * accompanies it; a `closeCode` of `1006` is a close the client observed without a status.
+ */
+export type MailboxEventStreamErrorReason = "idleTimeout";
 /** Field-level validation messages, keyed by dotted path, as a `ValidationError` carries them. */
 export type MailboxEventStreamErrorFields = Readonly<Record<string, ReadonlyArray<string>>>;
 /**
@@ -76,6 +84,8 @@ export declare class MailboxEventStreamError<Tag extends MailboxEventStreamError
     readonly retryAfterSeconds: number | undefined;
     /** The tag the host sent, when it is not one this client maps. */
     readonly serverTag: string | undefined;
+    /** Set when the client ended the connection itself; see {@link MailboxEventStreamErrorReason}. */
+    readonly reason: MailboxEventStreamErrorReason | undefined;
     constructor(input: {
         readonly _tag: Tag;
         readonly message: string;
@@ -85,6 +95,7 @@ export declare class MailboxEventStreamError<Tag extends MailboxEventStreamError
         readonly fields?: MailboxEventStreamErrorFields | undefined;
         readonly retryAfterSeconds?: number | undefined;
         readonly serverTag?: string | undefined;
+        readonly reason?: MailboxEventStreamErrorReason | undefined;
     });
 }
 /** Every stream error as a union over `_tag`, so `Effect.catchTag` can narrow it. */
@@ -113,6 +124,17 @@ export interface MailboxEventStreamSocket {
 export type MailboxEventStreamWebSocket = new (url: string, options: {
     readonly headers: Readonly<Record<string, string>>;
 }) => MailboxEventStreamSocket;
+/** A reconnect the stream is about to make. */
+export interface MailboxEventStreamReconnect {
+    /** Why the connection ended: the error the stream would have ended with had it not retried. */
+    readonly error: MailboxEventStreamError;
+    /** The cursor the next connection resumes from; undefined when the stream started live and has none yet. */
+    readonly cursor: string | undefined;
+    /** Failed attempts in a row, starting at 1; a connection that went live resets it. */
+    readonly attempt: number;
+    /** How long the stream waits before connecting again. */
+    readonly delayMillis: number;
+}
 export interface MailboxEventStreamOptions {
     /** Resume after this cursor: every retained event after it, then live. Omit to start live. */
     readonly cursor?: string | undefined;
@@ -124,6 +146,11 @@ export interface MailboxEventStreamOptions {
     readonly onLive?: (() => void) | undefined;
     /** Reconnect after transient closes. Defaults to `true`. */
     readonly reconnect?: boolean | undefined;
+    /**
+     * Called when a transient failure ends a connection and the stream is about to reconnect from
+     * its last handled cursor, before the backoff wait. Never called when `reconnect` is `false`.
+     */
+    readonly onReconnect?: ((reconnect: MailboxEventStreamReconnect) => void) | undefined;
     /**
      * The events origin, such as `wss://events.samva.dev`. Defaults to the API origin with its
      * `api` host label replaced by `events`.

package/dist/{mailbox-events-VKR4f3qq.js → mailbox-events.js}

@@ -6,7 +6,8 @@
 * {@link MailboxEventStream} is an async iterable. The loop body handling an event is the
 * acknowledgement: asking for the next event marks the previous one handled, and the stream
 * resumes from the last handled event whenever it reconnects. Transient closes reconnect by
-* themselves; a close the caller has to act on ends the loop with a {@link MailboxEventStreamError}.
+* themselves, and a normal close (1000) from the host ends the loop after the events already
+* received; a close the caller has to act on ends the loop with a {@link MailboxEventStreamError}.
 *
 * This module has no runtime dependencies so the Promise and Effect clients share it.
 */
@@ -66,6 +67,8 @@ var MailboxEventStreamError = class extends Error {
 	retryAfterSeconds;
 	/** The tag the host sent, when it is not one this client maps. */
 	serverTag;
+	/** Set when the client ended the connection itself; see {@link MailboxEventStreamErrorReason}. */
+	reason;
 	constructor(input) {
 		super(input.message);
 		this._tag = input._tag;
@@ -75,9 +78,12 @@ var MailboxEventStreamError = class extends Error {
 		this.fields = input.fields;
 		this.retryAfterSeconds = input.retryAfterSeconds;
 		this.serverTag = input.serverTag;
+		this.reason = input.reason;
 	}
 };
 const OPEN = 1;
+/** The close code a host ends a finished stream with. */
+const NORMAL_CLOSE = 1e3;
 /** Acknowledge after this many handled events, well inside the server's window of 256. */
 const ACK_EVERY = 32;
 const RETRY_BASE_MILLIS = 500;
@@ -300,7 +306,7 @@ var MailboxEventStream = class {
 	* {@link markHandled} was called, so a resume repeats it. A pending iteration finishes.
 	*/
 	close() {
-		if (this.#ended) return;
+		if (this.#closed) return;
 		this.#ack();
 		this.#ended = true;
 		this.#closed = true;
@@ -349,10 +355,13 @@ var MailboxEventStream = class {
 			draining?.resolve();
 			this.#ack();
 			if (this.#error !== void 0) throw this.#errorAtCursor(this.#error);
-			if (this.#ended) return {
-				done: true,
-				value: void 0
-			};
+			if (this.#ended) {
+				this.#callerSignal?.removeEventListener("abort", this.#onCallerAbort);
+				return {
+					done: true,
+					value: void 0
+				};
+			}
 			await new Promise((resolve) => {
 				this.#waiting = { resolve };
 			});
@@ -418,8 +427,16 @@ var MailboxEventStream = class {
 				attempt = 0;
 			});
 			if (this.#ended || outcome.kind === "stopped") return;
+			if (outcome.kind === "closed" && outcome.code === NORMAL_CLOSE) {
+				this.#finish();
+				return;
+			}
 			let result;
 			if (outcome.kind === "closed") result = closeOutcome(outcome.code);
+			else if (outcome.kind === "idle") result = outcomeOf("StreamDisconnectedError", true, {
+				reason: "idleTimeout",
+				message: `No frame from the events host in ${MAILBOX_EVENT_STREAM_IDLE_MILLIS / 1e3} seconds, so the stream closed the connection.`
+			});
 			else {
 				const refusal = await this.#diagnose();
 				result = refusal === void 0 ? outcomeOf("StreamDisconnectedError", true) : refusalOutcome(refusal);
@@ -430,9 +447,23 @@ var MailboxEventStream = class {
 			}
 			const backoff = Math.min(RETRY_MAX_MILLIS, RETRY_BASE_MILLIS * 2 ** attempt);
 			attempt += 1;
-			await sleep(result.retryAfterMillis ?? backoff / 2 + Math.random() * (backoff / 2), this.#stop.signal);
+			const delayMillis = result.retryAfterMillis ?? backoff / 2 + Math.random() * (backoff / 2);
+			this.#options.onReconnect?.({
+				error: this.#withCursor(result.error),
+				cursor: this.#resumeCursor(),
+				attempt,
+				delayMillis
+			});
+			await sleep(delayMillis, this.#stop.signal);
 		}
 	}
+	/** End the iteration after the buffered events, with no error. */
+	#finish() {
+		if (this.#ended) return;
+		this.#ended = true;
+		this.#stop.abort();
+		this.#wake();
+	}
 	#withCursor(error) {
 		return new MailboxEventStreamError({
 			...error,
@@ -464,10 +495,7 @@ var MailboxEventStream = class {
 			const armIdle = () => {
 				clearTimeout(idleTimer);
 				idleTimer = setTimeout(() => {
-					settle(opened ? {
-						kind: "closed",
-						code: 1006
-					} : { kind: "refused" });
+					settle(opened ? { kind: "idle" } : { kind: "refused" });
 					socket.close(1e3);
 				}, MAILBOX_EVENT_STREAM_IDLE_MILLIS);
 			};
@@ -626,6 +654,6 @@ const readRefusalBody = async (response) => {
 	}
 };
 //#endregion
-export { MailboxEventStreamError as n, MailboxEventStream as t };
+export { MAILBOX_EVENT_STREAM_IDLE_MILLIS, MAILBOX_EVENT_STREAM_PATH, MAILBOX_EVENT_STREAM_PING_FRAME, MAILBOX_EVENT_STREAM_PING_MILLIS, MailboxEventStream, MailboxEventStreamCloseCode, MailboxEventStreamError, mailboxEventsUrl };
 
-//# sourceMappingURL=mailbox-events-VKR4f3qq.js.map
+//# sourceMappingURL=mailbox-events.js.map

package/dist/{normalize-B79uJIeb.js → normalize.js}

@@ -67,6 +67,6 @@ function buildMessagesSendPayload(input) {
 	};
 }
 //#endregion
-export { buildMessagesSendPayload as n, replyToEmailsPayload as r, buildEmailSendPayload as t };
+export { buildEmailSendPayload, buildMessagesSendPayload, replyToEmailsPayload };
 
-//# sourceMappingURL=normalize-B79uJIeb.js.map
+//# sourceMappingURL=normalize.js.map

package/dist/package.js

@@ -0,0 +1,6 @@
+//#region package.json
+var version = "0.19.0";
+//#endregion
+export { version };
+
+//# sourceMappingURL=package.js.map