@aitne/daemon 0.1.0

package/dist/services/mail/account-registry.d.ts

@@ -0,0 +1,208 @@
+import type Database from "better-sqlite3";
+import type { EncryptedBlobStore } from "../../secrets/encrypted-blob-store.js";
+import type { AuthStatus, MailAccount, MailAccountHealth, MailProvider, MailProviderKind, PollCursor } from "./provider.js";
+import { type ImapCapabilitySet } from "./imap/capabilities.js";
+interface MailAccountRow {
+    id: string;
+    kind: string;
+    email: string;
+    label: string | null;
+    auth_type: string;
+    auth_status: string;
+    secret_blob_name: string;
+    poll_interval_seconds: number;
+    idle_enabled: number;
+    idle_fallback_until: string | null;
+    unified_poll: number;
+    active: number;
+    created_at_utc: string;
+    last_error: string | null;
+    last_error_at_utc: string | null;
+    last_poll_at_utc: string | null;
+    consecutive_error_count: number;
+    imap_capabilities_json: string | null;
+}
+export declare function parseMailAccountRow(row: MailAccountRow): MailAccount;
+export declare function parseMailAccountHealth(row: MailAccountRow): MailAccountHealth;
+export interface ScopeGateInput {
+    kind: MailProviderKind;
+    active: boolean;
+    authStatus: AuthStatus;
+    unifiedPoll: boolean;
+}
+/**
+ * Pure scope-gate predicate (§3.2).
+ *
+ * The unified mail-poller and pre-materialized skill must only surface
+ * accounts matching ALL four conditions. Legacy gmail rows (unifiedPoll=false)
+ * pass through the legacy poller path and are intentionally excluded from the
+ * unified set to avoid double-polling.
+ */
+export declare function passesScopeGate(input: ScopeGateInput, enabledKinds: readonly MailProviderKind[]): boolean;
+export interface AddAccountInput {
+    kind: MailProviderKind;
+    email: string;
+    label?: string;
+    authType: "oauth" | "app_password";
+    secretPayload: string;
+    idleEnabled?: boolean;
+    pollIntervalSeconds?: number;
+    unifiedPoll?: boolean;
+    /**
+     * Capabilities captured at account-add smoke-test time (IMAP providers
+     * only). Persisted immediately so Phase 7 readers never see a NULL
+     * capability column on freshly-added rows — the runtime probe re-captures
+     * on first live connect, which is a no-op since capabilities are stable.
+     */
+    capabilities?: ImapCapabilitySet;
+}
+export declare class ProviderNotEnabledError extends Error {
+    readonly code = "provider_not_enabled";
+    constructor(kind: MailProviderKind);
+}
+export declare class ProviderNotImplementedError extends Error {
+    readonly code = "provider_not_implemented";
+    constructor(kind: MailProviderKind);
+}
+export declare class DuplicateAccountError extends Error {
+    readonly code = "duplicate_account";
+    constructor(kind: MailProviderKind, email: string);
+}
+/** Context passed to provider factories. Holds the per-account abort signal so
+ *  the provider can cancel in-flight I/O when removeAccount / disable fires. */
+export interface MailProviderFactoryContext {
+    signal: AbortSignal;
+}
+export type MailProviderFactory = (account: MailAccount, ctx: MailProviderFactoryContext) => MailProvider | Promise<MailProvider>;
+/**
+ * Reason codes emitted by {@link MailAccountRegistryOptions.onScopeChanged}.
+ * Mirrored by the session-workdir refresh handler so logs can correlate a
+ * mutation to its downstream effect.
+ */
+export type MailScopeChangeReason = "account_added" | "account_removed" | "account_activated" | "account_deactivated" | "account_reauthed" | "auth_status_recovered" | "auth_status_degraded" | "enabled_providers_changed";
+export interface MailAccountRegistryOptions {
+    db: Database.Database;
+    blobStore: EncryptedBlobStore;
+    getEnabledKinds: () => readonly MailProviderKind[];
+    /**
+     * Per-kind factories for instantiating live MailProvider instances. Wired
+     * by index.ts as the provider dependencies (shared Google OAuth, MSAL,
+     * ImapFlow) become available.
+     */
+    providerFactories?: Partial<Record<MailProviderKind, MailProviderFactory>>;
+    now?: () => Date;
+    /**
+     * Fires AFTER a mutation that changes the set of accounts passing the
+     * scope gate (`listActiveAccounts()`). Single source of truth — so route
+     * handlers cannot forget to notify. Only non-trivial transitions fire:
+     * - `setActive` only when the active bit actually changes.
+     * - `updateAuthStatus` only when crossing the healthy / non-healthy
+     *   boundary (so repeated degraded→requires_consent reclassifications
+     *   don't spam).
+     * - `onProviderSelectionChanged` only when `newKinds` differs from the
+     *   previous kind set.
+     * Synchronous and best-effort. Throws are caught and logged; they never
+     * interrupt the mutation.
+     */
+    onScopeChanged?: (reason: MailScopeChangeReason) => void;
+}
+/**
+ * Owns the set of configured mail accounts: DB rows, secret blobs, and live
+ * MailProvider instances. The provider cache is lazy and per-accountId.
+ *
+ * Per §3.2 each accountId owns an AbortController so {@link removeAccount}
+ * can cancel in-flight polls before tearing down credentials.
+ */
+export declare class MailAccountRegistry {
+    private readonly db;
+    private readonly blobStore;
+    private readonly getEnabledKinds;
+    private readonly providerFactories;
+    private readonly now;
+    private readonly onScopeChanged;
+    private readonly mutexes;
+    private readonly providerCache;
+    private readonly abortControllers;
+    /** Last kinds set passed to onProviderSelectionChanged, for no-op elision. */
+    private lastAnnouncedKinds;
+    constructor(options: MailAccountRegistryOptions);
+    listAccounts(): MailAccount[];
+    listActiveAccounts(): MailAccount[];
+    getAccount(accountId: string): MailAccount | null;
+    getHealth(accountId: string): MailAccountHealth | null;
+    /**
+     * Returns the current abort signal for an account. The controller is
+     * created lazily so callers (providers, pollers) always get a live signal
+     * even for accounts that haven't been touched yet. `removeAccount` aborts
+     * and drops the controller; the next caller mints a fresh one.
+     */
+    getAbortSignal(accountId: string): AbortSignal;
+    private getOrCreateAbortController;
+    addAccount(input: AddAccountInput): Promise<MailAccount>;
+    removeAccount(accountId: string): Promise<boolean>;
+    /**
+     * Replace the on-disk secret for an existing IMAP (app-password) account
+     * — used when the user rotates their Yahoo / iCloud app password and the
+     * account has flipped to `requires_consent`. The secret blob is overwritten
+     * in place (same name) so the account ID and poll cursor survive intact;
+     * the cached provider is evicted so the next poll opens a fresh IMAP
+     * session with the new credentials.
+     *
+     * Caller is responsible for verifying the new credentials against the IMAP
+     * server before calling — this method does not re-validate.
+     */
+    refreshImapSecret(accountId: string, secretPayload: string, capabilities?: ImapCapabilitySet): Promise<MailAccount | null>;
+    setActive(accountId: string, active: boolean): Promise<MailAccount | null>;
+    /**
+     * Atomic auth-status flip. Use the {@link effectiveAuthStatus} pure helper
+     * (auth-failure-classifier.ts) to decide what status to pass in.
+     *
+     * Fires `onScopeChanged` ONLY when crossing the `healthy` boundary
+     * (healthy → non-healthy or vice versa). Reclassifying within the
+     * non-healthy space (e.g. `degraded` → `requires_consent`) does not
+     * change scope-gate membership, so no notification.
+     */
+    updateAuthStatus(accountId: string, status: AuthStatus, lastError?: string | null): boolean;
+    /**
+     * Bookkeeping after a poll tick. `success=true` resets
+     * `consecutive_error_count` to 0 and clears `last_error`.
+     * `success=false` increments the counter and records the error.
+     */
+    recordPollTick(accountId: string, outcome: {
+        success: true;
+    } | {
+        success: false;
+        error: string;
+    }): boolean;
+    getConsecutiveErrorCount(accountId: string): number;
+    /**
+     * Persist the CAPABILITY probe for an account (§3 Phase 4). The provider
+     * calls this fire-and-forget on first connect; the row may not exist if the
+     * account was removed mid-connect, in which case the UPDATE is a no-op.
+     */
+    updateCapabilities(accountId: string, capabilities: ImapCapabilitySet): boolean;
+    getCapabilities(accountId: string): ImapCapabilitySet | null;
+    loadPollCursor(accountId: string): PollCursor | null;
+    savePollCursor(accountId: string, cursor: PollCursor): boolean;
+    /**
+     * Lazy provider lookup. Caches per accountId. Throws
+     * {@link ProviderNotImplementedError} if no factory is registered.
+     */
+    peekProvider(accountId: string): MailProvider | null;
+    getProvider(accountId: string): Promise<MailProvider | null>;
+    /** Drop a cached provider — used after auth failures so the next call rebuilds the MSAL/IMAP client fresh. */
+    evictProvider(accountId: string): void;
+    /**
+     * Scope-gate change hook (§6.0). Phase 2 evicts cached providers for kinds
+     * leaving the enabled set so polling stops. Pollers also re-check on each
+     * tick via {@link listActiveAccounts}, so this is best-effort acceleration.
+     *
+     * Fires `onScopeChanged` only when `newKinds` differs from the last
+     * announced set (by membership, order-independent). Idempotent calls
+     * (e.g. PATCH /mail/providers with the same enabledKinds) are silent.
+     */
+    onProviderSelectionChanged(newKinds: readonly MailProviderKind[]): void;
+    private withMutex;
+}
+export {};
+//# sourceMappingURL=account-registry.d.ts.map

package/dist/services/mail/account-registry.d.ts.map

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