@pilely/simple-email 0.4.0 → 0.4.2

package/README.md

@@ -6,13 +6,13 @@ React hooks for the `simple_email` service — the platform's managed transactio
 
 | Hook | Wraps | Kind |
 | --- | --- | --- |
-| `useSend()` | `/send` | mutation, `{ to, subject, html }` or `{ to, template_id, variables? }` |
+| `useSend()` | `/send` | mutation, `{ to, subject, html }` or `{ to, template_id, variables? }` (a raw send), or `{ to_account, template_id, variables? }` (an account send); each takes an optional `idempotency_key`. Answers `{ send_id, recipient_count, replayed }` |
 | `useSends({ limit? })` | `/sends/list`, paged | infinite query; this app's outbox, `SendRow[]` |
 | `useEmailAccount()` | `accounts/{app}/info` | query; this app's account with its daily cap, sent today, credit and phone state |
 | `useEmailAccounts({ limit? })` | `accounts/list`, paged | infinite query; every account the caller owns |
-| `useCreateEmailAccount()` | `accounts/create` | mutation, the optional send group |
+| `useCreateEmailAccount()` | `accounts/create` | mutation, the optional send group, or `{ send_group?, account_senders? }` |
 | `useDeleteEmailAccount()` | `accounts/{app}/delete` | mutation, no variables |
-| `useSetEmailAccountAccess()` | `accounts/{app}/access/set` | mutation, the send group (`null` = owner-only) |
+| `useSetEmailAccountAccess()` | `accounts/{app}/access/set` | mutation, the send group (`null` = owner-only), or `{ send_group, account_senders? }` (an omitted `account_senders` keeps the current value) |
 | `useTemplates({ limit? })` | `templates/list`, paged | infinite query; metadata only |
 | `useTemplate(templateId)` | `templates/{t}/info` | query; the template with its `html`; an `undefined` id disables it |
 | `useCreateTemplate()` | `templates/create` | mutation, `{ name, subject, html }` (`name` may be `null`) |
@@ -21,6 +21,16 @@ React hooks for the `simple_email` service — the platform's managed transactio
 
 The app id is added from `@pilely/core` on every route; it is never a variable. Every write waits for the server: an email "sent" before the server accepted it would be a lie.
 
+## Raw sends and account sends
+
+A **raw send** (`to`) goes to the addresses you name, with template or inline content. An **account send** (`to_account`) sends a template to one address the service looks up itself: the caller's own Pilely account email (`"self"`) or the app owner's (`"owner"`). The caller never supplies or sees that address — not in the answer, and not on the `"self"` row of the owner's `useSends()` (its `recipients` is `[]`). An account send is template-only: `to` with `to_account`, or `subject` / `html` on an account send, does not typecheck. It counts 1 recipient toward the daily cap and is billed to the owner like any other send.
+
+Who may make account sends is the account's `account_senders`: `"send_group"` (the default — the owner and the send group's members) or `"app_users"` (also every signed-in user of the app, through the app; raw sends stay closed to them). When you choose `"app_users"`, add a per-user `@simple_limiter` policy on `simple-email.<endpoint>` `/send` — without it one user can use up the app's daily cap and spend your balance. The service README's `### Who can send from an account` has the full table.
+
+## Retries: `idempotency_key`
+
+Give a send an `idempotency_key` (1–128 characters of `[A-Za-z0-9._:-]`, held per app for 24 hours) and a repeat with the same key, the same body and the same caller answers the FIRST send's `send_id` with `replayed: true` — nothing is sent, billed or counted again. The same key with another body or from another caller is `idempotency_key_reused` (409); a repeat while the first is still being handed to the provider is `idempotency_key_in_progress` (409, retry in a few seconds). Pick keys stable per logical email — `confirm:<row id>`, `digest:<user id>:<YYYY-MM-DD>` — so a retry after a crash or a timeout repeats the same key. Without a key every request is a new send, and `replayed` is `false`.
+
 ## What each write refreshes
 
 | Write | Invalidates |
