@pilely/simple-email 0.3.0 → 0.4.2

package/dist/hooks.js

@@ -0,0 +1,116 @@
+import { serviceQueryKey, useServiceInfiniteQuery, useServiceMutation, useServiceQuery } from "@pilely/core";
+import { accountInfo, createAccount, createTemplate, deleteAccount, deleteTemplate, listAccounts, listSends, listTemplates, send, setAccountAccess, templateInfo, updateTemplate, } from "./api.js";
+/** `["pilely", "simple-email", "sends", options]` */
+const sendsKey = () => serviceQueryKey("simple-email", "sends");
+/** `["pilely", "simple-email", "accounts", options]` */
+const accountsKey = () => serviceQueryKey("simple-email", "accounts");
+/** `["pilely", "simple-email", "account"]` — this app's account info. */
+const accountKey = () => serviceQueryKey("simple-email", "account");
+/** `["pilely", "simple-email", "templates", options]` */
+const templatesKey = () => serviceQueryKey("simple-email", "templates");
+/** `["pilely", "simple-email", "template", templateId]` */
+const templateKey = (templateId) => serviceQueryKey("simple-email", "template", templateId);
+// ── Sending ──────────────────────────────────────────────────────────────
+/** Sends one email from this app's account: a raw send (`to`) or an account
+ *  send (`to_account: "self" | "owner"`). Not optimistic: a send counts only
+ *  once the server accepted it. A repeat carrying the same `idempotency_key`
+ *  answers the first send with `replayed: true`. */
+export function useSend() {
+    return useServiceMutation("useSend", {
+        mutationFn: send,
+        invalidates: () => [sendsKey()],
+    });
+}
+/** This app's outbox, newest first, as an infinite query. */
+export function useSends(options = {}) {
+    const { limit } = options;
+    return useServiceInfiniteQuery("useSends", {
+        queryKey: [...sendsKey(), { limit }],
+        fetchPage: async (cursor) => {
+            const page = await listSends({ limit, ...(cursor ?? {}) });
+            return { rows: page.sends, nextCursor: page.next_cursor };
+        },
+    });
+}
+// ── Accounts ─────────────────────────────────────────────────────────────
+/** The caller's email accounts across apps, as an infinite query. */
+export function useEmailAccounts(options = {}) {
+    const { limit } = options;
+    return useServiceInfiniteQuery("useEmailAccounts", {
+        queryKey: [...accountsKey(), { limit }],
+        fetchPage: async (cursor) => {
+            const page = await listAccounts({ limit, ...(cursor ?? {}) });
+            return { rows: page.accounts, nextCursor: page.next_cursor };
+        },
+    });
+}
+/** This app's account with its live state: daily cap, sent today, credit
+ *  and phone verification. */
+export function useEmailAccount() {
+    return useServiceQuery("useEmailAccount", { queryKey: accountKey(), queryFn: accountInfo });
+}
+/** Creates this app's account; the variable is its optional send group
+ *  (`null` or omitted: owner-only), or `{ send_group?, account_senders? }`. */
+export function useCreateEmailAccount() {
+    return useServiceMutation("useCreateEmailAccount", {
+        mutationFn: (input) => typeof input === "object" && input !== null
+            ? createAccount(input.send_group, input.account_senders)
+            : createAccount(input ?? undefined),
+        invalidates: () => [accountsKey(), accountKey()],
+    });
+}
+/** Deletes this app's account and the templates under it. */
+export function useDeleteEmailAccount() {
+    return useServiceMutation("useDeleteEmailAccount", {
+        mutationFn: () => deleteAccount(),
+        invalidates: () => [accountsKey(), accountKey(), templatesKey(), serviceQueryKey("simple-email", "template")],
+    });
+}
+/** Replaces this app's send group (`null` means owner-only); the object form
+ *  `{ send_group, account_senders? }` also sets who may make account sends. */
+export function useSetEmailAccountAccess() {
+    return useServiceMutation("useSetEmailAccountAccess", {
+        mutationFn: (input) => typeof input === "object" && input !== null
+            ? setAccountAccess(input.send_group, input.account_senders)
+            : setAccountAccess(input),
+        invalidates: () => [accountsKey(), accountKey()],
+    });
+}
+// ── Templates ────────────────────────────────────────────────────────────
+/** This app's templates (metadata only), as an infinite query. */
+export function useTemplates(options = {}) {
+    const { limit } = options;
+    return useServiceInfiniteQuery("useTemplates", {
+        queryKey: [...templatesKey(), { limit }],
+        fetchPage: async (cursor) => {
+            const page = await listTemplates({ limit, ...(cursor ?? {}) });
+            return { rows: page.templates, nextCursor: page.next_cursor };
+        },
+    });
+}
+/** One template with its `html`. An `undefined` id disables the query. */
+export function useTemplate(templateId) {
+    return useServiceQuery("useTemplate", {
+        queryKey: templateKey(templateId),
+        queryFn: () => templateInfo(templateId),
+        enabled: templateId !== undefined,
+    });
+}
+export function useCreateTemplate() {
+    return useServiceMutation("useCreateTemplate", {
+        mutationFn: ({ name, subject, html }) => createTemplate(name, subject, html),
+        invalidates: () => [templatesKey()],
+    });
+}
+export function useUpdateTemplate() {
+    return useServiceMutation("useUpdateTemplate", {
+        mutationFn: ({ templateId, subject, html }) => updateTemplate(templateId, { subject, html }),
+        invalidates: (_template, { templateId }) => [templatesKey(), templateKey(templateId)],
+    });
+}
+export function useDeleteTemplate() {
+    return useServiceMutation("useDeleteTemplate", {
+        mutationFn: deleteTemplate,
+        invalidates: (_none, templateId) => [templatesKey(), templateKey(templateId)],
+    });
+}

