Skip to content
← Public packages

@kody/agent-mail

AgentMail inboxes for agents: create/list inboxes, messages, threads, and Svix webhook ingress.

FollowFork

Files

add-rule.ts

82 lines · 2.8 KB · TypeScript
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<string, unknown> = { 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) }
}