@pilely/simple-email 0.4.5 → 0.5.0

package/dist/mock.js

@@ -1,35 +1,57 @@
 // The in-browser fake of the simple_email service that `@pilely/core`'s
 // mock runtime routes to in mock mode. It answers every route this
-// package's wrapper calls with the JSON the real service returns. Nothing
-// is ever sent: `send` appends to an in-memory outbox (the rows `listSends`
-// answers) and logs the message to the console. Accounts and templates
-// live in memory and persist through the core store; an app's account is
-// created on its first send if it does not exist yet. It models shape, not
-// policy: no send groups, `account_senders` gating, daily caps or credit
-// checks. It does model the send shapes (raw and account sends)
-// and `idempotency_key`: a repeat with the same key, body and caller within
-// 24 hours answers the first send with `replayed: true` and adds no row; the
-// same key with another body or caller is `409 idempotency_key_reused`. An
-// account send to `"self"` logs `recipients: []`, one to `"owner"` logs a
-// stand-in owner address — the fake has no real account emails. Writes
-// need a signed-in user; a signed-out write and a missing account or
-// template answer the uniform bare 404. Accounts carry `reply_to`, set on
-// create and by `set_reply_to` (key required, a string or `null`); the fake
-// checks only its type, not the address rules or refused domains. Reached
-// only from the
-// `isMockMode()` branch in index.ts, so a production build carries none of
-// it.
+// package's page-side functions call with the JSON the real service
+// returns. Nothing is ever sent: a template send appends to an in-memory
+// outbox, carrying the template's stored recipient, and logs the message to
+// the console; its answer is `{ ok, send_id }` and never the address.
+// Accounts and templates live in memory and persist through the core store.
+//
+// The template send admits callers by the template's groups the way the
+// simple-db fake admits by policies: an empty `send_group` admits nobody;
+// the two platform-wide groups hold callers by type (every signed-out
+// visitor is in the anonymous group, every signed-in person — the owner
+// included — in the authenticated group), named by the same fixed test ids
+// the simple-group fake answers; the fake has no group membership data, so
+// ANY OTHER GROUP HOLDS NOBODY — an owner group as `send_group` admits no
+// one and a `deny_group` denies no one. Every refused caller gets the
+// uniform bare 404. Each placeholder of the template is read from the body
+// field of the same name; a missing or non-string one is `400 bad_request`
+// and nothing lands in the outbox; every other field is ignored.
+//
+// The freestyle send (`accounts/{app_id}/send`) answers the uniform bare
+// 404 to every caller: the service admits only the app's backend there, and
+// no caller in a browser is one. `send()` itself never reaches this fake —
+// it is a server function that calls `fetch` directly.
+//
+// Owner writes need a signed-in user; a signed-out write and a missing
+// account or template answer the uniform bare 404. Accounts carry
+// `reply_to`, set on create and by `set_reply_to` (key required, a string
+// or `null`); templates carry `recipient` (required on create), `send_group`
+// and `deny_group` (a platform-wide group as `deny_group` is the service's
+// 400). The fake checks the fields' shapes, not the address rules, refused
+// domains or group ownership. It does not model the daily caps, rate
+// limits or credit checks. Reached only from the `isMockMode()` branch in
+// api.ts, so a production build carries none of it.
 const MARKER = "pilely-mock-fake:simple-email";
 const DEFAULT_PAGE_SIZE = 50;
 const MAX_PAGE_SIZE = 100;
-const MAX_RECIPIENTS = 50;
 const DAILY_CAP = 200;
 const SENDING_DOMAIN = "mail.pilely.invalid";
