@withbuddi/buddi 0.1.0-pre.26 → 0.1.0-pre.28

package/packages/tools/email/dist/mailbox/actions.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Changing the owner's mailbox: mark, archive, move, trash — and undo.
+ *
+ * Until this file the plugin only ever read the server (`ports.ts`: every
+ * fetch is a peek). These are the writes, and every way into them is either a
+ * gated tool the owner approved, a page button the owner pressed, or a rule
+ * the owner set applying itself on arrival. Four things hold for all of them:
+ *
+ *  - **Nothing is deleted.** The most a write does to a message is move it.
+ *    Trash is the server's `\Trash` folder (RFC 6154), never EXPUNGE and
+ *    never `\Deleted`; a server without MOVE (RFC 6851) is refused rather
+ *    than emulated with COPY + delete, and no folder is created implicitly.
+ *  - **Every change is on the trail** (`email.mailbox_actions`, migration
+ *    017): which messages, where each was and where it went, its flags and
+ *    Gmail labels before, and who asked. That before is what `undo` restores.
+ *  - **buddi's own rows follow the message.** A moved message's row takes its
+ *    new folder, UIDVALIDITY and uid (COPYUID, RFC 4315), so the unread count,
+ *    the Mail page and triage see the mailbox as it now is — and the next poll
+ *    neither re-ingests a message moved back into the inbox (its quad already
+ *    exists) nor reverts a flag (the server agrees with the row).
+ *  - **One account per change.** The approval names the mailbox; a selection
+ *    that spans two is two calls.
+ *
+ * Gmail is told apart by its `X-GM-EXT-1` capability. There, archive is a
+ * MOVE from INBOX to All Mail (`\All`) — which takes the Inbox label off and
+ * leaves every other label — a label is a folder for `move`, and Trash drops
+ * labels, so a trash records them (`X-GM-LABELS`) and an undo puts them back.
+ * Anywhere else, archive is a MOVE to the folder the server marks `\Archive`,
+ * and a server with none is refused with a sentence.
+ */
+import type { DbArea } from '@buddi/core/plugin';
+import { ToolRefusal } from '@buddi/core/plugin';
+import type { EnvLike } from '../config.js';
+import { type AccountRecord, type ImapClientFactory, type ImapWriter, type MailboxInfo } from '../ports.js';
+type Db = Pick<DbArea, 'query'>;
+/** The most messages one call may change. One approval, one card, 500 rows. */
+export declare const MAX_PER_CALL = 500;
+/** How many messages an approval card names before "and N more". */
+export declare const SAMPLE_SIZE = 5;
+export declare const MAILBOX_ACTION_KINDS: readonly ["mark-read", "mark-unread", "archive", "move", "trash"];
+export type MailboxActionKind = (typeof MAILBOX_ACTION_KINDS)[number];
+/**
+ * Who made a change. `policy` is a rule applying itself on arrival — the
+ * owner's own or a learned one he kept; `policy_id` says which, and the policy
+ * row says where it came from.
+ */
+export type ActionOrigin = 'agent' | 'owner' | 'policy';
+export declare const SEEN = "\\Seen";
+/** One message as a change needs it: where it is, and enough to name it. */
+export interface Target {
+    id: string;
+    accountId: string;
+    folderId: string;
+    folder: string;
+    uidValidity: number;
+    uid: number;
+    messageId: string | null;
+    subject: string;
+    from: string;
+    flags: string[];
+}
+/** One message's entry on the trail: before and after. */
+export interface TrailItem {
+    id: string;
+    subject: string;
+    from: string;
+    messageId: string | null;
+    fromFolder: string;
+    fromUidValidity: number;
+    fromUid: number;
+    toFolder?: string;
+    toUidValidity?: number;
+    toUid?: number | null;
+    prevFlags?: string[];
+    prevLabels?: string[];
+}
+export interface ActionRecord {
+    id: string;
+    accountId: string;
+    kind: MailboxActionKind | 'undo';
+    destination: string | null;
+    criteria: string | null;
+    origin: ActionOrigin;
+    actor: string;
+    policyId: string | null;
+    runId: string | null;
+    actionId: string | null;
+    messageIds: string[];
+    items: TrailItem[];
+    changed: number;
+    note: string | null;
+    reverts: string | null;
+    undoneAt: string | null;
+    undoneBy: string | null;
+    createdAt: string | null;
+}
+export declare const ACTION_COLUMNS: string;
+export declare function toAction(row: Record<string, any>): ActionRecord;
+/** A refusal whose message is the sentence the owner and the agent read. */
+export declare class MailboxRefusal extends ToolRefusal {
+}
+/** The mailbox could not be opened at all: no password, or the provider refused it. Nothing was tried. */
+export declare class MailboxLoginRefusal extends MailboxRefusal {
+}
+export declare function plural(n: number, one: string, many?: string): string;
+/** "Mark as read", "Archive", … — the verb a card and a trail row lead with. */
+export declare function verbOf(kind: MailboxActionKind | 'undo', destination?: string | null): string;
+/** The sample lines a card shows: sender — subject. */
+export declare function sampleLines(targets: readonly Pick<Target, 'from' | 'subject'>[]): string[];
+/** The rows for these ids, with their folder names, in the order asked. */
+export declare function loadTargets(db: Db, ids: readonly string[]): Promise<Target[]>;
+/**
+ * The targets of one call, checked: every id known, at most `MAX_PER_CALL`,
+ * all in one mailbox the owner has. Refusals are sentences.
+ */
+export declare function requireTargets(db: Db, ids: readonly string[], accounts: readonly AccountRecord[]): Promise<{
+    account: AccountRecord;
+    targets: Target[];
+}>;
+export interface WriterOptions {
+    connect: ImapClientFactory;
+    env?: EnvLike;
+}
+/**
+ * Open a writing connection to one mailbox, run `work`, and close it.
+ *
+ * A login the provider refuses is written on the account row, as the poll
+ * writes it, so the settings row says "Password needed".
+ */
+export declare function withWriter<T>(ctx: {
+    buddi?: import('@buddi/core/plugin').BuddiHost | undefined;
+}, account: AccountRecord, opts: WriterOptions, work: (client: ImapWriter) => Promise<T>): Promise<T>;
+/** What a server is, for the decisions below. */
+export interface ServerFacts {
+    gmail: boolean;
+    move: boolean;
+    listing: MailboxInfo[];
+}
+export declare function serverFacts(client: ImapWriter): Promise<ServerFacts>;
+/** "INBOX, Archive, Receipts, …" — the list a refusal names. */
+export declare function folderList(listing: readonly MailboxInfo[]): string;
+/**
+ * Where a kind of change sends messages on this server, or a refusal.
+ *
+ * Nothing is created: a folder that does not exist is refused, naming the
+ * ones that do.
+ */
+export declare function destinationFor(facts: ServerFacts, kind: MailboxActionKind, account: string, folder?: string): string | null;
+export interface Provenance {
+    origin: ActionOrigin;
+    actor: string;
+    policyId?: string | null;
+    runId?: string | null;
+    actionId?: string | null;
+    criteria?: string | null;
+}
+export interface ActionOutcome {
+    /** The trail row, or null when nothing was there to change. */
+    action: ActionRecord | null;
+    changed: number;
+    skipped: number;
+    note: string;
+}
+/**
+ * Carry out one change on one account's server, keep the rows in step, and
+ * write it on the trail.
+ *
+ * Messages no longer where buddi last saw them are skipped, never guessed at,
+ * and the note says how many. Nothing is recorded when nothing changed.
+ */
+export declare function performAction(db: Db, client: ImapWriter, input: {
+    account: AccountRecord;
+    kind: MailboxActionKind;
+    targets: Target[];
+    folder?: string;
+    provenance: Provenance;
+    now: Date;
+    /** Already learned this connection, so a describe+execute pair does not list twice. */
+    facts?: ServerFacts;
+}): Promise<ActionOutcome>;
+export declare function findAction(db: Db, id: string): Promise<ActionRecord | null>;
+/** The newest change that can still be undone, in these accounts. */
+export declare function lastUndoable(db: Db, accountIds: readonly string[]): Promise<ActionRecord | null>;
+/** Why a change cannot be undone, or null when it can. */
+export declare function undoRefusal(action: ActionRecord): string | null;
+/** The sentence an undo's approval and the Recent changes row say. */
+export declare function describeUndo(action: ActionRecord, account: string): string;
+/**
+ * Put one change back, as far as the mailbox still allows, and record the
+ * undo as a change of its own.
+ *
+ * Each message is acted on where buddi's row says it is now — the row
+ * followed it — and only if the server still has it there: a message emptied
+ * from Trash, or moved again in another client, is skipped and counted.
+ */
+export declare function undoAction(db: Db, client: ImapWriter, input: {
+    account: AccountRecord;
+    action: ActionRecord;
+    provenance: Provenance;
+    now: Date;
+}): Promise<ActionOutcome>;
+/** The newest changes, for the Mail page's Recent changes. */
+export declare function recentActions(db: Db, accountIds: readonly string[], limit?: number): Promise<ActionRecord[]>;
+export {};
+//# sourceMappingURL=actions.d.ts.map

package/packages/tools/email/dist/mailbox/actions.d.ts.map

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