← Public packages
@kody/agent-mail
AgentMail inboxes for agents: create/list inboxes, messages, threads, and Svix webhook ingress.
Files
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,
}
}