@freecorps/ember-email 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FreeCorps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# @freecorps/ember-email
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Email as an [Ember](https://github.com/freecorps/ember) component, on Cloudflare Email Service (sending) and Email
+Routing (receiving). It runs in your own Cloudflare account.
+
+```ts
+// ember/ember.config.ts
+import { defineApp, createFunctionHandle } from "@freecorps/ember-server";
+import { email } from "@freecorps/ember-email";
+
+export default defineApp().use(email, {
+  config: {
+    domains: ["acme.com"],                                 // inbound domains routed to this Worker
+    rateLimit: { rate: 100, period: 60_000 },              // per project
+    hooks: { onInbound: createFunctionHandle("support:onInbound") },
+  },
+});
+```
+
+```ts
+// ember/users.ts
+import { Email } from "@freecorps/ember-email";
+import { components, mutation } from "./_generated/server";
+const email = new Email(components.email);
+
+export const signup = mutation({
+  args: { address: v.string(), name: v.string() },
+  handler: (ctx, a) => {
+    const id = ctx.db.insert("users", a);
+    // Commits (or rolls back) with the insert; delivered by an action right after.
+    email.send(ctx, { from: "Acme <hello@acme.com>", to: a.address, template: { name: "welcome", data: { name: a.name } }, idempotencyKey: `welcome:${id}` });
+    return id;
+  },
+});
+```
+
+## What it does
+
+- **Send.** `lib:send` / `email.send(ctx, ...)` is a mutation: atomic with the caller, optionally `sendAt`. It also
+  handles idempotency keys per project, suppressions per project (hard bounces and complaints are added
+  automatically), and a per-project token-bucket rate limit (nested `rateLimit` component, same transaction).
+  Delivery goes through the `send_email` binding (the deploy adds it) or the REST API, with retries. Headers the
+  provider refuses are dropped, keeping threading and `X-` headers.
+- **Templates** are stored in the shard and use a small Mustache-like engine (`{{var}}`, `{{{raw}}}`, `#if`/`#each`)
+  with a responsive layout. React Email works too: render it in an action and pass `html`.
+- **Delivery events.** The component owns a Queue (`ember-<project>-<env>-email-events`). Point an Email Service
+  event subscription for your sending domain at it. Events are deduplicated by `eventId`, the status only moves
+  forward, and `lib:get` is reactive.
+- **Inbound.** The component hooks the Worker's `email()` handler:
+  - It routes mailbox addresses (`support@`, `privacy@`) and plus-addressed thread tokens. Unknown addresses are
+    rejected.
+  - It stores the raw `.eml` and the attachments in files (R2), and parses the message with `postal-mime`.
+  - It reads DKIM, DMARC and SPF from Cloudflare's `Authentication-Results`.
+  - It threads messages by token, then by `In-Reply-To` (DMARC pass, same contact), then by subject.
+  - It handles spam per sender per hour and auto-replies without loops.
+  - Your `onInbound` hook runs in the same transaction (tickets, push).
+- **Inbox queries** for dashboards and mobile apps: `threads`, `thread`, `unread` (aggregate), `search`
+  (`searchIndex`), `reply`, `note`, `markRead`, `markUnread`, `setStatus`, `assign`, `compose` (a new conversation
+  from the mailbox, answers join it by token) and `recent` (latest threads with their messages, for offline replicas).
+
+## Domains: `@freecorps/ember-email/cloudflare`
+
+Puts a domain on Cloudflare for the component and removes it again. It only needs `fetch`, so it runs in a Worker
+(with its own API token secret) or on an operator's machine (no token in the Worker). It has no storage, HTTP API
+or keys: you keep the returned state.
+
+```ts
+import { destroyDomain, emailResources, resolveAccountId, syncDomain } from "@freecorps/ember-email/cloudflare";
+
+const c = { apiToken, accountId: await resolveAccountId(apiToken, { env: process.env }) };
+const { worker, eventsQueue } = emailResources("acme", "prod"); // ember-acme-prod, ember-acme-prod-email-events
+let d = await syncDomain(c, { name: "mail.acme.com", enableRouting: true }, { prev: null, mailboxes: ["support@mail.acme.com"], worker, queue: eventsQueue });
+// d.status: "pending" until Email Service finishes onboarding (a minute or two): sync again with { prev: d }.
+// d.records: the DNS records involved; d.notes: what is missing or needs the zone owner.
+await destroyDomain(c, d); // rules, event subscription, and the sending domain if this created it
+```
+
+What it does:
+
+- **Sending:** it onboards the domain in Email Service. Cloudflare manages its records (bounce MX/SPF, DKIM, DMARC).
+- **Receiving:** it checks Email Routing. For the zone apex, routing must already be on, because turning it on
+  rewrites the zone's MX. For a subdomain, `enableRouting: true` creates the routing subdomain. No API removes a
+  routing subdomain, so removal is a dashboard step.
+- **Mailboxes:** it adds one literal rule per mailbox address on the domain → your Worker. It never changes a rule
+  that routes somewhere else.
+- **Events:** it adds an `email.sending` event subscription → the component's queue.
+
+## Offline replicas: `@freecorps/ember-email/schema`
+
+`emailSchema`: the component's tables only (no postal-mime), for clients composing a local replica schema.
+
+## Example
+
+[`examples/email-lite`](https://github.com/freecorps/ember/tree/main/examples/email-lite) is the smallest app on the
+component (mailboxes, send, inbound). [freecorps/mail](https://github.com/freecorps/mail) is a full email service
+built on it (Resend-style HTTP API, inbox, mobile app).
+
+All the component's state lives in one shard (`config.shard`, default `global:main`).
+
+See `docs/PLAN.md` §16 and `docs/design/contracts.md` ("Email") in the repository.
+
+License: MIT.

package/dist/address.d.ts

@@ -0,0 +1,36 @@
+export type EmailAddress = {
+    email: string;
+    name?: string;
+};
+/** Is `s` a bare `local@domain.tld` address (no display name)? Deliberately strict: rejects header injection. */
+export declare function isEmail(s: unknown): s is string;
+/**
+ * `"Name" <a@b.c>`, `Name <a@b.c>`, `a@b.c` or `{ email, name }` → `{ email, name? }`. Parsed by position (a long
+ * hostile display name must not make a regex backtrack). Throws on anything else.
+ */
+export declare function parseAddress(input: string | EmailAddress): EmailAddress;
+/** `{ email, name }` → `"Name" <email>` (or the bare address). */
+export declare function formatAddress(a: EmailAddress): string;
+/** A list of `string | {email,name}` (or one) → parsed addresses, duplicates removed. */
+export declare function parseAddressList(x: string | EmailAddress | ReadonlyArray<string | EmailAddress> | undefined): EmailAddress[];
+export declare const domainOf: (email: string) => string;
+/**
+ * Splits plus-addressing: `support+t_abc123@x.com` → `{ base: "support@x.com", tag: "t_abc123" }`. Email Routing
+ * hands the Worker the envelope `to` with the `+detail` kept (the zone needs subaddressing on to route it).
+ */
+export declare function splitPlus(email: string): {
+    base: string;
+    tag: string | null;
+};
+/** `support@x.com` + tag → `support+tag@x.com`. */
+export declare function withPlus(email: string, tag: string): string;
+/** "Re: Fwd: [#12] Hello" → "hello": the key used to match a reply to its thread by subject. */
+export declare function subjectKey(subject: string | undefined): string;
+/** "Hello" → "Re: Hello" (once). */
+export declare function replySubject(subject: string): string;
+/** A `Message-ID` value without the angle brackets, lowercased (header lookups). */
+export declare function normalizeMessageId(id: string | undefined | null): string | null;
+/** All Message-IDs in a `References` / `In-Reply-To` header value. */
+export declare function messageIdList(h: string | undefined | null): string[];
+/** Addresses that must never get an automatic reply. */
+export declare function isNoReplySender(email: string): boolean;

package/dist/address.js

@@ -0,0 +1,121 @@
+// Addresses, plus-addressing and subjects. Pure functions (no Cloudflare APIs): used in mutations, actions and the
+// mail app's HTTP API.
+const BARE = /^[^\s<>@",;:()[\]\\]+@[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+$/;
+/** Is `s` a bare `local@domain.tld` address (no display name)? Deliberately strict: rejects header injection. */
+export function isEmail(s) {
+    return typeof s === "string" && s.length <= 254 && BARE.test(s);
+}
+/**
+ * `"Name" <a@b.c>`, `Name <a@b.c>`, `a@b.c` or `{ email, name }` → `{ email, name? }`. Parsed by position (a long
+ * hostile display name must not make a regex backtrack). Throws on anything else.
+ */
+export function parseAddress(input) {
+    if (typeof input === "object" && input !== null) {
+        if (!isEmail(input.email))
+            throw new Error(`Invalid email address ${JSON.stringify(input.email)}`);
+        const name = cleanName(input.name);
+        return name ? { email: input.email.toLowerCase(), name } : { email: input.email.toLowerCase() };
+    }
+    if (typeof input !== "string")
+        throw new Error("Invalid email address");
+    const s = input.trim();
+    const open = s.lastIndexOf("<");
+    if (open >= 0 && s.endsWith(">")) {
+        const email = s.slice(open + 1, -1).trim();
+        if (!isEmail(email))
+            throw new Error(`Invalid email address ${JSON.stringify(input)}`);
+        const name = cleanName(s.slice(0, open));
+        return name ? { email: email.toLowerCase(), name } : { email: email.toLowerCase() };
+    }
+    if (!isEmail(s))
+        throw new Error(`Invalid email address ${JSON.stringify(input)}`);
+    return { email: s.toLowerCase() };
+}
+function cleanName(n) {
+    if (n === undefined)
+        return undefined;
+    let x = n.trim();
+    if (x.startsWith('"') && x.endsWith('"') && x.length >= 2)
+        x = x.slice(1, -1);
+    x = x.replace(/[\r\n<>"]/g, "").trim();
+    return x ? x.slice(0, 200) : undefined;
+}
+/** `{ email, name }` → `"Name" <email>` (or the bare address). */
+export function formatAddress(a) {
+    return a.name ? `"${a.name.replace(/["\\]/g, "")}" <${a.email}>` : a.email;
+}
+/** A list of `string | {email,name}` (or one) → parsed addresses, duplicates removed. */
+export function parseAddressList(x) {
+    if (x === undefined)
+        return [];
+    const arr = Array.isArray(x) ? x : [x];
+    const seen = new Set();
+    const out = [];
+    for (const a of arr) {
+        const p = parseAddress(a);
+        if (seen.has(p.email))
+            continue;
+        seen.add(p.email);
+        out.push(p);
+    }
+    return out;
+}
+export const domainOf = (email) => email.slice(email.lastIndexOf("@") + 1).toLowerCase();
+/**
+ * Splits plus-addressing: `support+t_abc123@x.com` → `{ base: "support@x.com", tag: "t_abc123" }`. Email Routing
+ * hands the Worker the envelope `to` with the `+detail` kept (the zone needs subaddressing on to route it).
+ */
+export function splitPlus(email) {
+    const at = email.lastIndexOf("@");
+    const local = email.slice(0, at);
+    const plus = local.indexOf("+");
+    if (plus < 0)
+        return { base: email.toLowerCase(), tag: null };
+    return { base: `${local.slice(0, plus)}${email.slice(at)}`.toLowerCase(), tag: local.slice(plus + 1) || null };
+}
+/** `support@x.com` + tag → `support+tag@x.com`. */
+export function withPlus(email, tag) {
+    const at = email.lastIndexOf("@");
+    return `${email.slice(0, at)}+${tag}${email.slice(at)}`;
+}
+/** "Re: Fwd: [#12] Hello" → "hello": the key used to match a reply to its thread by subject. */
+export function subjectKey(subject) {
+    let s = (subject ?? "").trim();
+    for (;;) {
+        const next = s.replace(/^\s*((re|fw|fwd|aw|wg|sv|vs|res|enc|tr)\s*(\[\d+\])?\s*:\s*|\[#\d+\]\s*)/i, "");
+        if (next === s)
+            break;
+        s = next;
+    }
+    return s.replace(/\s+/g, " ").trim().toLowerCase().slice(0, 300);
+}
+/** "Hello" → "Re: Hello" (once). */
+export function replySubject(subject) {
+    return /^\s*re\s*:/i.test(subject) ? subject : `Re: ${subject}`;
+}
+/** A `Message-ID` value without the angle brackets, lowercased (header lookups). */
+export function normalizeMessageId(id) {
+    if (!id)
+        return null;
+    const m = /<([^<>]+)>/.exec(id);
+    const v = (m ? m[1] : id).trim();
+    return v ? v.toLowerCase() : null;
+}
+/** All Message-IDs in a `References` / `In-Reply-To` header value. */
+export function messageIdList(h) {
+    if (!h)
+        return [];
+    const out = [];
+    for (const m of h.matchAll(/<([^<>]+)>/g))
+        out.push(m[1].trim().toLowerCase());
+    if (!out.length)
+        for (const t of h.split(/\s+/))
+            if (t.includes("@"))
+                out.push(t.toLowerCase());
+    return out;
+}
+/** Addresses that must never get an automatic reply. */
+export function isNoReplySender(email) {
+    const local = email.slice(0, email.lastIndexOf("@")).toLowerCase();
+    return /^(no-?reply|do-?not-?reply|mailer-daemon|postmaster|bounces?|notifications?)([+.-]|$)/.test(local);
+}

package/dist/client.d.ts

@@ -0,0 +1,273 @@
+import type { FunctionReference } from "@freecorps/ember-server";
+import type { SendInput, SendResult } from "./component.ts";
+import type { EmailStatus } from "./events.ts";
+type Ref<T extends "query" | "mutation" | "action", A, R> = FunctionReference<T, "public", A, R>;
+type Page<T> = {
+    page: T[];
+    isDone: boolean;
+    continueCursor: string;
+};
+type PageOpts = {
+    numItems: number;
+    cursor: string | null;
+};
+export type EmailRecord = SendInput & {
+    _id: string;
+    _creationTime: number;
+    project: string;
+    status: EmailStatus;
+    sendAt: number;
+    attempts: number;
+    messageId?: string;
+    sentAt?: number;
+    lastEventAt?: number;
+    error?: {
+        code: string;
+        message: string;
+    };
+    suppressed?: string[];
+};
+export type ThreadRecord = {
+    _id: string;
+    mailbox: string;
+    number: number;
+    subject: string;
+    contact: string;
+    contactName?: string;
+    status: "open" | "waiting" | "closed" | "spam";
+    messageCount: number;
+    unreadCount: number;
+    lastMessageAt: number;
+    snippet: string;
+    assignee?: string;
+    assigneeName?: string;
+};
+/** What `components.<name>` of the email component looks like (public functions). */
+export interface EmailComponentApi {
+    lib: {
+        send: Ref<"mutation", SendInput, SendResult>;
+        sendBatch: Ref<"mutation", {
+            emails: SendInput[];
+        }, SendResult[]>;
+        cancel: Ref<"mutation", {
+            id: string;
+        }, {
+            ok: boolean;
+            status: string;
+        }>;
+        retry: Ref<"mutation", {
+            id: string;
+        }, {
+            ok: boolean;
+            status: string;
+        }>;
+        get: Ref<"query", {
+            id: string;
+        }, EmailRecord | null>;
+        list: Ref<"query", {
+            project?: string;
+            paginationOpts?: PageOpts;
+        }, Page<EmailRecord>>;
+        events: Ref<"query", {
+            id: string;
+        }, Array<Record<string, unknown>>>;
+        eventsByMessage: Ref<"query", {
+            messageId: string;
+        }, Array<Record<string, unknown>>>;
+        stats: Ref<"query", {
+            project?: string;
+        }, Record<string, number>>;
+        suppress: Ref<"mutation", {
+            project?: string;
+            email: string;
+            reason?: string;
+        }, string>;
+        unsuppress: Ref<"mutation", {
+            project?: string;
+            email: string;
+        }, boolean>;
+        suppressions: Ref<"query", {
+            project?: string;
+            paginationOpts?: PageOpts;
+        }, Page<{
+            email: string;
+            reason: string;
+            at: number;
+        }>>;
+        upsertTemplate: Ref<"mutation", {
+            project?: string;
+            name: string;
+            subject: string;
+            html: string;
+            text?: string;
+            layout?: unknown;
+        }, string>;
+        removeTemplate: Ref<"mutation", {
+            project?: string;
+            name: string;
+        }, boolean>;
+        templates: Ref<"query", {
+            project?: string;
+        }, Array<{
+            name: string;
+            subject: string;
+            html: string;
+            text?: string;
+            updatedAt: number;
+        }>>;
+        render: Ref<"query", {
+            project?: string;
+            name: string;
+            data?: unknown;
+        }, {
+            subject: string;
+            html: string;
+            text: string;
+        } | null>;
+        upsertMailbox: Ref<"mutation", {
+            name: string;
+            address: string;
+            displayName?: string;
+            autoReply?: {
+                subject: string;
+                text: string;
+                html?: string;
+            } | null;
+        }, string>;
+        removeMailbox: Ref<"mutation", {
+            name: string;
+        }, boolean>;
+        mailboxes: Ref<"query", {}, Array<{
+            _id: string;
+            name: string;
+            address: string;
+            displayName?: string;
+            autoReply?: unknown;
+        }>>;
+        route: Ref<"query", {
+            to: string;
+        }, {
+            mailbox: string;
+            tag: string | null;
+        } | null>;
+        threads: Ref<"query", {
+            mailbox: string;
+            status?: string;
+            paginationOpts?: PageOpts;
+        }, Page<ThreadRecord>>;
+        thread: Ref<"query", {
+            threadId: string;
+        }, {
+            thread: ThreadRecord;
+            messages: Array<Record<string, any>>;
+        } | null>;
+        unread: Ref<"query", {
+            mailboxes?: string[];
+        }, Record<string, {
+            unread: number;
+            threads: number;
+        }>>;
+        search: Ref<"query", {
+            query: string;
+            mailbox?: string;
+            limit?: number;
+        }, Array<{
+            messageId: string;
+            threadId: string;
+            mailbox: string;
+            direction: string;
+            subject: string;
+            from: {
+                email: string;
+                name?: string;
+            };
+            snippet: string;
+            at: number;
+        }>>;
+        markRead: Ref<"mutation", {
+            threadId: string;
+        }, boolean>;
+        setStatus: Ref<"mutation", {
+            threadId: string;
+            status: "open" | "waiting" | "closed" | "spam";
+        }, string>;
+        reply: Ref<"mutation", {
+            threadId: string;
+            text: string;
+            html?: string;
+            author?: string;
+            cc?: string[];
+            sendAt?: number;
+        }, {
+            emailId: string;
+            messageId: string;
+            status: string;
+        }>;
+        note: Ref<"mutation", {
+            threadId: string;
+            text: string;
+            author?: string;
+        }, string>;
+        markUnread: Ref<"mutation", {
+            threadId: string;
+        }, boolean>;
+        assign: Ref<"mutation", {
+            threadId: string;
+            assignee: string | null;
+            assigneeName?: string;
+        }, string | null>;
+        compose: Ref<"mutation", {
+            mailbox: string;
+            to: string[];
+            cc?: string[];
+            subject: string;
+            text: string;
+            html?: string;
+            author?: string;
+        }, {
+            threadId: string;
+            emailId: string;
+            messageId: string;
+            status: string;
+            number: number;
+        }>;
+        recent: Ref<"query", {
+            mailboxes: string[];
+            threads?: number;
+        }, {
+            threads: ThreadRecord[];
+            messages: Array<Record<string, any>>;
+        }>;
+    };
+}
+type SyncCtx = {
+    runQuery(fn: any, args?: any): any;
+    runMutation?(fn: any, args?: any): any;
+};
+type AsyncCtx = {
+    runQuery(fn: any, args?: any): Promise<any>;
+    runMutation(fn: any, args?: any): Promise<any>;
+};
+export declare class Email {
+    readonly component: EmailComponentApi;
+    constructor(component: EmailComponentApi);
+    private mut;
+    /** Queues an email; in a mutation it commits (or rolls back) with it. */
+    send(ctx: SyncCtx, input: SendInput): SendResult;
+    send(ctx: AsyncCtx, input: SendInput): Promise<SendResult>;
+    sendBatch(ctx: SyncCtx, emails: SendInput[]): SendResult[];
+    sendBatch(ctx: AsyncCtx, emails: SendInput[]): Promise<SendResult[]>;
+    cancel(ctx: SyncCtx, id: string): {
+        ok: boolean;
+        status: string;
+    };
+    cancel(ctx: AsyncCtx, id: string): Promise<{
+        ok: boolean;
+        status: string;
+    }>;
+    get(ctx: SyncCtx, id: string): EmailRecord | null;
+    get(ctx: AsyncCtx, id: string): Promise<EmailRecord | null>;
+    /** Delivery status of an email (reactive in a query). */
+    status(ctx: SyncCtx, id: string): EmailStatus | null;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,36 @@
+// Typed helper over an installed email component (like `PushNotifications`): synchronous inside queries and
+// mutations (same transaction), Promises in actions.
+//
+//   const email = new Email(components.email);
+//   export const signup = mutation({ args: {...}, handler: (ctx, a) => {
+//     const userId = ctx.db.insert("users", a);
+//     email.send(ctx, { from: "Acme <hello@acme.com>", to: a.email, template: { name: "welcome", data: { name: a.name } } });
+//     return userId;
+//   }});
+export class Email {
+    component;
+    constructor(component) {
+        this.component = component;
+    }
+    mut(ctx, what) {
+        if (!ctx.runMutation)
+            throw new Error(`email.${what} needs a mutation or action ctx`);
+        return ctx.runMutation.bind(ctx);
+    }
+    send(ctx, input) {
+        return this.mut(ctx, "send")(this.component.lib.send, input);
+    }
+    sendBatch(ctx, emails) {
+        return this.mut(ctx, "sendBatch")(this.component.lib.sendBatch, { emails });
+    }
+    cancel(ctx, id) {
+        return this.mut(ctx, "cancel")(this.component.lib.cancel, { id });
+    }
+    get(ctx, id) {
+        return ctx.runQuery(this.component.lib.get, { id });
+    }
+    /** Delivery status of an email (reactive in a query). */
+    status(ctx, id) {
+        return ctx.runQuery(this.component.lib.get, { id })?.status ?? null;
+    }
+}

package/dist/cloudflare/api.d.ts

@@ -0,0 +1,64 @@
+export interface CfCreds {
+    accountId: string;
+    apiToken: string;
+    fetch?: typeof fetch;
+}
+export declare class CfError extends Error {
+    readonly status: number;
+    readonly codes: number[];
+    name: string;
+    constructor(message: string, status: number, codes: number[]);
+}
+export type DnsRecord = {
+    type: string;
+    name: string;
+    value: string;
+    priority?: number;
+    ttl?: number;
+    purpose: "sending" | "receiving";
+};
+/** The zone of `domain` in this account (walks up the labels: `a.b.example.com` → `example.com`). */
+export declare function findZone(c: CfCreds, domain: string): Promise<{
+    id: string;
+    name: string;
+} | null>;
+type SendingSubdomain = {
+    tag: string;
+    id?: string;
+    name: string;
+    enabled: boolean;
+};
+export declare function sendingDomain(c: CfCreds, zoneId: string, name: string): Promise<SendingSubdomain | null>;
+/** Onboards `name` for sending (idempotent) and returns its DNS records. */
+export declare function ensureSending(c: CfCreds, zoneId: string, name: string): Promise<{
+    sending: SendingSubdomain;
+    records: DnsRecord[];
+    created: boolean;
+}>;
+export declare function deleteSending(c: CfCreds, zoneId: string, tag: string): Promise<void>;
+export type RoutingState = {
+    enabled: boolean;
+    status: string;
+    records: DnsRecord[];
+    note?: string;
+};
+/** Whether Email Routing receives mail for `name` (apex or routing subdomain), and the records it needs. */
+export declare function routingState(c: CfCreds, zone: {
+    id: string;
+    name: string;
+}, name: string): Promise<RoutingState>;
+/** Adds `name` as a routing subdomain (records on the subdomain only). There is no API to remove it again. */
+export declare function enableRoutingSubdomain(c: CfCreds, zoneId: string, name: string): Promise<void>;
+/** A literal rule `address` → `worker` (reused when one already points there; never changes a rule routed elsewhere). */
+export declare function ensureWorkerRule(c: CfCreds, zoneId: string, address: string, worker: string): Promise<{
+    id: string;
+    created: boolean;
+}>;
+export declare function deleteRule(c: CfCreds, zoneId: string, id: string): Promise<void>;
+/** Queues event subscription: Email Service delivery events of `domain` → `queue` (by name). */
+export declare function ensureEventSubscription(c: CfCreds, zoneId: string, domain: string, queue: string): Promise<{
+    id: string;
+    created: boolean;
+}>;
+export declare function deleteEventSubscription(c: CfCreds, id: string): Promise<void>;
+export {};