@freecorps/ember-email 0.5.6 → 0.5.7

package/README.md

@@ -97,6 +97,10 @@ What it does:
   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.
+- **Catch-all:** with `catchAll: true` (a mailbox of the domain is its catch-all, `upsertMailbox({ catchAll: true })`),
+  the zone's catch-all rule → your Worker, so every address no mailbox has reaches that mailbox, with the address it
+  was sent to in its To. Only for the zone apex, since the rule belongs to the zone. It never takes over a catch-all
+  that routes somewhere else. `destroyDomain`, or a sync without `catchAll`, turns it back off.
 - **Events:** it adds an `email.sending` event subscription → the component's queue.
 
 ## Offline replicas: `@freecorps/ember-email/schema`

package/dist/client.d.ts

@@ -133,6 +133,7 @@ export interface EmailComponentApi {
                 text: string;
                 html?: string;
             } | null;
+            catchAll?: boolean | null;
         }, string>;
         removeMailbox: Ref<"mutation", {
             name: string;
@@ -143,6 +144,7 @@ export interface EmailComponentApi {
             address: string;
             displayName?: string;
             autoReply?: unknown;
+            catchAll?: boolean;
         }>>;
         route: Ref<"query", {
             to: string;

package/dist/cloudflare/api.d.ts

@@ -54,6 +54,15 @@ export declare function ensureWorkerRule(c: CfCreds, zoneId: string, address: st
     id: string;
     created: boolean;
 }>;
+/**
+ * The zone's catch-all rule → this Worker (every address no literal rule takes). Left alone, with an error, when it
+ * is on and sends mail somewhere else; a disabled or "drop" catch-all is taken over.
+ */
+export declare function ensureCatchAllRule(c: CfCreds, zoneId: string, worker: string): Promise<{
+    created: boolean;
+}>;
+/** Turns the zone's catch-all back off (drop), only when it points at this Worker. */
+export declare function releaseCatchAllRule(c: CfCreds, zoneId: string, worker: string): Promise<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<{

package/dist/cloudflare/api.js

@@ -118,6 +118,28 @@ export async function ensureWorkerRule(c, zoneId, address, worker) {
     });
     return { id: r.id, created: true };
 }
+const pointsAt = (r, worker) => r.actions.some((x) => x.type === "worker" && x.value?.includes(worker));
+/**
+ * The zone's catch-all rule → this Worker (every address no literal rule takes). Left alone, with an error, when it
+ * is on and sends mail somewhere else; a disabled or "drop" catch-all is taken over.
+ */
+export async function ensureCatchAllRule(c, zoneId, worker) {
+    const r = await call(c, "GET", `/zones/${zoneId}/email/routing/rules/catch_all`);
+    if (r.enabled && pointsAt(r, worker))
+        return { created: false };
+    if (r.enabled && !r.actions.every((x) => x.type === "drop"))
+        throw new CfError(`the zone's catch-all already routes mail elsewhere (${r.actions.map((x) => x.type).join(", ")}); not changing it`, 409, []);
+    await call(c, "PUT", `/zones/${zoneId}/email/routing/rules/catch_all`, { enabled: true, matchers: [{ type: "all" }], actions: [{ type: "worker", value: [worker] }] });
+    return { created: true };
+}
+/** Turns the zone's catch-all back off (drop), only when it points at this Worker. */
+export async function releaseCatchAllRule(c, zoneId, worker) {
+    const r = await call(c, "GET", `/zones/${zoneId}/email/routing/rules/catch_all`);
+    if (!pointsAt(r, worker))
+        return false;
+    await call(c, "PUT", `/zones/${zoneId}/email/routing/rules/catch_all`, { enabled: false, matchers: [{ type: "all" }], actions: [{ type: "drop" }] });
+    return true;
+}
 export async function deleteRule(c, zoneId, id) {
     await call(c, "DELETE", `/zones/${zoneId}/email/routing/rules/${id}`);
 }

package/dist/cloudflare/index.d.ts

@@ -1,4 +1,4 @@
-export { CfError, deleteEventSubscription, deleteRule, deleteSending, enableRoutingSubdomain, ensureEventSubscription, ensureSending, ensureWorkerRule, findZone, routingState, sendingDomain, type CfCreds, type DnsRecord, type RoutingState, } from "./api.ts";
+export { CfError, deleteEventSubscription, deleteRule, deleteSending, enableRoutingSubdomain, ensureEventSubscription, ensureSending, ensureWorkerRule, ensureCatchAllRule, releaseCatchAllRule, findZone, routingState, sendingDomain, type CfCreds, type DnsRecord, type RoutingState, } from "./api.ts";
 export { destroyDomain, isDomainName, syncDomain, type DomainState, type SyncDomainDeps, type SyncDomainOptions } from "./onboard.ts";
 /**
  * Names `ember deploy` gives an app's Worker and the email component's delivery-events queue (`install` is the name

package/dist/cloudflare/index.js

@@ -7,7 +7,7 @@
 //   const { worker, eventsQueue } = emailResources("acme", "prod");
 //   let d = await syncDomain(c, { name: "mail.acme.com" }, { prev: null, mailboxes: ["support@mail.acme.com"], worker, queue: eventsQueue });
 //   // keep `d` (it holds the ids of what was created); later: await destroyDomain(c, d)
-export { CfError, deleteEventSubscription, deleteRule, deleteSending, enableRoutingSubdomain, ensureEventSubscription, ensureSending, ensureWorkerRule, findZone, routingState, sendingDomain, } from "./api.js";
+export { CfError, deleteEventSubscription, deleteRule, deleteSending, enableRoutingSubdomain, ensureEventSubscription, ensureSending, ensureWorkerRule, ensureCatchAllRule, releaseCatchAllRule, findZone, routingState, sendingDomain, } from "./api.js";
 export { destroyDomain, isDomainName, syncDomain } from "./onboard.js";
 /**
  * Names `ember deploy` gives an app's Worker and the email component's delivery-events queue (`install` is the name

package/dist/cloudflare/onboard.d.ts

@@ -12,6 +12,8 @@ export type DomainState = {
     ruleIds: string[];
     subscriptionId?: string;
     createdSending?: boolean;
+    /** The zone's catch-all rule points at this Worker (set by `catchAll`; `destroyDomain` turns it off). */
+    catchAll?: string;
     notes: string[];
 };
 /** A syntactically valid (lowercase) domain name. */
