Skip to content
← Public packages

@kody/agent-mail

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

FollowFork

Files

lists.ts

109 lines · 3.8 KB · TypeScript
import { clean, encodePathSegment } from './core.ts'

export type ListDirection = 'receive' | 'send' | 'reply'
export type ListType = 'allow' | 'block'

export type ListScopeInput = {
	/** Scope rules to one inbox (most specific; overrides pod and org rules on a match). */
	inboxId?: string
	/** Scope rules to one pod (overrides org rules on a match). */
	podId?: string
}

export type ListSelectorInput = ListScopeInput & {
	/** `receive` (default): new inbound mail. `reply`: inbound replies to your outbound mail. `send`: outbound recipients. */
	direction?: ListDirection
	/** `allow` or `block`. Required. */
	type: ListType
}

const directions: ReadonlyArray<ListDirection> = ['receive', 'send', 'reply']
const types: ReadonlyArray<ListType> = ['allow', 'block']

export function normalizeDirection(value: unknown): ListDirection {
	const direction = clean(value || 'receive').toLowerCase()
	if (!directions.includes(direction as ListDirection)) {
		throw new Error('direction must be one of: ' + directions.join(', '))
	}
	return direction as ListDirection
}

export function normalizeListType(value: unknown): ListType {
	const type = clean(value).toLowerCase()
	if (!types.includes(type as ListType)) {
		throw new Error('type must be one of: ' + types.join(', '))
	}
	return type as ListType
}

const domainPattern = /^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z][a-z0-9-]{0,62}$/
const localPartPattern = /^[^\s@]{1,64}$/

/**
 * Normalize a list entry: a full email address (`partner@example.com`) or a
 * bare domain (`example.com`). Accepts `@example.com` as a domain too.
 */
export function normalizeEntry(value: unknown) {
	let entry = clean(value).toLowerCase()
	if (!entry) throw new Error('entry is required (email address or domain)')
	if (entry.startsWith('@')) entry = entry.slice(1)
	const at = entry.lastIndexOf('@')
	if (at === -1) {
		if (!domainPattern.test(entry)) {
			throw new Error('entry must be an email address or a domain like example.com')
		}
		return { entry, entryType: 'domain' as const }
	}
	const local = entry.slice(0, at)
	const domain = entry.slice(at + 1)
	if (!localPartPattern.test(local) || !domainPattern.test(domain)) {
		throw new Error('entry must be an email address or a domain like example.com')
	}
	return { entry, entryType: 'email' as const }
}

export function resolveScope(input: ListScopeInput) {
	const inboxId = clean(input.inboxId)
	const podId = clean(input.podId)
	if (inboxId && podId) throw new Error('Pass inboxId or podId, not both')
	if (inboxId) {
		return {
			scope: 'inbox' as const,
			scopeId: inboxId,
			prefix: '/v0/inboxes/' + encodePathSegment(inboxId, 'inboxId'),
		}
	}
	if (podId) {
		return {
			scope: 'pod' as const,
			scopeId: podId,
			prefix: '/v0/pods/' + encodePathSegment(podId, 'podId'),
		}
	}
	return { scope: 'organization' as const, scopeId: null, prefix: '/v0' }
}

/** Build the AgentMail Lists REST path for a scope + direction + type (+ entry). */
export function listPath(input: ListSelectorInput, entry?: string) {
	const direction = normalizeDirection(input.direction)
	const type = normalizeListType(input.type)
	const scope = resolveScope(input)
	let path = scope.prefix + '/lists/' + direction + '/' + type
	if (entry !== undefined) path += '/' + encodePathSegment(entry, 'entry')
	return { path, direction, type, scope: scope.scope, scopeId: scope.scopeId }
}

export function slimEntry(raw: unknown) {
	const value = (raw && typeof raw === 'object' ? raw : {}) as Record<string, unknown>
	return {
		entry: clean(value.entry) || null,
		entryType: clean(value.entry_type) || null,
		direction: clean(value.direction) || null,
		type: clean(value.list_type) || null,
		inboxId: clean(value.inbox_id) || null,
		podId: clean(value.pod_id) || null,
		reason: clean(value.reason) || null,
		readOnly: value.read_only === true,
		createdAt: clean(value.created_at) || null,
	}
}