package/dist/index.d.ts

@@ -1,96 +1,4 @@
-import type { Account, AccountCursor, AccountInfoEnvelope, SendCursor, SendRow, Template, TemplateCursor, TemplateMeta } from "./types.js";
-export type { Account, SimpleEmailErrorCode, AccountCursor, AccountInfoEnvelope, SendCursor, SendRow, Template, TemplateCursor, TemplateMeta, } from "./types.js";
-/** `to` is capped at the service's `max_recipients_per_send` (50 by default). */
-export type SendContent = {
-    template_id: string;
-    variables?: Record<string, string>;
-} | {
-    subject: string;
-    html: string;
-};
-export type SendInput = {
-    to: string[];
-} & SendContent;
-export interface ListSendsOptions {
-    limit?: number;
-    after_created_time_stamp?: number;
-    after_send_id?: string;
-}
-export interface ListAccountsOptions {
-    limit?: number;
-    after_created_time_stamp?: number;
-    after_app_id?: string;
-}
-export interface ListTemplatesOptions {
-    limit?: number;
-    after_created_time_stamp?: number;
-    after_template_id?: string;
-}
-/** Both keys are REQUIRED — the server rejects either one missing with a
- *  400 (`ContentField::validate`), matching `updateTemplate`'s full-replace
- *  contract: there is no patch form on this route. */
-export interface UpdateTemplateBody {
-    subject: string;
-    html: string;
-}
-/**
- * `app_id` is added from core's `appId()` — it is not a caller parameter.
- * Body size is capped on this route (like `createTemplate`/`updateTemplate`):
- * an oversize body is rejected by the server before any handler runs, so
- * the failure is not an `{ok:false}` envelope and the thrown `PilelyError`
- * carries a null `code`.
- */
-export declare function send(input: SendInput): Promise<{
-    send_id: string;
-    recipient_count: number;
-}>;
-/** `app_id` lives in the body here, like `send` — not in the path. The
- *  paged primitive; use `listAllSends` to walk to the end. */
-export declare function listSends(options?: ListSendsOptions): Promise<{
-    sends: SendRow[];
-    next_cursor: SendCursor | null;
-}>;
-export declare function listAllSends(): Promise<SendRow[]>;
-/** `sendGroup` is optional here — omit it (or pass `undefined`) and the
- *  key is left off the wire, meaning owner-only. `setAccountAccess` below
- *  is the opposite: its key is always required. */
-export declare function createAccount(sendGroup?: string | null): Promise<Account>;
-/** No `app_id` anywhere on this route — `after_app_id` is a cursor field,
- *  not a selector. The paged primitive; use `listAllAccounts` to walk to
- *  the end. */
-export declare function listAccounts(options?: ListAccountsOptions): Promise<{
-    accounts: Account[];
-    next_cursor: AccountCursor | null;
-}>;
-export declare function listAllAccounts(): Promise<Account[]>;
-/** Returns the account plus its live operational state — the four extra
- *  fields are nullable siblings of `account`, not nested inside it. */
-export declare function accountInfo(): Promise<AccountInfoEnvelope>;
-export declare function deleteAccount(): Promise<void>;
-/** `sendGroup` is REQUIRED here and its key is always sent, even `null` —
- *  the opposite of `createAccount`, where the key is optional. `null`
- *  means owner-only. */
-export declare function setAccountAccess(sendGroup: string | null): Promise<Account>;
-/** Returns metadata only — no `html`. Use `templateInfo` to read the body
- *  back.
- *
- *  `name` is nullable because the service accepts a nameless template. It
- *  stays a required POSITIONAL parameter — pass an explicit `null`, not
- *  nothing — and `TemplateMeta.name` then comes back `null`. */
-export declare function createTemplate(name: string | null, subject: string, html: string): Promise<TemplateMeta>;
-/** The paged primitive; use `listAllTemplates` to walk to the end. Rows
- *  carry metadata only — no `html`. */
-export declare function listTemplates(options?: ListTemplatesOptions): Promise<{
-    templates: TemplateMeta[];
-    next_cursor: TemplateCursor | null;
-}>;
-export declare function listAllTemplates(): Promise<TemplateMeta[]>;
-/** The only template route whose answer carries `html`. */
-export declare function templateInfo(templateNanoid: string): Promise<Template>;
-/**
- * A FULL REPLACE of both `subject` and `html` — never a patch — and `name`
- * is not updatable at all. Returns metadata only, like `createTemplate`.
- * Subject to the same oversize-body caveat as `send`/`createTemplate`.
- */
-export declare function updateTemplate(templateNanoid: string, body: UpdateTemplateBody): Promise<TemplateMeta>;
-export declare function deleteTemplate(templateNanoid: string): Promise<void>;
+export { useCreateEmailAccount, useCreateTemplate, useDeleteEmailAccount, useDeleteTemplate, useEmailAccount, useEmailAccounts, useSend, useSends, useSetEmailAccountAccess, useTemplate, useTemplates, useUpdateTemplate, } from "./hooks.js";
+export type { CreateEmailAccountInput, CreateTemplateInput, PageOptions, SetEmailAccountAccessInput, UpdateTemplateInput, } from "./hooks.js";
+export type { AccountSendInput, RawSendInput, SendContent, SendInput, SendKey, SendResult } from "./api.js";
+export type { Account, AccountSenders, SimpleEmailErrorCode, AccountCursor, AccountInfoEnvelope, SendCursor, SendRow, Template, TemplateCursor, TemplateMeta, ToAccount, } from "./types.js";