@@ -35,6 +37,11 @@ export type SyncDomainDeps = {
     worker: string;
     /** The component's delivery-events queue (see `emailResources`). */
     queue: string;
+    /**
+     * A mailbox of this domain is its catch-all: the zone's catch-all rule → `worker`. Only for a zone apex (the rule
+     * is the zone's); refused when the catch-all already routes mail elsewhere.
+     */
+    catchAll?: boolean;
 };
 /**
  * Onboards (or re-checks) a domain. Idempotent: run it again until `status` is `verified` (a new sending domain

package/dist/cloudflare/onboard.js

@@ -2,7 +2,7 @@
 // subdomain only when asked), one Worker rule per mailbox address, and the delivery-event subscription to the
 // component's queue. The caller keeps the returned `DomainState` (it holds the ids of what was created) and passes it
 // back on the next sync and to `destroyDomain`. Product-agnostic: no storage, no HTTP API, no API keys.
-import { CfError, deleteEventSubscription, deleteRule, deleteSending, enableRoutingSubdomain, ensureEventSubscription, ensureSending, ensureWorkerRule, findZone, routingState } from "./api.js";
+import { CfError, deleteEventSubscription, deleteRule, deleteSending, enableRoutingSubdomain, ensureCatchAllRule, ensureEventSubscription, ensureSending, ensureWorkerRule, findZone, releaseCatchAllRule, routingState } from "./api.js";
 const NAME = /^(?=.{3,253}$)([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/;
 /** A syntactically valid (lowercase) domain name. */
 export const isDomainName = (name) => NAME.test(name);