-const ACCOUNT_EMAIL_DOMAIN = "account.pilely.invalid";
-const IDEMPOTENCY_WINDOW_MS = 24 * 60 * 60 * 1000;
-const IDEMPOTENCY_KEY = /^[A-Za-z0-9._:-]{1,128}$/;
-const ACCOUNT_SENDERS = ["send_group", "app_users"];
-const TO_ACCOUNT = ["self", "owner"];
+const VARIABLES_MAX_BYTES = 4096;
+const GROUP_ID = /^[A-Za-z0-9]{1,64}$/;
+const ADDRESS = /^[^@\s]+@[^@\s]+\.[^@\s]+$/;
+const PLACEHOLDER = /\{\{\s*([A-Za-z0-9_]+)\s*\}\}/g;
+/** The fake's ids for the two platform-wide groups: fixed test values, not
+ *  the production ids. `@pilely/simple-group`'s fake answers the same two
+ *  from `groups/anonymous` and `groups/authenticated`, so in mock mode an id
+ *  read from `anonymousGroupId()` / `authenticatedGroupId()` works as a
+ *  template's `send_group` here. Not part of the package's public surface. */
+export const MOCK_ANON_GROUP = "mockAnonymousGroup0001";
+export const MOCK_AUTH_GROUP = "mockAuthenticatedGrp01";
+/** A template persisted before the template-send fields existed reads this
+ *  recipient, the stand-in for the owner's account email the service's
+ *  migration stored. */
+const LEGACY_RECIPIENT = "owner@account.pilely.invalid";
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -40,34 +62,36 @@ function pageSize(body) {
     const raw = body.limit === undefined || body.limit === null ? DEFAULT_PAGE_SIZE : Number(body.limit);
     return Math.min(MAX_PAGE_SIZE, Math.max(1, Number.isFinite(raw) ? Math.trunc(raw) : DEFAULT_PAGE_SIZE));
 }
