samva 0.10.0 → 0.12.0

package/dist/mailbox-events.d.ts

@@ -0,0 +1,178 @@
+/**
+ * The mailbox event stream: the `mailbox.*` events a webhook endpoint receives, delivered over a
+ * WebSocket to a program that has no public URL for webhooks to reach.
+ *
+ * {@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}.
+ *
+ * This module has no runtime dependencies so the Promise and Effect clients share it.
+ */
+/** The WebSocket path on the events host. */
+export declare const MAILBOX_EVENT_STREAM_PATH = "/v1/mailboxes/events";
+/** Close codes the events host ends an accepted connection with. */
+export declare const MailboxEventStreamCloseCode: {
+    /** The client sent a frame that is not an acknowledgement of a cursor it was sent. */
+    readonly invalidFrame: 4400;
+    /** The credential stopped authenticating: revoked, rotated, or expired. */
+    readonly unauthorized: 4401;
+    /** The credential authenticates but may no longer read mailboxes. */
+    readonly forbidden: 4403;
+    /** Mailboxes are unavailable to the organization. */
+    readonly gone: 4404;
+    /** Too many events went unacknowledged. Reconnecting from the last handled cursor recovers. */
+    readonly slowConsumer: 4408;
+    /** Events after the cursor are no longer retained. Read current state and start without one. */
+    readonly cursorExpired: 4410;
+    /** Access could not be confirmed for a while. Reconnecting from the last cursor recovers. */
+    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";
+/** 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. */
+    readonly cursor: string;
+    /** The event id: the `webhook-id` a webhook delivery of the same event carries. */
+    readonly id: string;
+    readonly type: MailboxEventType;
+    readonly timestamp: string;
+    /** The event's `data`, exactly as the webhook body carries it. */
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/**
+ * 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,
+ * `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";
+/** Field-level validation messages, keyed by dotted path, as a `ValidationError` carries them. */
+export type MailboxEventStreamErrorFields = Readonly<Record<string, ReadonlyArray<string>>>;
+/**
+ * A stream that ended. `_tag` names the cause and `message` says what to do next, as the host
+ * wrote it when the host refused. Branch on `_tag`; in the Effect client the stream fails with
+ * {@link MailboxEventStreamFailure}, which `Effect.catchTag` narrows by `_tag`.
+ *
+ * The stream retries by itself only where retrying can help: a transient close, an unreachable
+ * host, a `408`, a `429`, or a `5xx`. Every other refusal ends it, so a caller never loops on a
+ * request the host will keep refusing.
+ */
+export declare class MailboxEventStreamError<Tag extends MailboxEventStreamErrorTag = MailboxEventStreamErrorTag> extends Error {
+    readonly name = "MailboxEventStreamError";
+    readonly _tag: Tag;
+    /** The HTTP status, when the host refused the connection before accepting it. */
+    readonly status: number | undefined;
+    /** The WebSocket close code, when the host closed an accepted connection. */
+    readonly closeCode: number | undefined;
+    /** The last handled cursor; reconnect with it unless `_tag` is `CursorExpiredError`. */
+    readonly cursor: string | undefined;
+    /** A `ValidationError`'s field messages, such as `fields.cursor` or `fields.mailboxId`. */
+    readonly fields: MailboxEventStreamErrorFields | undefined;
+    /** How long a `RateLimitedError` or `ServiceUnavailableError` asked the caller to wait. */
+    readonly retryAfterSeconds: number | undefined;
+    /** The tag the host sent, when it is not one this client maps. */
+    readonly serverTag: string | undefined;
+    constructor(input: {
+        readonly _tag: Tag;
+        readonly message: string;
+        readonly status?: number | undefined;
+        readonly closeCode?: number | undefined;
+        readonly cursor?: string | undefined;
+        readonly fields?: MailboxEventStreamErrorFields | undefined;
+        readonly retryAfterSeconds?: number | undefined;
+        readonly serverTag?: string | undefined;
+    });
+}
+/** Every stream error as a union over `_tag`, so `Effect.catchTag` can narrow it. */
+export type MailboxEventStreamFailure = {
+    [Tag in MailboxEventStreamErrorTag]: MailboxEventStreamError<Tag>;
+}[MailboxEventStreamErrorTag];
+/** The subset of the WebSocket API the stream uses. */
+export interface MailboxEventStreamSocket {
+    readonly readyState: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener(type: "open", listener: () => void): void;
+    addEventListener(type: "message", listener: (event: {
+        readonly data: unknown;
+    }) => void): void;
+    addEventListener(type: "error", listener: () => void): void;
+    addEventListener(type: "close", listener: (event: {
+        readonly code: number;
+        readonly reason: string;
+    }) => void): void;
+}
+/**
+ * A WebSocket constructor that accepts request headers, as Node's, Bun's, and the `ws` package's
+ * do. The stream authenticates the upgrade with the client's credential headers.
+ */
+export type MailboxEventStreamWebSocket = new (url: string, options: {
+    readonly headers: Readonly<Record<string, string>>;
+}) => MailboxEventStreamSocket;
+export interface MailboxEventStreamOptions {
+    /** Resume after this cursor: every retained event after it, then live. Omit to start live. */
+    readonly cursor?: string | undefined;
+    /** Only these mailboxes, within what the credential can read. Omit for every readable one. */
+    readonly mailboxIds?: ReadonlyArray<string> | undefined;
+    /** Ends the stream, as {@link MailboxEventStream.close} does. */
+    readonly signal?: AbortSignal | undefined;
+    /** Called each time replay has caught up and the stream is delivering live events. */
+    readonly onLive?: (() => void) | undefined;
+    /** Reconnect after transient closes. Defaults to `true`. */
+    readonly reconnect?: boolean | undefined;
+    /**
+     * The events origin, such as `wss://events.samva.dev`. Defaults to the API origin with its
+     * `api` host label replaced by `events`.
+     */
+    readonly eventsUrl?: string | undefined;
+    /** Defaults to the runtime's global `WebSocket`. */
+    readonly WebSocket?: MailboxEventStreamWebSocket | undefined;
+}
+/** What the stream needs from a configured client. */
+export interface MailboxEventStreamConnection {
+    readonly baseUrl: string;
+    /** The credential and attribution headers every request of the client carries. */
+    readonly headers: Readonly<Record<string, string>>;
+    readonly fetch?: typeof fetch | undefined;
+}
+/** The frame that asks the events host whether the connection is alive; pinned to the host's by a test. */
+export declare const MAILBOX_EVENT_STREAM_PING_FRAME = "{\"kind\":\"ping\"}";
+/** How often the stream sends a ping; pinned to the host's constant by a test. */
+export declare const MAILBOX_EVENT_STREAM_PING_MILLIS = 30000;
+/**
+ * How long a connection may stay silent before it is treated as dropped: three ping intervals, so
+ * one late or lost pong does not reconnect. The host sends nothing on a quiet mailbox, so the
+ * pong is the only proof of life; a socket that died without a close event is otherwise
+ * indistinguishable from a quiet mailbox.
+ */
+export declare const MAILBOX_EVENT_STREAM_IDLE_MILLIS: number;
+/** The events URL for an API origin: `https://api.samva.dev` → `wss://events.samva.dev/v1/…`. */
+export declare const mailboxEventsUrl: (connection: Pick<MailboxEventStreamConnection, "baseUrl">, options: Pick<MailboxEventStreamOptions, "eventsUrl" | "cursor" | "mailboxIds">) => URL;
+/**
+ * A resumable stream of mailbox events. Iterate it with `for await`; break out of the loop or call
+ * {@link close} to end it.
+ */
+export declare class MailboxEventStream implements AsyncIterable<MailboxEvent> {
+    #private;
+    constructor(connection: MailboxEventStreamConnection, options?: MailboxEventStreamOptions);
+    /**
+     * The position to resume from: the last handled event's cursor, or a later position the
+     * server confirmed with nothing in between for this stream. Undefined until there is one.
+     */
+    get cursor(): string | undefined;
+    /**
+     * Mark the event in hand handled now, before asking for the next one: for a caller that stops
+     * after handling it, so {@link close} acknowledges it and {@link cursor} moves past it.
+     */
+    markHandled(): void;
+    /**
+     * End the stream. Handled events are acknowledged; the event in hand is not, unless
+     * {@link markHandled} was called, so a resume repeats it. A pending iteration finishes.
+     */
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<MailboxEvent>;
+}

package/dist/mailboxes-BtcktcNB.js

@@ -0,0 +1,147 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.js";
+import { n as MailboxEventStreamError, t as MailboxEventStream } from "./mailbox-events-CsbF35vH.js";
+import { n as make } from "./operation-BEghYyLu.js";
+import { t as Service } from "./client-Cj1bqIEe.js";
+import { Cause, Effect, Exit, Stream } from "effect";
+//#region src/effect/internal/mailbox-events.ts
+const toStreamError = (cause) => cause instanceof MailboxEventStreamError ? cause : new MailboxEventStreamError({
+	_tag: "StreamDisconnectedError",
+	message: String(cause)
+});
+/**
+* The organization's mailbox events as a stream, resuming from `cursor`. An event counts as handled
+* once the stream is pulled again, or once it ends successfully after the event (as `Stream.take`
+* does); a failure or interruption leaves the event in hand unacknowledged, so a resume repeats it.
+* The stream fails with a {@link MailboxEventStreamFailure}, which `Effect.catchTag` narrows by the
+* `_tag` of the host's refusal.
+*/
+const events = (options = {}) => Stream.scoped(Stream.unwrap(Effect.gen(function* () {
+	const client = yield* Service;
+	const iterator = (yield* Effect.acquireRelease(Effect.try({
+		try: () => new MailboxEventStream(client.connection, options),
+		catch: toStreamError
+	}), (opened, exit) => Effect.sync(() => {
+		if (Exit.isSuccess(exit)) opened.markHandled();
+		opened.close();
+	})))[Symbol.asyncIterator]();
+	return Stream.fromEffectRepeat(Effect.tryPromise({
+		try: () => iterator.next(),
+		catch: toStreamError
+	}).pipe(Effect.flatMap((next) => next.done ? Cause.done() : Effect.succeed(next.value))));
+})));
+//#endregion
+//#region src/effect/mailboxes.ts
+var mailboxes_exports = /* @__PURE__ */ __exportAll({
+	MailboxEventStreamError: () => MailboxEventStreamError,
+	addThreadLabels: () => addThreadLabels,
+	approveAction: () => approveAction,
+	create: () => create,
+	createDraft: () => createDraft,
+	createGrant: () => createGrant,
+	createLabel: () => createLabel,
+	createNote: () => createNote,
+	createPolicy: () => createPolicy,
+	deleteDraft: () => deleteDraft,
+	deleteLabel: () => deleteLabel,
+	deleteNote: () => deleteNote,
+	deletePolicy: () => deletePolicy,
+	denyAction: () => denyAction,
+	discardMessage: () => discardMessage,
+	events: () => events,
+	forward: () => forward,
+	get: () => get,
+	getAgentActivity: () => getAgentActivity,
+	getDraft: () => getDraft,
+	getMessage: () => getMessage,
+	getMessageAttachment: () => getMessageAttachment,
+	getMessageRaw: () => getMessageRaw,
+	getPolicy: () => getPolicy,
+	getThread: () => getThread,
+	getThreadContent: () => getThreadContent,
+	list: () => list,
+	listActions: () => listActions,
+	listDrafts: () => listDrafts,
+	listEvents: () => listEvents,
+	listFolders: () => listFolders,
+	listGrants: () => listGrants,
+	listLabels: () => listLabels,
+	listPolicies: () => listPolicies,
+	listQuarantine: () => listQuarantine,
+	listThreadMessages: () => listThreadMessages,
+	listThreadNotes: () => listThreadNotes,
+	listThreads: () => listThreads,
+	pause: () => pause,
+	releaseMessage: () => releaseMessage,
+	remove: () => remove,
+	removeThreadLabels: () => removeThreadLabels,
+	reply: () => reply,
+	replyAll: () => replyAll,
+	resume: () => resume,
+	revokeGrant: () => revokeGrant,
+	sendDraft: () => sendDraft,
+	sendMessage: () => sendMessage,
+	update: () => update,
+	updateDraft: () => updateDraft,
+	updateGrant: () => updateGrant,
+	updateLabel: () => updateLabel,
+	updateNote: () => updateNote,
+	updatePolicy: () => updatePolicy,
+	updateThread: () => updateThread
+});
+const list = make("mailboxesList");
+const create = make("mailboxesCreate");
+const get = make("mailboxesGet");
+const update = make("mailboxesUpdate");
+const remove = make("mailboxesRemove");
+const pause = make("mailboxesPause");
+const resume = make("mailboxesResume");
+const getAgentActivity = make("mailboxesGetAgentActivity");
+const listGrants = make("mailboxesListGrants");
+const createGrant = make("mailboxesCreateGrant");
+const updateGrant = make("mailboxesUpdateGrant");
+const revokeGrant = make("mailboxesRevokeGrant");
+const listPolicies = make("mailboxesListPolicies");
+const createPolicy = make("mailboxesCreatePolicy");
+const getPolicy = make("mailboxesGetPolicy");
+const updatePolicy = make("mailboxesUpdatePolicy");
+const deletePolicy = make("mailboxesDeletePolicy");
+const listFolders = make("mailboxesListFolders");
+const listLabels = make("mailboxesListLabels");
+const createLabel = make("mailboxesCreateLabel");
+const updateLabel = make("mailboxesUpdateLabel");
+const deleteLabel = make("mailboxesDeleteLabel");
+const listThreads = make("mailboxesListThreads");
+const getThread = make("mailboxesGetThread");
+const updateThread = make("mailboxesUpdateThread");
+const addThreadLabels = make("mailboxesAddThreadLabels");
+const removeThreadLabels = make("mailboxesRemoveThreadLabels");
+const listThreadMessages = make("mailboxesListThreadMessages");
+const getThreadContent = make("mailboxesGetThreadContent");
+const listThreadNotes = make("mailboxesListThreadNotes");
+const createNote = make("mailboxesCreateNote");
+const updateNote = make("mailboxesUpdateNote");
+const deleteNote = make("mailboxesDeleteNote");
+const sendMessage = make("mailboxesSendMessage");
+const getMessage = make("mailboxesGetMessage");
+const getMessageRaw = make("mailboxesGetMessageRaw");
+const getMessageAttachment = make("mailboxesGetMessageAttachment");
+const reply = make("mailboxesReply");
+const replyAll = make("mailboxesReplyAll");
+const forward = make("mailboxesForward");
+const listQuarantine = make("mailboxesListQuarantine");
+const releaseMessage = make("mailboxesReleaseMessage");
+const discardMessage = make("mailboxesDiscardMessage");
+const listDrafts = make("mailboxesListDrafts");
+const createDraft = make("mailboxesCreateDraft");
+const getDraft = make("mailboxesGetDraft");
+const updateDraft = make("mailboxesUpdateDraft");
+const deleteDraft = make("mailboxesDeleteDraft");
+const sendDraft = make("mailboxesSendDraft");
+const listActions = make("mailboxesListActions");
+const approveAction = make("mailboxesApproveAction");
+const denyAction = make("mailboxesDenyAction");
+const listEvents = make("mailboxesListEvents");
+//#endregion
+export { updatePolicy as $, listGrants as A, remove as B, getThread as C, listDrafts as D, listActions as E, listThreadNotes as F, revokeGrant as G, reply as H, listThreads as I, update as J, sendDraft as K, mailboxes_exports as L, listPolicies as M, listQuarantine as N, listEvents as O, listThreadMessages as P, updateNote as Q, pause as R, getPolicy as S, list as T, replyAll as U, removeThreadLabels as V, resume as W, updateGrant as X, updateDraft as Y, updateLabel as Z, getAgentActivity as _, createGrant as a, getMessageAttachment as b, createPolicy as c, deleteNote as d, updateThread as et, deletePolicy as f, get as g, forward as h, createDraft as i, listLabels as j, listFolders as k, deleteDraft as l, discardMessage as m, approveAction as n, createLabel as o, denyAction as p, sendMessage as q, create as r, createNote as s, addThreadLabels as t, events as tt, deleteLabel as u, getDraft as v, getThreadContent as w, getMessageRaw as x, getMessage as y, releaseMessage as z };
+
+//# sourceMappingURL=mailboxes-BtcktcNB.js.map