@@ -39,6 +39,7 @@ export async function syncDomain(c, a, deps) {
     let routingStatus;
     const ruleIds = [...(prev?.ruleIds ?? [])];
     let subscriptionId = prev?.subscriptionId;
+    let catchAll = prev?.catchAll;
     let recvOk = !wantRecv;
     if (wantRecv) {
         let r = await routingState(c, zone, name);
@@ -64,6 +65,27 @@ export async function syncDomain(c, a, deps) {
                     notes.push(e.message);
                 }
             }
+            if (deps.catchAll && name !== zone.name)
+                notes.push(`a catch-all is the zone's rule: only ${zone.name} can have one, not ${name}`);
+            else if (deps.catchAll) {
+                try {
+                    await ensureCatchAllRule(c, zone.id, deps.worker);
+                    catchAll = deps.worker;
+                }
+                catch (e) {
+                    notes.push(`catch-all: ${e.message}`);
+                }
+            }
+            else if (catchAll && name === zone.name) {
+                // No catch-all mailbox any more: the rule this sync set goes back off.
+                try {
+                    await releaseCatchAllRule(c, zone.id, catchAll);
+                    catchAll = undefined;
+                }
+                catch (e) {
+                    notes.push(`catch-all: ${e.message}`);
+                }
+            }
         }
     }
     if (wantSend && sendingOk) {
@@ -87,6 +109,7 @@ export async function syncDomain(c, a, deps) {
         ruleIds,
         ...(subscriptionId ? { subscriptionId } : {}),
         createdSending,
+        ...(catchAll ? { catchAll } : {}),
         notes,
     };
 }
@@ -107,6 +130,8 @@ export async function destroyDomain(c, d) {
             await attempt(`rule ${id}`, () => deleteRule(c, d.zoneId, id));
         if (d.createdSending && d.sendingTag)
             await attempt("sending domain", () => deleteSending(c, d.zoneId, d.sendingTag));
+        if (d.catchAll)
+            await attempt("catch-all", async () => void (await releaseCatchAllRule(c, d.zoneId, d.catchAll)));
     }
     if (d.subscriptionId)
         await attempt("event subscription", () => deleteEventSubscription(c, d.subscriptionId));

package/dist/component.d.ts

@@ -596,6 +596,7 @@ export declare const emailFunctions: {
                 subject: string;
                 html?: string;
             } | null;
+            catchAll?: boolean | null;
         }, GenericId<"mailboxes">>;
         removeMailbox: import("@freecorps/ember-server").RegisteredMutation<"public", {
             name: string;
@@ -613,6 +614,7 @@ export declare const emailFunctions: {
                 subject: string;
                 html?: string;
             };
+            catchAll?: boolean;
         }[]>;
         route: import("@freecorps/ember-server").RegisteredQuery<"public", {
             to: string;
@@ -1403,6 +1405,7 @@ export declare const email: import("@freecorps/ember-server").ComponentDefinitio
                 subject: string;
                 html?: string;
             } | null;
+            catchAll?: boolean | null;
         }, GenericId<"mailboxes">>;
         removeMailbox: import("@freecorps/ember-server").RegisteredMutation<"public", {
             name: string;
@@ -1420,6 +1423,7 @@ export declare const email: import("@freecorps/ember-server").ComponentDefinitio
                 subject: string;
                 html?: string;
             };
