@cosmicdrift/kumiko-bundled-features 0.392.2 → 0.394.0

package/dist/inbound-mail-foundation/watch-supervisor.js

@@ -42,37 +42,36 @@
 // only while the connection is open. Losing the claim (for example through
 // a Redis outage or expired TTL) tears down the local watcher instead of
 // racing a new holder.
-import { configuredPiiSubjectKms, decryptPiiFieldValues, } from "@cosmicdrift/kumiko-framework/crypto";
-import { fetchOne, insertOne, selectMany, updateMany } from "@cosmicdrift/kumiko-framework/db";
 import { SYSTEM_USER_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { systemScopedRunner, tenantScopedSecrets, } from "@cosmicdrift/kumiko-framework/internal/row-level-security";
-import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+import { mapWithConcurrency } from "../shared/index.js";
+import { createAccountHealth } from "./account-health.js";
+import { createAccountPoller } from "./account-poll.js";
+import { pollScheduleOf, withPollDeadline } from "./account-poll-schedule.js";
+import { registerMailAccountWakeListener } from "./account-wake.js";
 import { InboundMailAccountStatuses, InboundMailFoundationHandlers } from "./constants.js";
-import { MAIL_ACCOUNT_PII_FIELDS, seenMessageTable, syncCursorTable } from "./entities.js";
-import { createOAuthAccessTokenManager, usesFoundationManagedOAuth, } from "./oauth-access-token.js";
-import { mailAccountsProjectionTable } from "./projection.js";
+import { describeError } from "./describe-error.js";
+import { currentCountBucket } from "./ingest-failures.js";
+import { createOAuthAccessTokenManager, usesFoundationManagedOAuth } from "./oauth-access-token.js";
+import { isInboundAuthError, isInboundCursorInvalidError, isInboundRateLimitError, } from "./provider-errors.js";
 import { resolveInboundProviderForAccount } from "./provider-factory.js";
-import { isInboundAuthError, isInboundCursorInvalidError, isInboundRateLimitError, } from "./types.js";
-// Provider errors can embed token or response data in `message`; logs carry
-// only the error class.
-function describeError(err) {
-    return err instanceof Error ? err.name : typeof err;
-}
+import { createMessageIngester } from "./supervisor-ingest.js";
+import { createSyncAccountNow, runExclusivePerAccount, } from "./sync-account-now.js";
+import { createSyncCursorStore } from "./sync-cursor-store.js";
+import { listSyncableAccounts } from "./syncable-accounts.js";
+import { createWatchCatchUp } from "./watch-catch-up.js";
+import { createWatchLease } from "./watch-lease.js";
 const DEFAULT_POLL_INTERVAL_MS = 5 * 60 * 1000;
 const DEFAULT_BACKFILL_WINDOW_DAYS = 30;
 const DEFAULT_MAX_MESSAGES_PER_POLL = 200;
 const DEFAULT_WATCH_BACKOFF_INITIAL_MS = 5_000;
 const DEFAULT_WATCH_BACKOFF_MAX_MS = 5 * 60 * 1000;
 const DEFAULT_WATCH_LEASE_TTL_SECONDS = 90;
-/** One cursor per account (one mailbox inbox) for now; multi-folder support
- *  can add further scopes later without a schema change. */
-const CURSOR_SCOPE = "default";
-const SEEN_LOOKUP_CHUNK_SIZE = 1000;
 export function createInboundMailSupervisor(deps) {
     const pollIntervalMs = deps.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
     const backfillWindowDays = deps.backfillWindowDays ?? DEFAULT_BACKFILL_WINDOW_DAYS;
     const maxMessagesPerPoll = deps.maxMessagesPerPoll ?? DEFAULT_MAX_MESSAGES_PER_POLL;
+    const { pollConcurrency, accountPollDeadlineMs } = pollScheduleOf(deps);
     const backoffInitialMs = deps.watchBackoffInitialMs ?? DEFAULT_WATCH_BACKOFF_INITIAL_MS;
     const backoffMaxMs = deps.watchBackoffMaxMs ?? DEFAULT_WATCH_BACKOFF_MAX_MS;
     const leaseTtlSeconds = deps.watchLeaseTtlSeconds ?? DEFAULT_WATCH_LEASE_TTL_SECONDS;
@@ -112,135 +111,16 @@ export function createInboundMailSupervisor(deps) {
     let running = false;
     let pollTimer = null;
     let pollInFlight = null;
+    let unregisterWake = null;
     const watchers = new Map();
-    // ---------------------------------------------------------------
-    // Account snapshot: active accounts of all tenants with the address
-    // decrypted (providers never work with ciphertext).
-    // ---------------------------------------------------------------
-    async function listActiveAccounts() {
-        const rows = await selectMany(systemDb, mailAccountsProjectionTable, {
-            status: InboundMailAccountStatuses.active,
-        });
-        const piiKms = configuredPiiSubjectKms();
-        const records = [];
-        for (const row of rows) {
-            let decrypted;
-            try {
-                decrypted = piiKms
-                    ? await decryptPiiFieldValues(row, MAIL_ACCOUNT_PII_FIELDS, piiKms, {
-                        requestId: "inbound-mail-foundation:supervisor:list-accounts",
-                    })
-                    : row;
-            }
-            catch (error) {
-                // Class name only: the message may carry ciphertext or key details.
-                const errorName = error instanceof Error ? error.name : "unknown error";
-                log(`inbound-mail: account ${row.id} skipped — address did not decrypt (${errorName})`);
-                continue;
-            }
-            const decryptedAddress = decrypted["address"];
-            // Falling back to row.address would hand the ciphertext to a provider.
-            // One undecryptable account must not stop polling of every other tenant's accounts.
-            if (typeof decryptedAddress !== "string") {
-                log(`inbound-mail: account ${row.id} skipped — address did not decrypt to text`);
-                continue;
-            }
-            records.push({
-                id: row.id,
-                tenantId: row.tenantId,
-                provider: row.provider,
-                authMethod: row.authMethod,
-                ownerUserId: row.ownerUserId ?? null,
-                address: decryptedAddress,
-                displayName: row.displayName ?? "",
-                status: InboundMailAccountStatuses.active,
-                watchState: row.watchState ?? "idle",
-            });
-        }
-        return records;
-    }
-    // ---------------------------------------------------------------
-    // Cursor-Persistenz (unmanaged direct-write store).
-    // ---------------------------------------------------------------
-    async function loadCursor(accountId) {
-        const row = await fetchOne(systemDb, syncCursorTable, {
-            accountId,
-            scope: CURSOR_SCOPE,
-        });
-        if (!row)
-            return null;
-        try {
-            const parsed = JSON.parse(row.cursor);
-            return isPlainObject(parsed) ? parsed : null;
-        }
-        catch {
-            return null; // a corrupt cursor counts as none → backfill; dedup catches duplicates
-        }
-    }
-    async function saveCursor(account, cursor) {
-        const accountId = account.id;
-        const now = Temporal.Now.instant().toString();
-        const serialized = JSON.stringify(cursor);
-        const existing = await fetchOne(systemDb, syncCursorTable, {
-            accountId,
-            scope: CURSOR_SCOPE,
-        });
-        if (existing) {
-            await updateMany(systemDb, syncCursorTable, { cursor: serialized, updatedAt: now }, { accountId, scope: CURSOR_SCOPE });
-            // skip: the update path is complete; do not fall through to the insert branch.
-            return;
-        }
-        await insertOne(systemDb, syncCursorTable, {
-            id: crypto.randomUUID(),
-            // Direct-write store: no executor stamps the NOT NULL tenant_id for us.
-            tenantId: account.tenantId,
-            accountId,
-            scope: CURSOR_SCOPE,
-            cursor: serialized,
-            updatedAt: now,
-        });
-    }
-    async function resetCursor(accountId) {
-        // No deleteMany import is needed: an empty cursor parses to null, so the
-        // next fetch runs as a backfill.
-        await updateMany(systemDb, syncCursorTable, { cursor: "", updatedAt: Temporal.Now.instant().toString() }, { accountId, scope: CURSOR_SCOPE });
-    }
-    // ---------------------------------------------------------------
-    // Ingest: every message goes through the standard write handler.
-    // ---------------------------------------------------------------
-    async function ingestBatch(account, msgs, cursorSnapshot) {
-        for (const msg of msgs) {
-            const bodyRef = deps.storeBody && msg.rawMime ? await deps.storeBody(account, msg) : "";
-            const result = await deps.dispatchWrite({
-                handlerQn: InboundMailFoundationHandlers.ingestMessage,
-                tenantId: account.tenantId,
-                payload: {
-                    accountId: account.id,
-                    ownerUserId: account.ownerUserId,
-                    providerName: account.provider,
-                    providerMessageId: msg.providerMessageId,
-                    messageIdHeader: msg.messageIdHeader,
-                    providerThreadId: msg.providerThreadId,
-                    references: msg.references,
-                    from: msg.from,
-                    to: msg.to,
-                    cc: msg.cc,
-                    subject: msg.subject,
-                    snippet: msg.snippet,
-                    receivedAtIso: msg.receivedAtIso,
-                    bodyRef,
-                    scope: msg.scope,
-                    providerCursor: cursorSnapshot,
-                },
-            });
-            if (!result.isSuccess) {
-                // A single-message failure aborts the batch without persisting the cursor.
-                // The next tick refetches from the old cursor, and deduplication skips
-                // messages that were already processed.
-                throw new Error(`ingest-message failed for account ${account.id}: ${JSON.stringify(result.error ?? {})}`);
-            }
-        }
-    }
+    const cursors = createSyncCursorStore(systemDb);
+    const ingester = createMessageIngester({
+        db: systemDb,
+        dispatchWrite: deps.dispatchWrite,
+        log,
+        ...(deps.storeBody && { storeBody: deps.storeBody }),
+    });
+    const health = createAccountHealth({ db: systemDb, dispatchWrite: deps.dispatchWrite, log });
     async function markAccount(account, fields, reason) {
         await deps.dispatchWrite({
             handlerQn: InboundMailFoundationHandlers.updateAccount,
@@ -265,162 +145,113 @@ export function createInboundMailSupervisor(deps) {
         }
         if (isInboundCursorInvalidError(err)) {
             log(`inbound-mail: account ${account.id} cursor invalid — full resync in backfill window`);
-            await resetCursor(account.id);
+            await cursors.reset(account.id);
             return true;
         }
         // Transient or unknown error: log it and retry on the next tick.
         log(`inbound-mail: account ${account.id} sync error: ${describeError(err)}`);
         return true;
     }
-    // ---------------------------------------------------------------
-    // Poll (Reconciliation).
-    // ---------------------------------------------------------------
-    function unknownMessageIdsFilterFor(account) {
-        return async (providerMessageIds) => {
-            if (providerMessageIds.length === 0)
-                return new Set();
-            // One bind parameter per id: a full-mailbox listing would exceed Postgres' 65535 limit.
-            const seenIds = new Set();
-            for (let start = 0; start < providerMessageIds.length; start += SEEN_LOOKUP_CHUNK_SIZE) {
-                const seen = await selectMany(systemDb, seenMessageTable, {
-                    tenantId: account.tenantId,
-                    accountId: account.id,
-                    providerMessageId: {
-                        in: providerMessageIds.slice(start, start + SEEN_LOOKUP_CHUNK_SIZE),
-                    },
-                }, { fields: ["providerMessageId"] });
-                for (const row of seen)
-                    seenIds.add(row.providerMessageId);
-            }
-            return new Set(providerMessageIds.filter((id) => !seenIds.has(id)));
-        };
-    }
-    async function pollAccount(account, plugin) {
-        let cursor = await loadCursor(account.id);
-        let budget = maxMessagesPerPoll;
+    const { pollAccount } = createAccountPoller({
+        systemDb,
+        cursors,
+        ingester,
+        health,
+        providerCtx,
+        dispatchWrite: deps.dispatchWrite,
+        backfillWindowDays,
+        maxMessagesPerPoll,
+        resolveAccessToken,
+        handleSyncError,
+        log,
+    });
+    function resolvePluginOrLog(account) {
         try {
-            // hasMore loop: paginate within this tick until the message budget is
-            // exhausted.
-            for (;;) {
-                const accessToken = await resolveAccessToken(account, plugin);
-                const result = await plugin.fetch(providerCtx, account, cursor, {
-                    backfillWindowDays,
-                    maxMessages: budget,
-                    filterUnknownMessageIds: unknownMessageIdsFilterFor(account),
-                    ...(accessToken !== undefined && { accessToken }),
-                });
-                await ingestBatch(account, result.messages, JSON.stringify(result.nextCursor));
-                await saveCursor(account, result.nextCursor);
-                cursor = result.nextCursor;
-                budget -= result.messages.length;
-                if (!result.hasMore || budget <= 0)
-                    break;
-            }
+            return resolveInboundProviderForAccount(providerCtx, account);
         }
         catch (err) {
-            await handleSyncError(account, err);
+            log(`inbound-mail: ${describeError(err)}`);
+            return undefined;
+        }
+    }
+    const inFlightSyncs = new Map();
+    const pollAccountWithDeadline = withPollDeadline(pollAccount, {
+        ms: accountPollDeadlineMs,
+        onDeadline: async (account) => {
+            log(`inbound-mail: account ${account.id} sync passed its ${accountPollDeadlineMs}ms deadline`);
+            await health.onPollFailure(account, "transient");
+        },
+    });
+    async function pollAccountOfTick(account, plugin) {
+        // Joining would hang this tick on the same stuck sync; wake and syncAccountNow still join.
+        if (inFlightSyncs.has(account.id)) {
+            log(`inbound-mail: account ${account.id} is still syncing, skipped this tick`);
         }
+        else {
+            await runExclusivePerAccount(inFlightSyncs, account.id, async () => {
+                await pollAccountWithDeadline(account, plugin, {
+                    countBucket: currentCountBucket(deps.now, pollIntervalMs),
+                });
+            });
+        }
+        if (running)
+            await ensureWatcher(account, plugin);
     }
     async function pollOnce() {
-        const accounts = await listActiveAccounts();
-        for (const account of accounts) {
-            let plugin;
+        const accounts = await listSyncableAccounts(systemDb, log, { health });
+        // One account failing must not abort the others, and mapWithConcurrency would reject on the first error.
+        await mapWithConcurrency(accounts, Math.max(1, pollConcurrency), async (account) => {
             try {
-                plugin = resolveInboundProviderForAccount(providerCtx, account);
+                const plugin = resolvePluginOrLog(account);
+                if (plugin)
+                    await pollAccountOfTick(account, plugin);
             }
             catch (err) {
-                log(`inbound-mail: ${describeError(err)}`);
-                continue;
+                log(`inbound-mail: account ${account.id} tick failed: ${describeError(err)}`);
             }
-            await pollAccount(account, plugin);
-            if (running)
-                await ensureWatcher(account, plugin);
-        }
-        // Remove watchers for accounts that are no longer active.
-        const activeIds = new Set(accounts.map((a) => a.id));
+        });
+        // Remove watchers for accounts that are no longer syncable.
+        const syncableIds = new Set(accounts.map((a) => a.id));
         for (const accountId of watchers.keys()) {
-            if (!activeIds.has(accountId))
+            if (!syncableIds.has(accountId))
                 await stopWatcher(accountId);
         }
     }
+    const watchCatchUp = createWatchCatchUp({
+        inFlight: inFlightSyncs,
+        pollAccount: pollAccountWithDeadline,
+        isRunning: () => running,
+        log,
+    });
+    const syncAccountNow = createSyncAccountNow({
+        inFlight: inFlightSyncs,
+        loadAccount: async (onlyAccountId) => (await listSyncableAccounts(systemDb, log, { onlyAccountId }))[0],
+        resolvePlugin: resolvePluginOrLog,
+        pollAccount: pollAccountWithDeadline,
+        ensureWatcher,
+        isRunning: () => running,
+    });
     // ---------------------------------------------------------------
     // Watch lifecycle with backoff restart.
     // ---------------------------------------------------------------
-    // Heartbeat for a held watch lease. Independent of the connection's own
-    // lifecycle — it keeps renewing across reconnect backoff, not just while
-    // `plugin.watch()` is actually connected, so a flaky IMAP link doesn't
-    // make this worker lose the account to a peer mid-backoff.
-    function scheduleRenew(account, state, generation) {
-        state.renewTimer = setTimeout(() => {
-            void renewLeaseOnce(account, state, generation);
-        }, renewIntervalMs);
-    }
-    async function tearDownAfterRenewFailures(account, state, reason) {
-        log(`inbound-mail: watch lease ${reason} for account ${account.id} — tearing down local watcher`);
-        state.lockToken = null;
-        await stopWatcher(account.id);
-    }
-    async function renewLeaseOnce(account, state, generation) {
-        state.renewTimer = null;
-        // skip: supervisor stopped, generation superseded, or lease already lost — stale timer fire, nothing to renew.
-        if (!running || state.generation !== generation || !state.lockToken || !deps.lock)
-            return;
-        let renewed;
-        try {
-            renewed = await deps.lock.renew(account.id, state.lockToken, leaseTtlSeconds);
-        }
-        catch (err) {
-            log(`inbound-mail: watch lease renew for account ${account.id} failed: ${describeError(err)}`);
-            state.renewFailures += 1;
-            // After failures spanning a full lease TTL, tear down — otherwise a
-            // peer can acquire the expired key while we still hold an IDLE conn.
-            if (state.renewFailures * renewIntervalMs >= leaseTtlSeconds * 1000) {
-                await tearDownAfterRenewFailures(account, state, "renew failed across TTL");
-                // skip: connection torn down, no reschedule
-                return;
-            }
-            rescheduleIfStillHeld(account, state, generation);
-            // skip: renew failed but TTL not yet exhausted, retry already scheduled
-            return;
-        }
-        state.renewFailures = 0;
-        if (!renewed) {
-            await tearDownAfterRenewFailures(account, state, "lost");
-            // skip: lease lost and torn down, nothing to reschedule
-            return;
-        }
-        rescheduleIfStillHeld(account, state, generation);
-    }
-    function rescheduleIfStillHeld(account, state, generation) {
-        if (running && state.generation === generation && state.lockToken) {
-            scheduleRenew(account, state, generation);
-        }
-    }
-    // kumiko-lint-ignore complexity-budget yield-point stale-map check after acquire is intentional
-    async function acquireWatchLease(account, state) {
-        if (!deps.lock || state.lockToken)
-            return "acquired";
-        const token = await deps.lock.acquire(account.id, { ttlSeconds: leaseTtlSeconds });
-        if (!token)
-            return "no-token";
-        // The acquire() await is a yield point: a concurrent stopWatcher()
-        // (e.g. from a lost-lease renewal on a different generation) may have
-        // already retired this exact state and removed it from the map. If so,
-        // committing the fresh token onto it would leak the lease — nothing
-        // would ever release it, blocking failover for the full TTL.
-        if (watchers.get(account.id) !== state) {
-            await deps.lock.release(account.id, token);
-            return "stale";
-        }
-        state.lockToken = token;
-        scheduleRenew(account, state, state.generation);
-        return "acquired";
-    }
+    const watchLease = createWatchLease({
+        lock: deps.lock,
+        ttlSeconds: leaseTtlSeconds,
+        renewIntervalMs,
+        watchers,
+        isRunning: () => running,
+        stopWatcher,
+        log,
+    });
     // kumiko-lint-ignore complexity-budget watch lifecycle (start/stop/restart) stays cohesive
     async function ensureWatcher(account, plugin) {
         // skip: provider without live push; the reconciliation poll covers the account.
         if (!plugin.watch)
             return;
+        const stale = watchers.get(account.id);
+        if (stale?.stop && stale.trustedAuthservId !== (account.trustedAuthservId ?? null)) {
+            await stopWatcher(account.id);
+        }
         const existing = watchers.get(account.id);
         // skip: the watcher is already running, starting, or scheduled for restart.
         if (existing?.stop || existing?.restartTimer || existing?.starting)
@@ -434,27 +265,21 @@ export function createInboundMailSupervisor(deps) {
             renewTimer: null,
             renewFailures: 0,
             starting: false,
+            trustedAuthservId: null,
         };
         watchers.set(account.id, state);
-        const leaseResult = await acquireWatchLease(account, state);
-        if (leaseResult === "no-token") {
-            // Another worker already holds this account's watch lease — the poll
-            // still covers it, this worker just doesn't open a second IDLE
-            // connection. Retried on the next tick.
-            if (!existing)
+        state.starting = true;
+        const leaseResult = await watchLease.acquire(account, state);
+        if (leaseResult !== "acquired") {
+            if (leaseResult === "no-token" && !existing)
                 watchers.delete(account.id);
-            // skip: no lease token acquired above — nothing more to set up here.
-            return;
-        }
-        if (leaseResult === "stale") {
-            // skip: state was retired by a concurrent stopWatcher while acquire()
-            // awaited — committing here would leak the lease.
+            state.starting = false;
+            // skip: no-token means the poll still covers the account and the next tick retries; stale means stopWatcher retired this state.
             return;
         }
         const generation = state.generation;
         const scheduleRestart = (err) => {
-            // skip: the supervisor stopped or the watcher generation changed; a restart
-            // would create a zombie watcher.
+            // skip: stopped or superseded generation; a restart would create a zombie watcher.
             if (!running || state.generation !== generation)
                 return;
             state.stop = null;
@@ -467,13 +292,13 @@ export function createInboundMailSupervisor(deps) {
                 void ensureWatcher(account, plugin);
             }, delay);
         };
-        state.starting = true;
+        state.trustedAuthservId = account.trustedAuthservId ?? null;
         try {
             const accessToken = await resolveAccessToken(account, plugin);
             const stop = await plugin.watch(providerCtx, account, {
-                onMessages: async (msgs) => {
+                onMessages: async (msgs, rejected = []) => {
                     try {
-                        await ingestBatch(account, msgs, "watch");
+                        await ingester.ingestBatch(account, msgs, rejected, "watch");
                     }
                     catch (err) {
                         // An ingest failure must not kill the watcher: the next poll
@@ -509,6 +334,7 @@ export function createInboundMailSupervisor(deps) {
             catch (err) {
                 log(`inbound-mail: markAccount(watching) for account ${account.id} failed: ${describeError(err)}`);
             }
+            watchCatchUp.schedule(account, plugin);
         }
         catch (err) {
             const keepRunning = await handleSyncError(account, err);
@@ -581,18 +407,25 @@ export function createInboundMailSupervisor(deps) {
             if (running)
                 return;
             running = true;
+            unregisterWake = registerMailAccountWakeListener((_tenantId, accountId) => {
+                syncAccountNow(accountId).catch((err) => log(`inbound-mail: wake sync for account ${accountId} failed: ${describeError(err)}`));
+            });
             await pollOnce();
             scheduleNextPoll();
         },
         pollOnce,
+        syncAccountNow,
         async stop() {
             running = false;
+            unregisterWake?.();
+            unregisterWake = null;
             if (pollTimer) {
                 clearTimeout(pollTimer);
                 pollTimer = null;
             }
             if (pollInFlight)
                 await pollInFlight;
+            await Promise.allSettled([...inFlightSyncs.values(), watchCatchUp.settled()]);
             for (const accountId of [...watchers.keys()]) {
                 await stopWatcher(accountId);
             }

package/dist/inbound-mail-foundation/web/client-plugin.d.ts

@@ -0,0 +1,14 @@
+import type { ClientFeatureDefinition } from "@cosmicdrift/kumiko-renderer/web";
+export type InboundMailFoundationClientOptions = {
+    /** Mount path of the connect route, when the app moved it (`connectPath` of
+     *  createInboundMailConnectRoutes). Default "/api/inbound-mail/connect". */
+    readonly connectPath?: string;
+    /** Leaves the app for the provider's sign-in page. Default: `location.assign`. */
+    readonly navigate?: (url: string) => void;
+};
+export declare function oauthReconnectUrl(connectPath: string, row: {
+    readonly provider: string;
+    readonly address: string;
+    readonly ownerUserId?: string;
+}): string;
+export declare function inboundMailFoundationClient(options?: InboundMailFoundationClientOptions): ClientFeatureDefinition;

package/dist/inbound-mail-foundation/web/client-plugin.js

@@ -0,0 +1,40 @@
+// Client feature for inbound-mail-foundation. The mail account screens offer "Reactivate" for an OAuth
+// mailbox as a clientAction: signing in again is a browser redirect into the same connect route and
+// callback that created the mailbox, which a writeHandler cannot do.
+import { INBOUND_MAIL_CONNECT_PATH, INBOUND_MAIL_FOUNDATION_FEATURE, INBOUND_MAIL_RECONNECT_OAUTH_ACTION, } from "./constants.js";
+const INVALID_RECONNECT_ROW = "inboundMail.accounts.reconnect.invalidRow";
+function textField(payload, field) {
+    const value = payload[field];
+    return typeof value === "string" && value !== "" ? value : undefined;
+}
+// The callback trusts only the signed state, which the connect route builds from the session and these
+// parameters; scope "user" makes the signed-in caller the owner, so the route re-checks ownership.
+export function oauthReconnectUrl(connectPath, row) {
+    const query = new URLSearchParams({
+        provider: row.provider,
+        scope: row.ownerUserId === undefined ? "shared" : "user",
+        mailbox: row.address,
+    });
+    return `${connectPath}?${query.toString()}`;
+}
+function reconnectOauthHandler(connectPath, navigate) {
+    return async (payload) => {
+        const provider = textField(payload, "provider");
+        const address = textField(payload, "address");
+        if (provider === undefined || address === undefined) {
+            return { ok: false, message: INVALID_RECONNECT_ROW };
+        }
+        const ownerUserId = textField(payload, "ownerUserId");
+        navigate(oauthReconnectUrl(connectPath, { provider, address, ...(ownerUserId && { ownerUserId }) }));
+        return { ok: true };
+    };
+}
+export function inboundMailFoundationClient(options = {}) {
+    const navigate = options.navigate ?? ((url) => globalThis.location.assign(url));
+    return {
+        name: INBOUND_MAIL_FOUNDATION_FEATURE,
+        clientActions: {
+            [INBOUND_MAIL_RECONNECT_OAUTH_ACTION]: reconnectOauthHandler(options.connectPath ?? INBOUND_MAIL_CONNECT_PATH, navigate),
+        },
+    };
+}

package/dist/inbound-mail-foundation/web/constants.d.ts

@@ -0,0 +1,5 @@
+export declare const INBOUND_MAIL_FOUNDATION_FEATURE: "inbound-mail-foundation";
+/** Default mount path of the OAuth connect route; the web client builds the reconnect link from it. */
+export declare const INBOUND_MAIL_CONNECT_PATH = "/api/inbound-mail/connect";
+/** Client action of the OAuth "Reactivate" row action: sends the browser to the OAuth connect route. */
+export declare const INBOUND_MAIL_RECONNECT_OAUTH_ACTION: string;

package/dist/inbound-mail-foundation/web/constants.js

@@ -0,0 +1,6 @@
+// Constants the browser client shares with the server feature; the server constants re-export them.
+export const INBOUND_MAIL_FOUNDATION_FEATURE = "inbound-mail-foundation";
+/** Default mount path of the OAuth connect route; the web client builds the reconnect link from it. */
+export const INBOUND_MAIL_CONNECT_PATH = "/api/inbound-mail/connect";
+/** Client action of the OAuth "Reactivate" row action: sends the browser to the OAuth connect route. */
+export const INBOUND_MAIL_RECONNECT_OAUTH_ACTION = `${INBOUND_MAIL_FOUNDATION_FEATURE}:reconnect-oauth`;

package/dist/inbound-mail-foundation/web/index.d.ts

@@ -0,0 +1 @@
+export { type InboundMailFoundationClientOptions, inboundMailFoundationClient, oauthReconnectUrl, } from "./client-plugin.ts";

package/dist/inbound-mail-foundation/web/index.js

@@ -0,0 +1 @@
+export { inboundMailFoundationClient, oauthReconnectUrl, } from "./client-plugin.js";