-function render(text, variables) {
-    return text.replace(/\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g, (whole, name) => name in variables ? String(variables[name]) : whole);
+/** Every placeholder name in `text`, in order of first use. */
+function placeholders(text) {
+    return [...new Set([...text.matchAll(PLACEHOLDER)].map((m) => m[1]))];
+}
+function render(text, values) {
+    return text.replace(PLACEHOLDER, (whole, name) => (name in values ? values[name] : whole));
 }
 function accountPayload(account) {
+    // Built field by field, so state persisted with fields the service no
+    // longer answers never reaches the wire.
     return {
         app_id: account.app_id,
         address: account.address,
         display_name: account.display_name,
-        send_group: account.send_group,
-        // State persisted before account_senders existed reads the default.
-        account_senders: account.account_senders ?? "send_group",
         // State persisted before reply_to existed reads none.
         reply_to: account.reply_to ?? null,
         created_time_stamp: account.created_time_stamp,
     };
 }
-/** The wire row: the fake's own fields stripped, and the two newer keys
- *  defaulted for rows persisted before they existed. */
-function sendPayload({ app_id: _appId, fingerprint: _fingerprint, ...row }) {
-    return { ...row, to_account: row.to_account ?? null, idempotency_key: row.idempotency_key ?? null };
-}
-/** `undefined` when the key is absent; `null` when it is present but not
- *  one of the two values (an explicit `null` included — the server's 400). */
-function parseAccountSenders(body) {
-    if (!("account_senders" in body))
-        return undefined;
-    const value = body.account_senders;
-    return ACCOUNT_SENDERS.includes(value) ? value : null;
+function templateMeta(template) {
+    return {
+        template_id: template.template_id,
+        name: template.name,
+        subject: template.subject,
+        recipient: template.recipient ?? LEGACY_RECIPIENT,
+        send_group: template.send_group ?? null,
+        deny_group: template.deny_group ?? null,
+        created_time_stamp: template.created_time_stamp,
+        updated_time_stamp: template.updated_time_stamp,
+    };
 }
 /** `undefined` when the key is absent; the address, or `null` (none). A value
  *  of any other type is the server's 400, answered as `false`. */
@@ -79,34 +103,27 @@ function parseReplyTo(body) {
         return value;
     return false;
 }
-/** The service's "same body": the caller, the mode, `to` as a
- *  case-insensitive set, `to_account`, the template and its variables, and
- *  inline content. */
-function fingerprint(caller, body, to) {
-    const variables = isObject(body.variables)
-        ? Object.keys(body.variables)
-            .sort()
-            .map((name) => [name, body.variables[name]])
-        : null;
-    return JSON.stringify([
-        caller,
-        body.app_id,
-        to === null ? null : [...new Set(to.map((r) => r.toLowerCase()))].sort(),
-        body.to_account ?? null,
-        body.template_id ?? null,
-        variables,
-        body.subject ?? null,
-        body.html ?? null,
-    ]);
+/** `undefined` when the key is absent; the group id, or `null` (empty). A
+ *  value that is not a group id is the server's 400, answered as `false`. */
+function parseGroup(body, key) {
+    if (!(key in body))
+        return undefined;
+    const value = body[key];
+    if (value === null)
+        return null;
+    if (typeof value === "string" && GROUP_ID.test(value))
+        return value;
+    return false;
 }
-function templateMeta(template) {
-    return {
-        template_id: template.template_id,
-        name: template.name,
-        subject: template.subject,
-        created_time_stamp: template.created_time_stamp,
-        updated_time_stamp: template.updated_time_stamp,
-    };
+/** Whether `group` holds the caller: the anonymous group every signed-out
+ *  visitor, the authenticated group every signed-in person; the fake has no
+ *  membership data, so any other group holds nobody. */
+function groupHolds(group, signedIn) {
+    if (group === MOCK_ANON_GROUP)
+        return !signedIn;
+    if (group === MOCK_AUTH_GROUP)
+        return signedIn;
+    return false;
 }
 /**
  * Newest-first keyset paging over rows already sorted, with the cursor
@@ -143,138 +160,69 @@ export const createSimpleEmailFake = (ctx) => {
     function findAccount(appId) {
         return state.accounts.find((a) => a.app_id === appId);
     }
-    function createAccount(appId, sendGroup, accountSenders, replyTo) {
-        const account = {
-            app_id: appId,
-            address: `${appId}@${SENDING_DOMAIN}`,
-            display_name: null,
-            send_group: sendGroup,
-            account_senders: accountSenders,
-            reply_to: replyTo,
-            created_time_stamp: ctx.now(),
-            templates: [],
-        };
-        state.accounts.push(account);
-        return account;
-    }
-    function send(body) {
-        if (typeof body.app_id !== "string" || body.app_id === "") {
-            return ctx.refuse(400, "bad_request", "app_id is required");
+    /** The two groups of a create or update body, or the server's 400. Each
+     *  is `undefined` when its key is absent. */
+    function parseGroups(body) {
+        const sendGroup = parseGroup(body, "send_group");
+        const denyGroup = parseGroup(body, "deny_group");
+        if (sendGroup === false || denyGroup === false) {
+            return ctx.refuse(400, "bad_request", "send_group and deny_group must be a group id (1..=64 of [A-Za-z0-9]) or null");
         }
-        const hasTo = body.to !== undefined && body.to !== null;
-        const hasToAccount = body.to_account !== undefined && body.to_account !== null;
-        if (hasTo === hasToAccount) {
-            return ctx.refuse(400, "bad_request", "send either to or to_account");
+        if (denyGroup === MOCK_ANON_GROUP || denyGroup === MOCK_AUTH_GROUP) {
+            return ctx.refuse(400, "bad_request", "deny_group must be an ACTIVE simple_group owned by you, or null");
         }
-        let to = null;
-        let toAccount = null;
-        if (hasTo) {
-            const raw = body.to;
-            if (!Array.isArray(raw) || raw.length < 1 || raw.length > MAX_RECIPIENTS || !raw.every((r) => typeof r === "string")) {
-                return ctx.refuse(400, "bad_request", `to must hold 1..=${MAX_RECIPIENTS} addresses`);
-            }
-            to = raw;
-        }
-        else {
-            if (!TO_ACCOUNT.includes(body.to_account)) {
-                return ctx.refuse(400, "bad_request", 'to_account must be "self" or "owner"');
-            }
-            toAccount = body.to_account;
-        }
-        const hasTemplate = body.template_id !== undefined && body.template_id !== null;
-        const hasInline = body.subject !== undefined || body.html !== undefined;
-        if (toAccount !== null && (hasInline || !hasTemplate)) {
-            return ctx.refuse(400, "bad_request", "an account send takes template_id, never subject or html");
-        }
-        if (hasTemplate === hasInline) {
-            return ctx.refuse(400, "bad_request", "send either template_id or subject + html");
-        }
-        const key = body.idempotency_key;
-        if (key !== undefined && (typeof key !== "string" || !IDEMPOTENCY_KEY.test(key))) {
-            return ctx.refuse(400, "bad_request", "idempotency_key must be 1..=128 characters of [A-Za-z0-9._:-]");
-        }
-        const account = findAccount(body.app_id) ?? createAccount(body.app_id, null, "send_group", null);
-        const user = ctx.user();
-        const caller = user?.id ?? "mock-user";
-        const print = fingerprint(caller, body, to);
-        const now = ctx.now();
-        if (typeof key === "string") {
-            const first = state.sends.find((s) => s.app_id === account.app_id && s.idempotency_key === key && now - s.fired_at < IDEMPOTENCY_WINDOW_MS);
-            if (first) {
-                if (first.fingerprint !== print) {
-                    return ctx.refuse(409, "idempotency_key_reused", "this idempotency_key belongs to a different request");
-                }
-                return ctx.ok({ ok: true, send_id: first.send_id, recipient_count: first.recipient_count, replayed: true });
-            }
+        return { send_group: sendGroup, deny_group: denyGroup };
+    }
+    /** The template send: the caller and the template's groups, then the
+     *  body, then the outbox. */
+    function sendTemplate(account, template, rawBody) {
+        const signedIn = ctx.user() !== null;
+        if (!account || !template)
+            return ctx.notFound();
+        const sendGroup = template.send_group ?? null;
+        if (!groupHolds(sendGroup, signedIn))
+            return ctx.notFound();
+        // A deny_group is an owner group, and an owner group holds nobody here.
+        if (rawBody !== undefined && rawBody !== null && !isObject(rawBody)) {
+            return ctx.refuse(400, "bad_request", "the body must be a JSON object of the template's variables");
         }
-        let subject;
-        let html;
-        let templateId = null;
-        if (hasTemplate) {
-            const template = account.templates.find((t) => t.template_id === body.template_id);
-            if (!template) {
-                return ctx.refuse(400, "bad_request", "template_id names no template of this account");
+        const body = isObject(rawBody) ? rawBody : {};
+        const values = {};
+        for (const name of placeholders(`${template.subject}\n${template.html}`)) {
+            const value = body[name];
+            if (typeof value !== "string") {
+                return ctx.refuse(400, "bad_request", `template variable ${name} is missing or not a string`);
             }
-            const variables = isObject(body.variables) ? body.variables : {};
-            subject = render(template.subject, variables);
-            html = render(template.html, variables);
-            templateId = template.template_id;
+            values[name] = value;
         }
-        else {
-            if (typeof body.subject !== "string" || typeof body.html !== "string") {
-                return ctx.refuse(400, "bad_request", "subject and html are required together");
-            }
-            subject = body.subject;
-            html = body.html;
+        if (new TextEncoder().encode(Object.values(values).join("")).length > VARIABLES_MAX_BYTES) {
+            return ctx.refuse(400, "bad_request", `the template's values exceed ${VARIABLES_MAX_BYTES} bytes`);
         }
-        // A "self" row never shows the caller's address; an "owner" row shows the
-        // owner's own. The fake has no account emails, so the owner's is a
-        // stand-in built from the signed-in mock user's handle.
-        const recipients = to !== null ? [...to] : toAccount === "owner" ? [`${user?.handle ?? "owner"}@${ACCOUNT_EMAIL_DOMAIN}`] : [];
+        const recipient = template.recipient ?? LEGACY_RECIPIENT;
+        const subject = render(template.subject, values);
+        const html = render(template.html, values);
         const row = {
             app_id: account.app_id,
-            fingerprint: print,
             send_id: ctx.nanoid(),
-            requester_user_id: caller,
-            via_app: true,
-            kind: hasTemplate ? "template" : "inline",
-            template_id: templateId,
+            template_id: template.template_id,
+            recipient,
             subject,
-            recipients,
-            recipient_count: to !== null ? to.length : 1,
-            outcome: "sent",
-            outcome_reason: null,
-            to_account: toAccount,
-            idempotency_key: typeof key === "string" ? key : null,
-            fired_at: now,
+            recipient_count: 1,
+            fired_at: ctx.now(),
         };
         state.sends.push(row);
         save();
         console.log("[pilely mock] simple-email outbox: nothing was sent", {
             from: account.address,
-            to: toAccount !== null ? `(the ${toAccount === "self" ? "caller's" : "owner's"} account email)` : row.recipients,
+            to: recipient,
             subject,
             html,
         });
-        return ctx.ok({ ok: true, send_id: row.send_id, recipient_count: row.recipient_count, replayed: false });
+        return ctx.ok({ ok: true, send_id: row.send_id });
     }
     function handle(path, rawBody) {
         const body = isObject(rawBody) ? rawBody : {};
         const signedIn = ctx.user() !== null;
-        if (path === "/send") {
-            if (!signedIn)
-                return ctx.notFound();
-            return send(body);
-        }
-        if (path === "/sends/list") {
-            const appId = typeof body.app_id === "string" ? body.app_id : "";
-            const rows = state.sends.filter((s) => s.app_id === appId);
-            const result = keysetPage(rows, body, ["after_created_time_stamp", "after_send_id"], (s) => [s.fired_at, s.send_id], (s) => ({ after_created_time_stamp: s.fired_at, after_send_id: s.send_id }));
-            if (!result)
-                return cursorRefusal();
-            const sends = result.page.map(sendPayload);
-            return ctx.ok({ ok: true, sends, next_cursor: result.next });
-        }
         if (path === "/accounts/create") {
             if (!signedIn)
                 return ctx.notFound();
@@ -284,16 +232,19 @@ export const createSimpleEmailFake = (ctx) => {
             if (findAccount(body.app_id)) {
                 return ctx.refuse(409, "account_exists", "this app already has an email account");
             }
-            const accountSenders = parseAccountSenders(body);
-            if (accountSenders === null) {
-                return ctx.refuse(400, "bad_request", 'account_senders must be "send_group" or "app_users"');
-            }
             const replyTo = parseReplyTo(body);
             if (replyTo === false) {
                 return ctx.refuse(400, "bad_request", "reply_to must be an email address or null");
             }
-            const sendGroup = typeof body.send_group === "string" ? body.send_group : null;
-            const account = createAccount(body.app_id, sendGroup, accountSenders ?? "send_group", replyTo ?? null);
+            const account = {
+                app_id: body.app_id,
+                address: `${body.app_id}@${SENDING_DOMAIN}`,
+                display_name: null,
+                reply_to: replyTo ?? null,
+                created_time_stamp: ctx.now(),
+                templates: [],
+            };
+            state.accounts.push(account);
             save();
             return ctx.ok({ ok: true, account: accountPayload(account) });
         }
@@ -309,6 +260,10 @@ export const createSimpleEmailFake = (ctx) => {
         const account = findAccount(parts[1]);
         const rest = parts.slice(2);
         const route = rest.join("/");
+        if (route === "send") {
+            // Only the app's backend may make a freestyle send; no browser caller is one.
+            return ctx.notFound();
+        }
         if (route === "info") {
             if (!account)
                 return ctx.notFound();
@@ -331,22 +286,6 @@ export const createSimpleEmailFake = (ctx) => {
             save();
             return ctx.ok({ ok: true });
         }
-        if (route === "access/set") {
-            if (!signedIn || !account)
-                return ctx.notFound();
-            if (!("send_group" in body))
-                return ctx.refuse(400, "bad_request", "send_group is required");
-            const accountSenders = parseAccountSenders(body);
-            if (accountSenders === null) {
-                return ctx.refuse(400, "bad_request", 'account_senders must be "send_group" or "app_users"');
-            }
-            account.send_group = typeof body.send_group === "string" ? body.send_group : null;
-            // Omitted keeps the current value.
-            if (accountSenders !== undefined)
-                account.account_senders = accountSenders;
-            save();
-            return ctx.ok({ ok: true, account: accountPayload(account) });
-        }
         if (route === "set_reply_to") {
             if (!signedIn || !account)
                 return ctx.notFound();
@@ -367,12 +306,21 @@ export const createSimpleEmailFake = (ctx) => {
             if (typeof body.subject !== "string" || typeof body.html !== "string") {
                 return ctx.refuse(400, "bad_request", "subject and html are required");
             }
+            if (typeof body.recipient !== "string" || !ADDRESS.test(body.recipient)) {
+                return ctx.refuse(400, "bad_request", "recipient is required: one email address");
+            }
+            const groups = parseGroups(body);
+            if ("status" in groups)
+                return groups;
             const now = ctx.now();
             const template = {
                 template_id: ctx.nanoid(),
                 name: typeof body.name === "string" ? body.name : null,
                 subject: body.subject,
                 html: body.html,
+                recipient: body.recipient,
+                send_group: groups.send_group ?? null,
+                deny_group: groups.deny_group ?? null,
                 created_time_stamp: now,
                 updated_time_stamp: now,
             };
@@ -392,6 +340,9 @@ export const createSimpleEmailFake = (ctx) => {
             return null;
         const template = account?.templates.find((t) => t.template_id === rest[1]);
         const action = rest[2];
+        if (action === "send") {
+            return sendTemplate(account, template, rawBody);
+        }
         if (action === "info") {
             if (!template)
                 return ctx.notFound();
@@ -403,8 +354,21 @@ export const createSimpleEmailFake = (ctx) => {
             if (typeof body.subject !== "string" || typeof body.html !== "string") {
                 return ctx.refuse(400, "bad_request", "subject and html are both required");
             }
+            if ("recipient" in body && (typeof body.recipient !== "string" || !ADDRESS.test(body.recipient))) {
+                return ctx.refuse(400, "bad_request", "recipient must be one email address; it cannot be emptied");
+            }
+            const groups = parseGroups(body);
+            if ("status" in groups)
+                return groups;
             template.subject = body.subject;
             template.html = body.html;
+            // An omitted key keeps the stored value; null empties a group.
+            if (typeof body.recipient === "string")
+                template.recipient = body.recipient;
+            if (groups.send_group !== undefined)
+                template.send_group = groups.send_group;
+            if (groups.deny_group !== undefined)
+                template.deny_group = groups.deny_group;
             template.updated_time_stamp = ctx.now();
             save();
             return ctx.ok({ ok: true, template: templateMeta(template) });

package/dist/send.d.ts

@@ -0,0 +1,75 @@
+import type { SimpleEmailErrorCode } from "./types.js";
+/** Where the service answers. A testing-tier lane passes its own origin. */
+export declare const SIMPLE_EMAIL_ORIGIN = "https://simple-email.pilely.app";
+/** `to` holds 1 to 50 addresses. */
+export type SendContent = {
+    template_id: string;
+    variables?: Record<string, string>;
+} | {
+    subject: string;
+    html: string;
+};
+/**
+ * Optional on both shapes: 1–128 characters of `[A-Za-z0-9._:-]`, held per
+ * app for 24 hours from its first use. A repeat with the same key and the
+ * same body answers the first send's `send_id` with `replayed: true` and
+ * sends and bills nothing; the same key with another body is
+ * `409 idempotency_key_reused`. Pick keys stable per logical email
+ * (`digest:<user id>:<YYYY-MM-DD>`, `confirm:<row id>`) — a new key per
+ * attempt defeats the protection.
+ */
+export interface SendKey {
+    idempotency_key?: string;
+}
+/** A freestyle send: to the addresses in `to`, template or inline content. */
+export type SendInput = {
+    to: string[];
+} & SendContent & SendKey;
+/** `replayed` is `true` when the answer is an earlier keyed send's (nothing
+ *  new was sent), `false` for a new send — and always `false` without an
+ *  `idempotency_key`. Duplicate addresses collapse, so `recipient_count`
+ *  can be lower than `to.length`. */
+export interface SendResult {
+    send_id: string;
+    recipient_count: number;
+    replayed: boolean;
+}
+export interface SendOptions {
+    /** The account's app — the app whose backend this is. */
+    appId: string;
+    /** The backend's own `PILELY_BACKEND_TOKEN`. Sent only as the bearer,
+     *  only to `origin`. */
+    backendToken: string;
+    /** Defaults to `https://simple-email.pilely.app`. */
+    origin?: string;
+}
+/** A refused `send`. `code` is `null` for a bodiless answer — an oversize
+ *  body refused before any handler runs, an unknown path — and on a missing
+ *  `appId` or `backendToken` (`status` 0, nothing was sent). Never carries
+ *  the token. */
+export declare class SendError extends Error {
+    readonly status: number;
+    readonly code: SimpleEmailErrorCode | null;
+    readonly reason: string;
+    name: string;
+    constructor(status: number, code: SimpleEmailErrorCode | null, reason: string);
+}
+/**
+ * Sends one message from the app's account to every address in `to`:
+ * `POST <origin>/accounts/<appId>/send` with the backend token as bearer.
+ * Resolves to the service's answer; throws `SendError` on any refusal — a
+ * caller that is not this app's backend, an unknown account or template, or
+ * the owner out of balance (all one 404), a bad body (400), an
+ * `idempotency_key` conflict (409), the app's 500-recipient UTC-day
+ * freestyle cap (`429 daily_cap_exceeded`).
+ *
+ * ```ts
+ * import { send } from "@pilely/simple-email/send";
+ *
+ * await send(
+ *   { to: [row.email], template_id: WELCOME, variables: { name: row.name }, idempotency_key: `welcome:${row.id}` },
+ *   { appId: process.env.APP_ID!, backendToken: process.env.PILELY_BACKEND_TOKEN! },
+ * );
+ * ```
+ */
+export declare function send(input: SendInput, options: SendOptions): Promise<SendResult>;