+            catchAll?: boolean;
         }[]>;
         route: import("@freecorps/ember-server").RegisteredQuery<"public", {
             to: string;

package/dist/component.js

@@ -387,10 +387,18 @@ function applyToEmail(ctx, e, ev) {
 }
 // ------------------------------------------------------------------------------------------------ inbound
 const THREAD_WINDOW = 30 * DAY;
+/** The catch-all mailbox of `domain`, if one is set. */
+function catchAllOf(ctx, domain) {
+    return ctx.db.query("mailboxes").collect().find((m) => m.catchAll && domainOf(m.address) === domain) ?? null;
+}
 function routeOf(ctx, to) {
     const { base, tag } = splitPlus(to.toLowerCase());
     const m = ctx.db.query("mailboxes").withIndex("by_address", (q) => q.eq("address", base)).first();
-    return m ? { mailbox: m.name, tag } : null;
+    if (m)
+        return { mailbox: m.name, tag };
+    // No mailbox has that address: its domain's catch-all takes it (the address it was sent to stays in its To).
+    const all = catchAllOf(ctx, domainOf(base));
+    return all ? { mailbox: all.name, tag: null } : null;
 }
 function token(ctx) {
     const abc = "abcdefghijklmnopqrstuvwxyz0123456789";
@@ -842,6 +850,8 @@ export const emailFunctions = {
                 displayName: v.optional(v.union(v.null(), v.string())),
                 /** Absent: keeps the stored one; null: clears it. */
                 autoReply: v.optional(v.union(v.null(), v.object({ subject: v.string(), text: v.string(), html: v.optional(v.string()) }))),
+                /** The domain's catch-all (one per domain). Absent: keeps the stored value; false or null: clears it. */
+                catchAll: v.optional(v.union(v.null(), v.boolean())),
             },
             handler: (ctx, a) => {
                 if (!/^[a-z][a-z0-9_-]{0,39}$/.test(a.name))
@@ -856,7 +866,21 @@ export const emailFunctions = {
                 // Patch semantics: an absent field keeps its stored value, null clears it.
                 const displayName = a.displayName === null ? undefined : (a.displayName ?? prev?.displayName);
                 const autoReply = a.autoReply === null ? undefined : (a.autoReply ?? prev?.autoReply);
-                const doc = { name: a.name, address, ...(displayName ? { displayName } : {}), ...(autoReply ? { autoReply } : {}), nextNumber: prev?.nextNumber ?? 1, createdAt: prev?.createdAt ?? ctx.now };
+                const catchAll = a.catchAll === undefined ? !!prev?.catchAll : !!a.catchAll;
+                if (catchAll) {
+                    const other = catchAllOf(ctx, domainOf(address));
+                    if (other && other.name !== a.name)
+                        fail("ValidationError", `${domainOf(address)} already has a catch-all: mailbox ${other.name}`);
+                }
+                const doc = {
+                    name: a.name,
+                    address,
+                    ...(displayName ? { displayName } : {}),
+                    ...(autoReply ? { autoReply } : {}),
+                    ...(catchAll ? { catchAll: true } : {}),
+                    nextNumber: prev?.nextNumber ?? 1,
+                    createdAt: prev?.createdAt ?? ctx.now,
+                };
                 if (prev) {
                     ctx.db.replace(prev._id, doc);
                     return prev._id;

package/dist/schema.d.ts

@@ -169,6 +169,8 @@ export declare const emailSchema: import("@freecorps/ember-server").SchemaDefini
             text: import("@freecorps/ember-values").Validator<string, "required", never>;
             html: import("@freecorps/ember-values").Validator<string, "optional", never>;
         }> | undefined>>;
+        /** Receives mail for any address of its domain that no other mailbox has (one per domain). */
+        catchAll: import("@freecorps/ember-values").Validator<boolean, "optional", never>;
         nextNumber: import("@freecorps/ember-values").Validator<number, "required", never>;
         createdAt: import("@freecorps/ember-values").Validator<number, "required", never>;
     }>, {

package/dist/schema.js

@@ -93,6 +93,8 @@ export const emailSchema = defineSchema({
             address: v.string(),
             displayName: v.optional(v.string()),
             autoReply: v.optional(v.object({ subject: v.string(), text: v.string(), html: v.optional(v.string()) })),
+            /** Receives mail for any address of its domain that no other mailbox has (one per domain). */
+            catchAll: v.optional(v.boolean()),
             nextNumber: v.number(),
             createdAt: v.number(),
         })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@freecorps/ember-email",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Email component for Ember on Cloudflare: send (atomic from mutations, scheduled, idempotent) through Email Service, templates, suppressions and per-project rate limits, delivery events from the Queue, inbound mail (Email Routing) parsed into mailboxes and threads. `@freecorps/ember-email/cloudflare` onboards a domain (sending, routing rules, event subscription) and removes it.",
   "keywords": [
     "ember",
@@ -52,9 +52,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@freecorps/ember-rate-limit": "0.5.6",
-    "@freecorps/ember-server": "0.5.6",
-    "@freecorps/ember-values": "0.5.6",
+    "@freecorps/ember-rate-limit": "0.5.7",
+    "@freecorps/ember-server": "0.5.7",
+    "@freecorps/ember-values": "0.5.7",
     "postal-mime": "^4.1.4"
   }
 }