import { agentMailRequest, clean, requireConfirmOrDryRun } from './core.ts' import { listPath, normalizeEntry, slimEntry, type ListSelectorInput } from './lists.ts' export type AddRuleInput = ListSelectorInput & { /** Email address (`partner@example.com`) or domain (`example.com`). */ entry?: string /** Alias for `entry`. */ match?: string /** Optional reason; AgentMail only stores it on block lists. */ reason?: string /** Preview the request without calling AgentMail. */ dryRun?: boolean /** Required true for a live create (unless dryRun). */ confirm?: boolean } /** * Add an email address or domain to an AgentMail allow or block list. * Requires confirm: true for a live POST, or dryRun: true to preview. * Uses POST /v0/lists/{direction}/{type} (or /v0/pods/{podId}/... or * /v0/inboxes/{inboxId}/...). AgentMail enforces lists natively: * - receive allow: once non-empty, only matching senders are accepted * (allowlist-only mode for that scope) * - receive block: matching senders are rejected * - reply lists apply instead of receive lists to replies to your mail * - inbox scope beats pod beats organization when a scope has a match * * @param input.type - `allow` or `block` (required) * @param input.entry - Email address or domain (or `match`) * @param input.direction - `receive` (default), `reply`, or `send` * @param input.inboxId - Optional inbox scope * @param input.podId - Optional pod scope * @param input.reason - Optional reason (block lists) * @param input.dryRun - Preview without creating * @param input.confirm - Must be true for a live create * @returns Created entry or dry-run preview * * @example * import addRule from 'kody:@kody/agent-mail/add-rule' * const preview = await addRule({ * type: 'allow', * entry: 'my-other-harness@agentmail.to', * inboxId: 'prime@agentmail.to', * dryRun: true, * }) */ export default async function addRule(input: AddRuleInput) { const mode = requireConfirmOrDryRun(input, 'add a live AgentMail list entry') const { entry, entryType } = normalizeEntry(input.entry ?? input.match) const target = listPath(input) const body: Record = { entry } const reason = clean(input.reason) if (reason && target.type === 'block') body.reason = reason const base = { scope: target.scope, scopeId: target.scopeId, direction: target.direction, type: target.type, entryType, } if (mode === 'dryRun') { return { dryRun: true as const, ...base, method: 'POST', path: target.path, body, ...(reason && target.type !== 'block' ? { note: 'reason is ignored on allow lists' } : {}), } } const raw = await agentMailRequest({ method: 'POST', path: target.path, body, label: 'AgentMail create list entry', }) return { dryRun: false as const, ...base, entry: slimEntry(raw) } }