package/dist/index.js

@@ -1,190 +1,4 @@
-// @pilely/simple-email — a typed wrapper over the simple_email service's 12
-// POST routes. See README.md for where app_id lives on each route: this is
-// the one service where it moves between the body and the path.
-import { appId, call, collectPages, isMockMode, registerMockService } from "@pilely/core";
-import { createSimpleEmailFake } from "./mock.js";
-// Importing this package is all an app does to get its fake in mock mode.
-// Dead code in a build without `VITE_PILELY_MOCK=1`, fake included.
-if (isMockMode()) {
-    registerMockService("simple-email", createSimpleEmailFake);
-}
-/**
- * Every route on this service needs an app id on the wire (body or path).
- * `@pilely/core`'s `appId()` can return `null` (no tag, `ready()` not yet
- * resolved) — this service cannot send that: a `null` in a path template
- * would silently become the literal string `"null"`. Fail loudly instead.
- */
-function requireAppId() {
-    const id = appId();
-    if (!id) {
-        throw new Error('pilely client not loaded, <meta name="pilely-app"> missing, and no token pile_id claim available yet — call after ready()');
-    }
-    return id;
-}
-// ── Sending ──────────────────────────────────────────────────────────────
-/**
- * `app_id` is added from core's `appId()` — it is not a caller parameter.
- * Body size is capped on this route (like `createTemplate`/`updateTemplate`):
- * an oversize body is rejected by the server before any handler runs, so
- * the failure is not an `{ok:false}` envelope and the thrown `PilelyError`
- * carries a null `code`.
- */
-export async function send(input) {
-    const body = "template_id" in input
-        ? { app_id: requireAppId(), to: input.to, template_id: input.template_id, variables: input.variables }
-        : { app_id: requireAppId(), to: input.to, subject: input.subject, html: input.html };
-    return call({
-        service: "simple-email",
-        path: "/send",
-        body,
-    });
-}
-/** `app_id` lives in the body here, like `send` — not in the path. The
- *  paged primitive; use `listAllSends` to walk to the end. */
-export async function listSends(options = {}) {
-    const json = await call({
-        service: "simple-email",
-        path: "/sends/list",
-        body: {
-            app_id: requireAppId(),
-            limit: options.limit,
-            after_created_time_stamp: options.after_created_time_stamp,
-            after_send_id: options.after_send_id,
-        },
-    });
-    return { sends: json.sends, next_cursor: json.next_cursor };
-}
-export async function listAllSends() {
-    return collectPages(async (cursor) => {
-        const page = await listSends({ limit: 100, ...(cursor ?? {}) });
-        return { rows: page.sends, nextCursor: page.next_cursor };
-    });
-}
-// ── Accounts ─────────────────────────────────────────────────────────────
-/** `sendGroup` is optional here — omit it (or pass `undefined`) and the
- *  key is left off the wire, meaning owner-only. `setAccountAccess` below
- *  is the opposite: its key is always required. */
-export async function createAccount(sendGroup) {
-    const body = { app_id: requireAppId() };
-    if (sendGroup !== undefined) {
-        body.send_group = sendGroup;
-    }
-    const json = await call({
-        service: "simple-email",
-        path: "/accounts/create",
-        body,
-    });
-    return json.account;
-}
-/** No `app_id` anywhere on this route — `after_app_id` is a cursor field,
- *  not a selector. The paged primitive; use `listAllAccounts` to walk to
- *  the end. */
-export async function listAccounts(options = {}) {
-    const json = await call({
-        service: "simple-email",
-        path: "/accounts/list",
-        body: {
-            limit: options.limit,
-            after_created_time_stamp: options.after_created_time_stamp,
-            after_app_id: options.after_app_id,
-        },
-    });
-    return { accounts: json.accounts, next_cursor: json.next_cursor };
-}
-export async function listAllAccounts() {
-    return collectPages(async (cursor) => {
-        const page = await listAccounts({ limit: 100, ...(cursor ?? {}) });
-        return { rows: page.accounts, nextCursor: page.next_cursor };
-    });
-}
-/** Returns the account plus its live operational state — the four extra
- *  fields are nullable siblings of `account`, not nested inside it. */
-export async function accountInfo() {
-    const json = await call({
-        service: "simple-email",
-        path: `/accounts/${requireAppId()}/info`,
-    });
-    return {
-        account: json.account,
-        daily_cap: json.daily_cap,
-        sent_today: json.sent_today,
-        credit_blocked: json.credit_blocked,
-        phone_verified: json.phone_verified,
-    };
-}
-export async function deleteAccount() {
-    await call({ service: "simple-email", path: `/accounts/${requireAppId()}/delete` });
-}
-/** `sendGroup` is REQUIRED here and its key is always sent, even `null` —
- *  the opposite of `createAccount`, where the key is optional. `null`
- *  means owner-only. */
-export async function setAccountAccess(sendGroup) {
-    const json = await call({
-        service: "simple-email",
-        path: `/accounts/${requireAppId()}/access/set`,
-        body: { send_group: sendGroup },
-    });
-    return json.account;
-}
-// ── Templates (nested under the account) ────────────────────────────────
-/** Returns metadata only — no `html`. Use `templateInfo` to read the body
- *  back.
- *
- *  `name` is nullable because the service accepts a nameless template. It
- *  stays a required POSITIONAL parameter — pass an explicit `null`, not
- *  nothing — and `TemplateMeta.name` then comes back `null`. */
-export async function createTemplate(name, subject, html) {
-    const json = await call({
-        service: "simple-email",
-        path: `/accounts/${requireAppId()}/templates/create`,
-        body: { name, subject, html },
-    });
-    return json.template;
-}
-/** The paged primitive; use `listAllTemplates` to walk to the end. Rows
- *  carry metadata only — no `html`. */
-export async function listTemplates(options = {}) {
-    const json = await call({
-        service: "simple-email",
-        path: `/accounts/${requireAppId()}/templates/list`,
-        body: {
-            limit: options.limit,
-            after_created_time_stamp: options.after_created_time_stamp,
-            after_template_id: options.after_template_id,
-        },
-    });
-    return { templates: json.templates, next_cursor: json.next_cursor };
-}
-export async function listAllTemplates() {
-    return collectPages(async (cursor) => {
-        const page = await listTemplates({ limit: 100, ...(cursor ?? {}) });
-        return { rows: page.templates, nextCursor: page.next_cursor };
-    });
-}
-/** The only template route whose answer carries `html`. */
-export async function templateInfo(templateNanoid) {
-    const json = await call({
-        service: "simple-email",
-        path: `/accounts/${requireAppId()}/templates/${templateNanoid}/info`,
-    });
-    return json.template;
-}
-/**
- * A FULL REPLACE of both `subject` and `html` — never a patch — and `name`
- * is not updatable at all. Returns metadata only, like `createTemplate`.
- * Subject to the same oversize-body caveat as `send`/`createTemplate`.
- */
-export async function updateTemplate(templateNanoid, body) {
-    const json = await call({
-        service: "simple-email",
-        path: `/accounts/${requireAppId()}/templates/${templateNanoid}/update`,
-        body,
-    });
-    return json.template;
-}
-export async function deleteTemplate(templateNanoid) {
-    await call({
-        service: "simple-email",
-        path: `/accounts/${requireAppId()}/templates/${templateNanoid}/delete`,
-    });
-}
+// @pilely/simple-email — React hooks over the simple_email service: a query
+// hook for every read, a mutation hook for every write. Render them inside
+// @pilely/core's <PilelyProvider>.
+export { useCreateEmailAccount, useCreateTemplate, useDeleteEmailAccount, useDeleteTemplate, useEmailAccount, useEmailAccounts, useSend, useSends, useSetEmailAccountAccess, useTemplate, useTemplates, useUpdateTemplate, } from "./hooks.js";