@@ -45,10 +55,25 @@ export function Outbox() {
         Send
       </button>
       {send.error && <p role="alert">{send.error.message}</p>}
-      <ul>{sends?.map((row) => <li key={row.send_id}>{row.subject} — {row.outcome}</li>)}</ul>
+      <ul>
+        {sends?.map((row) => (
+          <li key={row.send_id}>
+            {row.subject} — {row.outcome}
+            {row.to_account && ` (to the ${row.to_account} account email)`}
+          </li>
+        ))}
+      </ul>
     </>
   );
 }
+
+// After a row is stored: confirm it to the signed-in submitter, once, even if
+// the page retries. `templateId` is a template of this app's account.
+export function useConfirmSubmission(templateId: string) {
+  const send = useSend();
+  return (rowId: string) =>
+    send.mutateAsync({ to_account: "self", template_id: templateId, idempotency_key: `confirm:${rowId}` });
+}
 ```
 
 ## Query keys
@@ -69,17 +94,19 @@ export function Outbox() {
 
 Importing this package in a build made with `VITE_PILELY_MOCK=1` registers an in-browser fake of `simple_email` behind `@pilely/core`'s mock runtime — nothing else to call.
 
-**Nothing is ever sent.** A send is appended to an in-memory outbox — the rows `useSends` answers — and logged to the console. Accounts and templates persist to `localStorage` across reloads; the app's account is created on its first send. A missing account or template answers the bare 404, and a second account for the same app answers `account_exists` (409). The 50-recipient bound is kept. It does not model send groups, the daily cap, the phone gate, rate limits or credit checks.
+**Nothing is ever sent.** A send is appended to an in-memory outbox — the rows `useSends` answers — and logged to the console. Accounts and templates persist to `localStorage` across reloads; the app's account is created on its first send. A missing account or template answers the bare 404, and a second account for the same app answers `account_exists` (409). The 50-recipient bound is kept.
+
+It models the send shapes and `idempotency_key`: an account send's row carries `to_account` and one recipient (`recipients: []` for `"self"`, a stand-in owner address for `"owner"` — the fake has no real account emails); a body with both `to` and `to_account`, or an account send with inline content, is `bad_request`; a repeat with the same key, body and caller answers `replayed: true` without a new row, and the same key with another body is `idempotency_key_reused`. Accounts carry `account_senders`, settable on create and access/set. It does not model send groups, `account_senders` gating, the daily cap, the phone gate, rate limits, credit checks or `idempotency_key_in_progress`.
 
 Writes need a signed-in user: a signed-out write answers the uniform bare 404, which reaches the hook's `error` as `PilelyError(404, null)`. See [`@pilely/core`](../core#mock-mode) for the switch, `seedMock()` and `resetMock()`.
 
 ## Error codes
 
-Refusals arrive as `PilelyError` in the hook's `error`, with a `code` drawn from `SimpleEmailErrorCode`. Match on the code: **`daily_cap_exceeded` and `rate_limited` both answer 429** — one means the app spent its UTC-day allowance (retry tomorrow), the other is a burst window (retry shortly).
+Refusals arrive as `PilelyError` in the hook's `error`, with a `code` drawn from `SimpleEmailErrorCode`. Match on the code, not the status: **`out_of_traffic_credits` and `phone_verification_unavailable` both answer 503** — one means the owner's traffic balance is used up (the owner must top up), the other is transient (retry shortly). `daily_cap_exceeded` (429) means the app spent its UTC-day allowance (retry tomorrow). `rate_limited` (429) means the caller is over a `@simple_limiter` policy the app's owner set on this app's sends; root answers it with a `Retry-After` header (retry after that many seconds). `idempotency_key_reused` (409) means the key already belongs to a different request on this app in the last 24 hours — nothing was sent, use a new key for a different email; `idempotency_key_in_progress` (409) means the first request with that key is still being handed to the provider — retry in a few seconds with the same key.
 
 A send can also answer `phone_verification_required` (403), `phone_verification_unavailable` (503) and `out_of_traffic_credits` (503). Provisioning adds `account_exists`, `account_limit_reached` and `template_limit_reached` (all 409). The rest: `not_found` (404, the uniform hide), `bad_request` (400), `unauthenticated` (401), `bad_forwarded_identity` (401), `internal` (500). An oversize send or template body is refused before any handler runs, so its `code` is `null`.
 
-Limits: billed per recipient, at most 50 recipients per send, 200 sends per app per UTC day.
+Limits: billed per recipient, at most 50 recipients per send (an account send has exactly 1), 200 recipients per app per UTC day by default. `useEmailAccount()`'s `daily_cap` shows the cap in force for this app; for a higher one, open a support ticket on `@customer` naming the app, the cap you want and what the mail is.
 
 ## Install
 

package/dist/api.d.ts

@@ -1,4 +1,4 @@
-import type { Account, AccountCursor, AccountInfoEnvelope, SendCursor, SendRow, Template, TemplateCursor, TemplateMeta } from "./types.js";
+import type { Account, AccountCursor, AccountInfoEnvelope, AccountSenders, SendCursor, SendRow, Template, TemplateCursor, TemplateMeta, ToAccount } from "./types.js";
 /** `to` is capped at the service's `max_recipients_per_send` (50 by default). */
 export type SendContent = {
     template_id: string;
@@ -7,9 +7,47 @@ export type SendContent = {
     subject: string;
     html: string;
 };
-export type SendInput = {
+/**
+ * Optional on every send shape: 1–128 characters of `[A-Za-z0-9._:-]`, held
+ * per app for 24 hours from its first use. A repeat with the same key, the
+ * same body and the same caller answers the first send's `send_id` with
+ * `replayed: true` and sends and bills nothing; the same key with another
+ * body or caller 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 raw send: to the addresses in `to`, template or inline content. */
+export type RawSendInput = {
     to: string[];
-} & SendContent;
+    to_account?: never;
+} & SendContent & SendKey;
+/**
+ * An account send: a template to ONE address the service looks up itself —
+ * the caller's own account email (`"self"`) or the account owner's
+ * (`"owner"`). No `to`, and template content only: `subject` / `html` are a
+ * 400 on the server, so they do not typecheck here.
+ */
+export type AccountSendInput = {
+    to_account: ToAccount;
+    to?: never;
+    template_id: string;
+    variables?: Record<string, string>;
+    subject?: never;
+    html?: never;
+} & SendKey;
+/** Exactly one of `to` (a raw send) or `to_account` (an account send). */
+export type SendInput = RawSendInput | AccountSendInput;
+/** `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`. An account send's answer never carries an address. */
+export interface SendResult {
+    send_id: string;
+    recipient_count: number;
+    replayed: boolean;
+}
 export interface ListSendsOptions {
     limit?: number;
     after_created_time_stamp?: number;
@@ -39,10 +77,7 @@ export interface UpdateTemplateBody {
  * 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;
-}>;
+export declare function send(input: SendInput): Promise<SendResult>;
 /** `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<{
@@ -52,8 +87,10 @@ export declare function listSends(options?: ListSendsOptions): Promise<{
 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>;
+ *  is the opposite: its key is always required. `accountSenders` is
+ *  optional too, and left off the wire when `undefined` (the server then
+ *  uses `"send_group"`; it refuses an explicit `null` with a 400). */
+export declare function createAccount(sendGroup?: string | null, accountSenders?: AccountSenders): 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. */
@@ -68,8 +105,9 @@ 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>;
+ *  means owner-only. `accountSenders` is optional: `undefined` leaves the
+ *  key off the wire, which KEEPS the account's current value. */
+export declare function setAccountAccess(sendGroup: string | null, accountSenders?: AccountSenders): Promise<Account>;
 /** Returns metadata only — no `html`. Use `templateInfo` to read the body
  *  back.
  *

package/dist/api.js

@@ -32,9 +32,13 @@ function requireAppId() {
  * 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 };
+    const app_id = requireAppId();
+    const idempotency_key = input.idempotency_key;
+    const body = input.to_account !== undefined
+        ? { app_id, to_account: input.to_account, template_id: input.template_id, variables: input.variables, idempotency_key }
+        : "template_id" in input
+            ? { app_id, to: input.to, template_id: input.template_id, variables: input.variables, idempotency_key }
+            : { app_id, to: input.to, subject: input.subject, html: input.html, idempotency_key };
     return call({
         service: "simple-email",
         path: "/send",
@@ -65,12 +69,19 @@ export async function listAllSends() {
 // ── 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() };
+ *  is the opposite: its key is always required. `accountSenders` is
+ *  optional too, and left off the wire when `undefined` (the server then
+ *  uses `"send_group"`; it refuses an explicit `null` with a 400). */
+export async function createAccount(sendGroup, accountSenders) {
+    const body = {
+        app_id: requireAppId(),
+    };
     if (sendGroup !== undefined) {
         body.send_group = sendGroup;
     }
+    if (accountSenders !== undefined) {
+        body.account_senders = accountSenders;
+    }
     const json = await call({
         service: "simple-email",
         path: "/accounts/create",
@@ -119,12 +130,17 @@ export async function deleteAccount() {
 }
 /** `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) {
+ *  means owner-only. `accountSenders` is optional: `undefined` leaves the
+ *  key off the wire, which KEEPS the account's current value. */
+export async function setAccountAccess(sendGroup, accountSenders) {
+    const body = { send_group: sendGroup };
+    if (accountSenders !== undefined) {
+        body.account_senders = accountSenders;
+    }
     const json = await call({
         service: "simple-email",
         path: `/accounts/${requireAppId()}/access/set`,
-        body: { send_group: sendGroup },
+        body,
     });
     return json.account;
 }

package/dist/hooks.d.ts

@@ -1,6 +1,6 @@
 import type { UseInfiniteQueryResult, UseMutationResult, UseQueryResult } from "@tanstack/react-query";
-import type { SendInput } from "./api.js";
-import type { Account, AccountInfoEnvelope, SendRow, Template, TemplateMeta } from "./types.js";
+import type { SendInput, SendResult } from "./api.js";
+import type { Account, AccountInfoEnvelope, AccountSenders, SendRow, Template, TemplateMeta } from "./types.js";
 export interface PageOptions {
     /** Rows per page; the server defaults to 50 and caps at 100. */
     limit?: number;
@@ -11,18 +11,30 @@ export interface CreateTemplateInput {
     subject: string;
     html: string;
 }
+/** `useCreateEmailAccount`'s object form. Both keys are optional: an omitted
+ *  `send_group` means owner-only, an omitted `account_senders` means
+ *  `"send_group"`. */
+export interface CreateEmailAccountInput {
+    send_group?: string | null;
+    account_senders?: AccountSenders;
+}
+/** `useSetEmailAccountAccess`'s object form. `send_group` is required (`null`
+ *  = owner-only); an omitted `account_senders` keeps the current value. */
+export interface SetEmailAccountAccessInput {
+    send_group: string | null;
+    account_senders?: AccountSenders;
+}
 /** A full replace of both `subject` and `html`; `name` is not updatable. */
 export interface UpdateTemplateInput {
     templateId: string;
     subject: string;
     html: string;
 }
-/** Sends one email from this app's account. Not optimistic: a send counts
- *  only once the server accepted it. */
-export declare function useSend(): UseMutationResult<{
-    send_id: string;
-    recipient_count: number;
-}, Error, SendInput>;
+/** 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 declare function useSend(): UseMutationResult<SendResult, Error, SendInput>;
 /** This app's outbox, newest first, as an infinite query. */
 export declare function useSends(options?: PageOptions): UseInfiniteQueryResult<SendRow[], Error>;
 /** The caller's email accounts across apps, as an infinite query. */
@@ -31,12 +43,13 @@ export declare function useEmailAccounts(options?: PageOptions): UseInfiniteQuer
  *  and phone verification. */
 export declare function useEmailAccount(): UseQueryResult<AccountInfoEnvelope, Error>;
 /** Creates this app's account; the variable is its optional send group
- *  (`null` or omitted: owner-only). */
-export declare function useCreateEmailAccount(): UseMutationResult<Account, Error, string | null | void>;
+ *  (`null` or omitted: owner-only), or `{ send_group?, account_senders? }`. */
+export declare function useCreateEmailAccount(): UseMutationResult<Account, Error, string | null | void | CreateEmailAccountInput>;
 /** Deletes this app's account and the templates under it. */
 export declare function useDeleteEmailAccount(): UseMutationResult<void, Error, void>;
-/** Replaces this app's send group; `null` means owner-only. */
-export declare function useSetEmailAccountAccess(): UseMutationResult<Account, Error, string | null>;
+/** 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 declare function useSetEmailAccountAccess(): UseMutationResult<Account, Error, string | null | SetEmailAccountAccessInput>;
 /** This app's templates (metadata only), as an infinite query. */
 export declare function useTemplates(options?: PageOptions): UseInfiniteQueryResult<TemplateMeta[], Error>;
 /** One template with its `html`. An `undefined` id disables the query. */

package/dist/hooks.js

@@ -11,8 +11,10 @@ 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. Not optimistic: a send counts
- *  only once the server accepted it. */
+/** 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,
@@ -48,10 +50,12 @@ 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). */
+ *  (`null` or omitted: owner-only), or `{ send_group?, account_senders? }`. */
 export function useCreateEmailAccount() {
     return useServiceMutation("useCreateEmailAccount", {
-        mutationFn: (sendGroup) => createAccount(sendGroup ?? undefined),
+        mutationFn: (input) => typeof input === "object" && input !== null
+            ? createAccount(input.send_group, input.account_senders)
+            : createAccount(input ?? undefined),
         invalidates: () => [accountsKey(), accountKey()],
     });
 }
@@ -62,10 +66,13 @@ export function useDeleteEmailAccount() {
         invalidates: () => [accountsKey(), accountKey(), templatesKey(), serviceQueryKey("simple-email", "template")],
     });
 }
-/** Replaces this app's send group; `null` means owner-only. */
+/** 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: setAccountAccess,
+        mutationFn: (input) => typeof input === "object" && input !== null
+            ? setAccountAccess(input.send_group, input.account_senders)
+            : setAccountAccess(input),
         invalidates: () => [accountsKey(), accountKey()],
     });
 }

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { useCreateEmailAccount, useCreateTemplate, useDeleteEmailAccount, useDeleteTemplate, useEmailAccount, useEmailAccounts, useSend, useSends, useSetEmailAccountAccess, useTemplate, useTemplates, useUpdateTemplate, } from "./hooks.js";
-export type { CreateTemplateInput, PageOptions, UpdateTemplateInput } from "./hooks.js";
-export type { SendContent, SendInput } from "./api.js";
-export type { Account, SimpleEmailErrorCode, AccountCursor, AccountInfoEnvelope, SendCursor, SendRow, Template, TemplateCursor, TemplateMeta, } from "./types.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/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) });
         }

package/dist/types.d.ts

@@ -1,14 +1,34 @@
 /** Every `code` the simple_email service can put in a `{ok:false, code, reason}`
- *  refusal. Exhaustive as of the 2026-09 review, checked against the service's
- *  `response_json.rs` and `render.rs`.
+ *  refusal, including the two `idempotency_key_*` conflicts, checked
+ *  against the service's `response_json.rs` and `render.rs`.
  *
- *  This is the union that most earns its keep: `daily_cap_exceeded` and
- *  `rate_limited` BOTH answer 429, so a consumer cannot tell a burst limit
- *  (retry shortly) from the per-app daily send cap (retry tomorrow) by status
- *  alone — only by matching this code. */
+ *  This is the union that most earns its keep: `out_of_traffic_credits` and
+ *  `phone_verification_unavailable` BOTH answer 503, so a consumer cannot tell
+ *  a used-up owner balance (the owner must top up) from a transient outage
+ *  (retry shortly) by status alone — only by matching this code. */
 export type SimpleEmailErrorCode = "unauthenticated" | "bad_forwarded_identity" | "bad_request" | "not_found" | "account_exists" | "account_limit_reached" | "template_limit_reached"
-/** 429, same status as `rate_limited` — the per-app UTC-day send cap. */
- | "daily_cap_exceeded" | "phone_verification_required" | "phone_verification_unavailable" | "out_of_traffic_credits" | "rate_limited" | "internal";
+/** 409 — this `idempotency_key` already belongs to a different request
+ *  (another body or another caller) on this app in the last 24 hours;
+ *  nothing was sent. Use a new key for a different email. */
+ | "idempotency_key_reused"
+/** 409 — an earlier request with this `idempotency_key` is still being
+ *  handed to the provider; retry in a few seconds. */
+ | "idempotency_key_in_progress"
+/** 429 — the per-app UTC-day send cap. */
+ | "daily_cap_exceeded" | "phone_verification_required" | "phone_verification_unavailable" | "out_of_traffic_credits"
+/** 429 — over a `@simple_limiter` policy the app's owner set on this
+ *  app's sends; root answers it with a `Retry-After` header. */
+ | "rate_limited" | "internal";
+/** Who besides the owner may make account sends (`to_account`):
+ *  `"send_group"` (the default) keeps them to the owner and the send group's
+ *  members; `"app_users"` also lets every signed-in user arriving through the
+ *  account's own app send a template to their own or the owner's account
+ *  email. It never opens raw sends (`to`). */
+export type AccountSenders = "send_group" | "app_users";
+/** The recipient of an account send, resolved by the service: the caller's
+ *  own Pilely account email (`"self"`) or the account owner's (`"owner"`).
+ *  The caller never supplies or sees the address. */
+export type ToAccount = "self" | "owner";
 /** `address` is derived at read time, never stored, and `null` when the
  *  app it names is gone. */
 export interface Account {
@@ -18,6 +38,7 @@ export interface Account {
     /** `null` means owner-only — the opposite polarity from simple_db's
      *  `read_group`/`write_group`, where `null` means everyone. */
     send_group: string | null;
+    account_senders: AccountSenders;
     created_time_stamp: number;
 }
 /** `daily_cap`'s three siblings are nullable and sit BESIDE `account`, not
@@ -50,6 +71,10 @@ export interface TemplateMeta {
 export interface Template extends TemplateMeta {
     html?: string;
 }
+/** One send-log row. An account send's row carries its `to_account`: for
+ *  `"self"`, `recipients` is `[]` and `recipient_count` is `1` — the owner
+ *  never sees a user's account email through this service; for `"owner"`,
+ *  `recipients` holds the owner's own address. */
 export interface SendRow {
     send_id: string;
     requester_user_id: string;
@@ -61,6 +86,10 @@ export interface SendRow {
     recipient_count: number;
     outcome: string;
     outcome_reason: string | null;
+    /** `null` for a raw send. */
+    to_account: ToAccount | null;
+    /** The caller's `idempotency_key`, or `null` when the send had none. */
+    idempotency_key: string | null;
     fired_at: number;
 }
 export interface SendCursor {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilely/simple-email",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "React hooks for the simple_email service.",
   "license": "MIT",
   "type": "module",