package/dist/mock.js

@@ -5,7 +5,13 @@
 // 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, daily caps, phone gates or credit checks. Writes
+// policy: no send groups, `account_senders` gating, daily caps, phone gates
+// 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. Reached only from the
 // `isMockMode()` branch in index.ts, so a production build carries none of
@@ -16,6 +22,11 @@ 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"];
 function isObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -35,9 +46,44 @@ function accountPayload(account) {
         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",
         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;
+}
+/** 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,
+    ]);
+}
 function templateMeta(template) {
     return {
         template_id: template.template_id,
@@ -82,12 +128,13 @@ export const createSimpleEmailFake = (ctx) => {
     function findAccount(appId) {
         return state.accounts.find((a) => a.app_id === appId);
     }
-    function createAccount(appId, sendGroup) {
+    function createAccount(appId, sendGroup, accountSenders) {
         const account = {
             app_id: appId,
             address: `${appId}@${SENDING_DOMAIN}`,
             display_name: null,
             send_group: sendGroup,
+            account_senders: accountSenders,
             created_time_stamp: ctx.now(),
             templates: [],
         };
@@ -98,16 +145,52 @@ export const createSimpleEmailFake = (ctx) => {
         if (typeof body.app_id !== "string" || body.app_id === "") {
             return ctx.refuse(400, "bad_request", "app_id is required");
         }
-        const to = body.to;
-        if (!Array.isArray(to) || to.length < 1 || to.length > MAX_RECIPIENTS || !to.every((r) => typeof r === "string")) {
-            return ctx.refuse(400, "bad_request", `to must hold 1..=${MAX_RECIPIENTS} addresses`);
+        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");
+        }
+        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 account = findAccount(body.app_id) ?? createAccount(body.app_id, null);
+        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");
+        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 });
+            }
+        }
         let subject;
         let html;
         let templateId = null;
@@ -128,30 +211,36 @@ export const createSimpleEmailFake = (ctx) => {
             subject = body.subject;
             html = body.html;
         }
-        const now = ctx.now();
+        // 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 row = {
             app_id: account.app_id,
+            fingerprint: print,
             send_id: ctx.nanoid(),
-            requester_user_id: ctx.user()?.id ?? "mock-user",
+            requester_user_id: caller,
             via_app: true,
             kind: hasTemplate ? "template" : "inline",
             template_id: templateId,
             subject,
-            recipients: [...to],
-            recipient_count: to.length,
+            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,
         };
         state.sends.push(row);
         save();
         console.log("[pilely mock] simple-email outbox: nothing was sent", {
             from: account.address,
-            to: row.recipients,
+            to: toAccount !== null ? `(the ${toAccount === "self" ? "caller's" : "owner's"} account email)` : row.recipients,
             subject,
             html,
         });
-        return ctx.ok({ ok: true, send_id: row.send_id, recipient_count: row.recipient_count });
+        return ctx.ok({ ok: true, send_id: row.send_id, recipient_count: row.recipient_count, replayed: false });
     }
     function handle(path, rawBody) {
         const body = isObject(rawBody) ? rawBody : {};
@@ -167,7 +256,7 @@ export const createSimpleEmailFake = (ctx) => {
             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(({ app_id: _appId, ...row }) => row);
+            const sends = result.page.map(sendPayload);
             return ctx.ok({ ok: true, sends, next_cursor: result.next });
         }
         if (path === "/accounts/create") {
@@ -179,8 +268,12 @@ 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 sendGroup = typeof body.send_group === "string" ? body.send_group : null;
-            const account = createAccount(body.app_id, sendGroup);
+            const account = createAccount(body.app_id, sendGroup, accountSenders ?? "send_group");
             save();
             return ctx.ok({ ok: true, account: accountPayload(account) });
         }
@@ -224,7 +317,14 @@ export const createSimpleEmailFake = (ctx) => {
                 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) });
         }