@pilely/simple-email 0.4.5 → 0.5.0

package/README.md

@@ -1,104 +1,135 @@
 # `@pilely/simple-email`
 
-React hooks for the `simple_email` service — the platform's managed transactional email. A query hook for every read, a mutation hook for every write. Render them inside `@pilely/core`'s `<PilelyProvider>`.
+The client for the `simple_email` service — the platform's managed transactional email. An email account has two ways to send, and this package has one entry for each:
 
-## Hooks
+- **`sendTemplate(templateId, variables)`**, and its hook `useSendTemplate()`, for a **page** of the app: the **template send**. It sends one of the account's templates, filled from the variables, to the ONE address the owner stored on that template. The caller supplies only the variables, so it can never point the mail at anyone else or change what it says. Any caller the template's groups admit can make it — signed-out visitors included.
+- **`send({ to, ... })`** for the app's **backend only**: the **freestyle send**, to any addresses, from a template or inline. Only the account's app's own backend, calling with its backend token, is admitted; a page, a signed-in user and you, the owner, get the uniform 404. It needs no browser runtime: a server imports it from `@pilely/simple-email/send`.
 
-| Hook | Wraps | Kind |
+Beside them, a query hook for every read and a mutation hook for every write of the account and its templates, for owner tooling. Render the hooks inside `@pilely/core`'s `<PilelyProvider>`.
+
+**Moving from `0.4.x`:** `0.5.0` removes `useSend()`, `useSends()` and `useSetEmailAccountAccess()` — the service no longer has the routes they call, so a `0.4.x` client's sends and outbox fail — and accounts carry no send access of their own any more: who may send is each template's groups, and your app's backend. Templates gain `recipient`, `send_group` and `deny_group`. `create-pilely-app` `0.4.3` still scaffolds `"@pilely/simple-email": "^0.4.0"`, whose `useSend` / `useSends` call those removed routes: in a scaffolded app, move the range to `^0.5.0`.
+
+## Hooks and functions
+
+| Export | Wraps | Kind |
 | --- | --- | --- |
-| `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[]` |
+| `useSendTemplate()` | `accounts/{app}/templates/{t}/send` | mutation, `{ templateId, variables? }`; answers `{ send_id }`, never the address |
+| `sendTemplate(templateId, variables?, { challenge }?)` | `accounts/{app}/templates/{t}/send` | the same template send as a plain function |
+| `send(input, { appId, backendToken, origin? })` | `accounts/{app}/send` | the freestyle send, backend only; `input` is `{ to, subject, html }` or `{ to, template_id, variables? }`, each with an optional `idempotency_key`. Answers `{ send_id, recipient_count, replayed }` |
 | `useEmailAccount()` | `accounts/{app}/info` | query; this app's account with its daily cap, sent today and credit state |
 | `useEmailAccounts({ limit? })` | `accounts/list`, paged | infinite query; every account the caller owns |
-| `useCreateEmailAccount()` | `accounts/create` | mutation, the optional send group, or `{ send_group?, account_senders?, reply_to? }` |
+| `useCreateEmailAccount()` | `accounts/create` | mutation, no variables, or `{ reply_to? }` |
 | `useDeleteEmailAccount()` | `accounts/{app}/delete` | mutation, no variables |
-| `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) |
 | `useSetEmailReplyTo()` | `accounts/{app}/set_reply_to` | mutation, the reply-to address, or `null` to clear it; always sent, never "keep" |
 | `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`) |
-| `useUpdateTemplate()` | `templates/{t}/update` | mutation, `{ templateId, subject, html }` — a full replace |
+| `useCreateTemplate()` | `templates/create` | mutation, `{ name, subject, html, recipient, send_group?, deny_group? }` (`name` may be `null`; `recipient` is required) |
+| `useUpdateTemplate()` | `templates/{t}/update` | mutation, `{ templateId, subject, html, recipient?, send_group?, deny_group? }` — `subject` and `html` a full replace; an omitted `recipient` or group keeps the stored value, `null` empties a group |
 | `useDeleteTemplate()` | `templates/{t}/delete` | mutation, the template id |
 
-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.
+On a page the app id is added from `@pilely/core` on every route; it is never a variable. `send()` runs where there is no page, so it takes the app id and the backend token explicitly. Every write waits for the server: an email "sent" before the server accepted it would be a lie.
 
-## Bot checks: `{ challenge }`
+Every template answer (`TemplateMeta`, `Template`) carries `recipient` (the stored address), `send_group` and `deny_group` (group ids, or `null` for an empty group). An `Account` carries `app_id`, `address`, `display_name`, `reply_to` and `created_time_stamp`.
 
-The app's owner can put a **challenge policy** on any route of `simple-email.pilely.app` for the app, typically `POST /send` (`https://simple-limiter.pilely.app/README.md`); root then refuses every send through the app that carries no solved bot check with `403 challenge_required`, before the service sees it — the owner's and the app's server's sends included. Every hook takes a `challenge` option for that, in its options object or as its last argument where it has none (`useSend({ challenge })`, `useTemplate(templateId, { challenge })`):
+## The template send, from a page
 
 ```tsx
-import { getChallenge, solveChallenge } from "@pilely/simple-limiter";
+import { useSendTemplate } from "@pilely/simple-email";
 
-const send = useSend({ challenge: async () => solveChallenge(await getChallenge()) });
-await send.mutateAsync({ to_account: "owner", template_id, variables }); // a fresh answer per send
+// CONTACT is a template of this app's account whose recipient is your own
+// address and whose send_group admits the people who use this form.
+export function ContactForm() {
+  const sendTemplate = useSendTemplate();
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        const form = new FormData(e.currentTarget);
+        sendTemplate.mutate({
+          templateId: CONTACT,
+          variables: { name: String(form.get("name")), message: String(form.get("message")) },
+        });
+      }}
+    >
+      <input name="name" />
+      <textarea name="message" />
+      <button disabled={sendTemplate.isPending}>Send</button>
+      {sendTemplate.isSuccess && <p>Thanks — your message was sent.</p>}
+      {sendTemplate.error && <p role="alert">{sendTemplate.error.message}</p>}
+    </form>
+  );
+}
 ```
 
-A string, or a function answering one (it may be async, and may answer `undefined`) asked once for each request the hook sends; every request carries it as the `X-Pilely-Challenge` header, and root uses it up only on a call a policy matches. One answer works for one call, within 5 minutes of `getChallenge()`, so give a function to a hook that sends more than once. A refusal is a `PilelyError` with `challenge_required` or `challenge_failed` (both 403) and is never retried; get and solve a new one to start over.
+`variables` holds one string per `{{placeholder}}` of the template's subject and html, and it is the whole request body: every other field the service ignores, so a caller can never add a `to`, a `subject` or an `html`. A missing (or non-string) variable is `bad_request` (400) and nothing is sent. The answer is `{ send_id }`; no answer of this route, success or error, carries the stored address. A template send counts 1 recipient toward the app's daily send cap.
 
-## Raw sends and account sends
+**Who may send it is the template's two groups.** Through the app's own page, a caller is admitted exactly when it is a member of the template's `send_group` and not a member of its `deny_group`. A refused caller, an unknown template and an exhausted owner balance all get the same `not_found` (404). An empty `send_group` admits nobody: a template cannot be sent this way until you set one.
 
-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.
+**Setting up the groups** with `@pilely/simple-group` (`https://simple-group.pilely.app/README.md`), then storing the ids on the template with `useCreateTemplate()` or `useUpdateTemplate()`:
 
-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.
+- every signed-out visitor of a public app: `send_group` = the platform-wide anonymous group, from `anonymousGroupId()`;
+- every signed-in user: `send_group` = the platform-wide authenticated group, from `authenticatedGroupId()`;
+- chosen people, or your app's backend: an owner group of your own (`useCreateGroup()`), with them added as members;
+- people to refuse: an owner group of your own as the `deny_group` (a platform-wide group is never a `deny_group`).
 
-## Replies: `reply_to`
+**Cap how often callers send it with a `@simple_limiter` policy** (`https://simple-limiter.pilely.app/README.md` → `### Limiting simple_email sends`): `host` `simple-email.pilely.app`, your app's id, `POST`, path `/accounts/<app id>/templates/*/send` (or one template's id in place of `*`), keyed by `ip` for signed-out visitors or `user` for signed-in users — for example a few sends per hour. Over it, root answers `rate_limited` (429) with a `Retry-After`. The service sets no per-caller limit of its own: without a policy, one caller can use up the app's daily cap and spend your balance. A template open to visitors is a form anyone can submit.
+
+**You pay for every send.** Every send, template or freestyle, whoever caused it — a visitor, a signed-in user, your backend — is billed to the account's owner, never to the caller.
 
-An account's `reply_to` is the address recipients' replies go to: every send from the account — raw, template and account sends — carries it as its `Reply-To`. `null` (the default) means none, and replies go nowhere. Set it on create (`useCreateEmailAccount()`'s `{ reply_to }`) or later with `useSetEmailReplyTo()`, which takes the address or `null` to clear it. It must be one bare address (no display name, no list) and not on `pilely-app-email.com`, `pilely.ai` or `pilely.app` nor a subdomain of one; the server answers anything else `bad_request` (400) with a reason naming the rule. Every `Account` carries it.
+## The freestyle send, from your backend
 
-## Retries: `idempotency_key`
+```ts
+import { send } from "@pilely/simple-email/send";
 
-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`.
+await send(
+  { to: [row.email], template_id: WELCOME, variables: { name: row.name }, idempotency_key: `welcome:${row.id}` },
+  { appId: APP_ID, backendToken: process.env.PILELY_BACKEND_TOKEN! },
+);
+```
+
+`send()` is for a server that holds the app's backend token — **never call it from a page**: a page has no backend token, and the service answers every caller but the app's own backend with the uniform 404. It imports nothing at runtime (no `@pilely/core`, no React, no `window.pilely`) and makes one plain `fetch` to `https://simple-email.pilely.app/accounts/<appId>/send` with the token as `Authorization: Bearer`; pass `origin` for another host. It is also exported from the main entry. A `@simple_server` box runs Rust, not JavaScript: there, make the same `POST` with your HTTP client (`https://simple-email.pilely.app/README.md` → `### POST /accounts/{app_id}/send`).
+
+`to` holds 1 to 50 addresses; the content is a template (`template_id`, with `variables` matching its placeholders exactly) or inline (`subject` + `html`), never both. A refusal throws `SendError` with `status`, `code` (a `SimpleEmailErrorCode`, or `null` for a bodiless answer) and `reason`; it never carries the token.
+
+Who may cause a freestyle send is your backend's own code — no group is involved. So is how often it sends: no `@simple_limiter` policy counts your app's backend, and the service's only bound is the freestyle cap, 500 recipients per app per UTC day (`daily_cap_exceeded`, 429), counted apart from the daily send cap. Before mailing an address a visitor typed, send at most one fixed-template confirmation with an `idempotency_key` tied to that address's row.
+
+### Retries: `idempotency_key`
+
+Give a freestyle 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 and the same body answers the FIRST send's `send_id` with `replayed: true` — nothing is sent, billed or counted again. The same key with another body 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`. The template send takes no key: every accepted call is a new email.
+
+## Bot checks: `{ challenge }`
+
+The app's owner can put a **challenge policy** on any route of `simple-email.pilely.app` for the app, typically the template send's path `/accounts/<app id>/templates/*/send` (`https://simple-limiter.pilely.app/README.md`) — never the freestyle send's `/accounts/<app id>/send`, whose backend caller cannot solve one, so such a policy would refuse every backend send; root then refuses every matching call through the app that carries no solved bot check with `403 challenge_required`, before the service sees it. Every hook and `sendTemplate` take a `challenge` option for that, in its options object or as its last argument where it has none (`useSendTemplate({ challenge })`, `useTemplate(templateId, { challenge })`):
+
+```tsx
+import { getChallenge, solveChallenge } from "@pilely/simple-limiter";
+
+const sendTemplate = useSendTemplate({ challenge: async () => solveChallenge(await getChallenge()) });
+await sendTemplate.mutateAsync({ templateId, variables }); // a fresh answer per send
+```
+
+A string, or a function answering one (it may be async, and may answer `undefined`) asked once for each request the hook sends; every request carries it as the `X-Pilely-Challenge` header, and root uses it up only on a call a policy matches. One answer works for one call, within 5 minutes of `getChallenge()`, so give a function to a hook that sends more than once. A refusal is a `PilelyError` with `challenge_required` or `challenge_failed` (both 403) and is never retried; get and solve a new one to start over. `send()` takes no `challenge`: a challenge is solved in a browser.
+
+## Replies: `reply_to`
+
+An account's `reply_to` is the address recipients' replies go to: every send from the account — template and freestyle — carries it as its `Reply-To`. `null` (the default) means none, and replies go nowhere. Set it on create (`useCreateEmailAccount()`'s `{ reply_to }`) or later with `useSetEmailReplyTo()`, which takes the address or `null` to clear it. It must be one bare address (no display name, no list) and not on `pilely-app-email.com`, `pilely.ai` or `pilely.app` nor a subdomain of one; the server answers anything else `bad_request` (400) with a reason naming the rule. Every `Account` carries it.
 
 ## What each write refreshes
 
 | Write | Invalidates |
 | --- | --- |
-| send | `useSends()` |
-| account create / set access / set reply-to | `useEmailAccounts()`, `useEmailAccount()` |
+| template send | `useEmailAccount()` (its `sent_today`) |
+| account create / set reply-to | `useEmailAccounts()`, `useEmailAccount()` |
 | account delete | `useEmailAccounts()`, `useEmailAccount()`, and the templates under it |
 | template create | `useTemplates()` |
 | template update / delete on `t` | `useTemplates()`, `useTemplate(t)` |
 
-## Example
-
-```tsx
-import { useSend, useSends } from "@pilely/simple-email";
-
-export function Outbox() {
-  const { data: sends } = useSends();
-  const send = useSend();
-  return (
-    <>
-      <button onClick={() => send.mutate({ to: ["friend@example.com"], subject: "Hi", html: "<p>Hello</p>" })}>
-        Send
-      </button>
-      {send.error && <p role="alert">{send.error.message}</p>}
-      <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}` });
-}
-```
+`send()` is not a hook and touches no cache.
 
 ## Query keys
 
 | Key | Query |
 | --- | --- |
-| `["pilely", "simple-email", "sends", { limit }]` | `useSends` |
 | `["pilely", "simple-email", "account"]` | `useEmailAccount` |
 | `["pilely", "simple-email", "accounts", { limit }]` | `useEmailAccounts` |
 | `["pilely", "simple-email", "templates", { limit }]` | `useTemplates` |
@@ -112,21 +143,25 @@ export function useConfirmSubmission(templateId: string) {
 
 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.
+**Nothing is ever sent.** A template send is appended to an in-memory outbox, addressed to the template's stored recipient, and logged to the console; its answer is `{ send_id }`, never the address. `useEmailAccount()`'s `sent_today` counts those sends. Accounts and templates persist to `localStorage` across reloads. A missing account or template answers the bare 404, and a second account for the same app answers `account_exists` (409).
+
+The template send admits callers by the template's groups as the `@pilely/simple-db` fake admits by policies: the two platform-wide groups hold callers by type — every signed-out visitor is in the anonymous group, every signed-in person in the authenticated group — under the same fixed test ids `@pilely/simple-group`'s fake answers from `anonymousGroupId()` / `authenticatedGroupId()`. 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 — test those against the real service. An empty `send_group` admits nobody. Each placeholder is read from the variables; a missing or non-string one is `bad_request`, and every other field is ignored.
+
+The freestyle route answers the bare 404 to every caller, since no caller in a browser is the app's backend. `send()` never reaches the fake: it is a server function that calls `fetch` directly.
 
-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, and `reply_to`, settable on create and set_reply_to (a missing key or a non-string value on set_reply_to is `bad_request`; the address rules and refused domains are not checked). It does not model send groups, `account_senders` gating, the daily cap, rate limits, credit checks or `idempotency_key_in_progress`.
+Templates carry `recipient` (required on create; `null` on update is `bad_request`), `send_group` and `deny_group` (a platform-wide group as `deny_group` is `bad_request`); accounts carry `reply_to`, settable on create and set_reply_to (a missing key or a non-string value on set_reply_to is `bad_request`). 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.
 
-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()`.
+Owner 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, not the status: **`daily_cap_exceeded` and `rate_limited` both answer 429**. `daily_cap_exceeded` means the app spent its UTC-day allowance (retry tomorrow). `rate_limited` 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.
+Refusals arrive as `PilelyError` in the hook's `error` (as `SendError` from `send()`), with a `code` drawn from `SimpleEmailErrorCode`. Match on the code, not the status: **`daily_cap_exceeded` and `rate_limited` both answer 429**. `daily_cap_exceeded` means the app spent a UTC-day allowance (retry tomorrow): the daily send cap on a template send, the 500-recipient freestyle cap on `send()`. `rate_limited` means the caller is over a `@simple_limiter` policy the app's owner set on the template send; 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 `out_of_traffic_credits` (503): the owner's traffic balance is used up, and the owner must top up. 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).
+Both send routes answer an exhausted owner balance with the uniform `not_found` (404), so billing state never leaks to a caller; the owner routes answer it `out_of_traffic_credits` (503) — top up. 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).
 
 A route the app's owner put a challenge policy on (`## Bot checks: { challenge }`) answers two more, from root before the service: `challenge_required` (403, the call carried no `challenge`; nothing was sent) and `challenge_failed` (403, the `challenge` was malformed, wrong, expired, started through another app, or already used — get and solve a new one). 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 (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.
+Limits: billed per recipient. A template send has exactly 1 recipient and counts toward the daily send cap, 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. A freestyle send has 1 to 50 recipients and counts toward the freestyle cap, 500 recipients per app per UTC day, never the daily send cap.
 
 ## Install
 
@@ -134,4 +169,4 @@ Limits: billed per recipient, at most 50 recipients per send (an account send ha
 npm install @pilely/simple-email @pilely/core @tanstack/react-query
 ```
 
-`@pilely/core`, `react` (`^18.3 || ^19`) and `@tanstack/react-query` (`^5`) are peer dependencies. Always install with the scope — unscoped names like `pilely-email` are not owned by this project. This is a pre-1.0 package and moves with the platform.
+`@pilely/core`, `react` (`^18.3 || ^19`) and `@tanstack/react-query` (`^5`) are peer dependencies of the main entry; the `@pilely/simple-email/send` subpath loads none of them. Always install with the scope — unscoped names like `pilely-email` are not owned by this project. This is a pre-1.0 package and moves with the platform.

package/dist/api.d.ts

@@ -1,59 +1,5 @@
 import type { ChallengeOption } from "@pilely/core";
-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;
-    variables?: Record<string, string>;
-} | {
-    subject: string;
-    html: string;
-};
-/**
- * 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[];
-    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;
-    after_send_id?: string;
-}
+import type { Account, AccountCursor, AccountInfoEnvelope, Template, TemplateCursor, TemplateMeta } from "./types.js";
 export interface ListAccountsOptions {
     limit?: number;
     after_created_time_stamp?: number;
@@ -64,36 +10,54 @@ export interface ListTemplatesOptions {
     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. */
+/** The template send's answer. Never the template's recipient. */
+export interface TemplateSendResult {
+    send_id: string;
+}
+/** `recipient` is REQUIRED: the ONE address every template send of this
+ *  template goes to — any address the owner likes, never verified. The two
+ *  groups are optional; omitted or `null` is an empty group. `send_group`
+ *  takes an owner group or one of the two platform-wide groups (anonymous,
+ *  authenticated — `@pilely/simple-group`'s `anonymousGroupId()` /
+ *  `authenticatedGroupId()`); `deny_group` takes an owner group only. */
+export interface CreateTemplateBody {
+    /** `null` for a nameless template. */
+    name: string | null;
+    subject: string;
+    html: string;
+    recipient: string;
+    send_group?: string | null;
+    deny_group?: string | null;
+}
+/** `subject` and `html` are REQUIRED — the server rejects either one missing
+ *  with a 400: the content is always a full replace. The other three are
+ *  optional: an omitted key keeps the stored value, `null` empties a group,
+ *  and `recipient` cannot be emptied (`null` is a 400, so it does not
+ *  typecheck). */
 export interface UpdateTemplateBody {
     subject: string;
     html: string;
+    recipient?: string;
+    send_group?: string | null;
+    deny_group?: string | null;
 }
 /**
- * `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`.
+ * The template send: `POST /accounts/{app_id}/templates/{template_id}/send`
+ * with the page's own app id. Sends that template, filled from `variables`,
+ * to the one recipient the owner stored on it — the caller can never point
+ * it anywhere else. `variables` is the body itself: each placeholder of the
+ * template's subject and html is read from the field of the same name, and
+ * every other field is ignored. A missing placeholder is a 400 and nothing
+ * is sent. The service admits the caller only when it is in the template's
+ * `send_group` and not in its `deny_group`; everyone else, an unknown
+ * template and an exhausted owner balance alike, gets the uniform 404.
  */
-export declare function send(input: SendInput, { challenge }?: ChallengeOption): 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, { challenge }?: ChallengeOption): Promise<{
-    sends: SendRow[];
-    next_cursor: SendCursor | null;
-}>;
-export declare function listAllSends(request?: ChallengeOption): 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. `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).
- *  `replyTo` is optional as well: `undefined` leaves the key off the wire,
- *  and omitted or `null` both mean no reply-to. */
-export declare function createAccount(sendGroup?: string | null, accountSenders?: AccountSenders, replyTo?: string | null, { challenge }?: ChallengeOption): Promise<Account>;
+export declare function sendTemplate(templateId: string, variables?: Record<string, string>, { challenge }?: ChallengeOption): Promise<TemplateSendResult>;
+/** `replyTo` is optional: `undefined` leaves the key off the wire, and
+ *  omitted or `null` both mean no reply-to. The account carries no send
+ *  access of its own — who may send is each template's groups, and the
+ *  app's backend. */
+export declare function createAccount(replyTo?: string | null, { challenge }?: ChallengeOption): 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. */
@@ -106,11 +70,6 @@ export declare function listAllAccounts(request?: ChallengeOption): Promise<Acco
  *  fields are nullable siblings of `account`, not nested inside it. */
 export declare function accountInfo({ challenge }?: ChallengeOption): Promise<AccountInfoEnvelope>;
 export declare function deleteAccount({ challenge }?: ChallengeOption): 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. `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, { challenge }?: ChallengeOption): Promise<Account>;
 /** `replyTo` is REQUIRED and its key is always sent, even `null` — the
  *  server refuses a missing key with a 400, so a typo can never silently
  *  clear it. An address sets where recipients' replies go (every send from
@@ -119,10 +78,10 @@ export declare function setReplyTo(replyTo: string | null, { challenge }?: Chall
 /** 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, { challenge }?: ChallengeOption): Promise<TemplateMeta>;
+ *  `name` is nullable because the service accepts a nameless template: pass
+ *  an explicit `null`, and `TemplateMeta.name` comes back `null`. An
+ *  omitted group is left off the wire (an empty group). */
+export declare function createTemplate(body: CreateTemplateBody, { challenge }?: ChallengeOption): Promise<TemplateMeta>;
 /** The paged primitive; use `listAllTemplates` to walk to the end. Rows
  *  carry metadata only — no `html`. */
 export declare function listTemplates(options?: ListTemplatesOptions, { challenge }?: ChallengeOption): Promise<{
@@ -133,9 +92,11 @@ export declare function listAllTemplates(request?: ChallengeOption): Promise<Tem
 /** The only template route whose answer carries `html`. */
 export declare function templateInfo(templateNanoid: string, { challenge }?: ChallengeOption): 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`.
+ * A FULL REPLACE of both `subject` and `html`; `recipient`, `send_group` and
+ * `deny_group` change only when their key is sent. `name` is not updatable
+ * at all. Returns metadata only, like `createTemplate`. An oversize body is
+ * rejected by the server before any handler runs, so the thrown
+ * `PilelyError` carries a null `code`.
  */
 export declare function updateTemplate(templateNanoid: string, body: UpdateTemplateBody, { challenge }?: ChallengeOption): Promise<TemplateMeta>;
 export declare function deleteTemplate(templateNanoid: string, { challenge }?: ChallengeOption): Promise<void>;

package/dist/api.js

@@ -1,9 +1,12 @@
-// The simple_email service's 13 POST routes, one function each. This is the
-// internal layer the hooks in hooks.ts call; the package exports the hooks,
-// not these. app_id moves between the body and the path from route to
-// route on this service. Every function takes `{ challenge }` — a bot-check
-// answer, or a function asked once per request — and every request it sends
-// carries it.
+// The simple_email service's page-side POST routes, one function each: the
+// template send and the owner's account and template management. This is
+// the layer the hooks in hooks.ts call; the package exports the hooks and
+// `sendTemplate`, not the rest. app_id is in the path on every route but
+// `accounts/create` (body) and `accounts/list` (none). Every function takes
+// `{ challenge }` — a bot-check answer, or a function asked once per
+// request — and every request it sends carries it. The freestyle send is
+// not here: only an app's backend may make it, so it lives in send.ts,
+// which needs no browser runtime.
 import { appId, call, collectPages, isMockMode, registerMockService } from "@pilely/core";
 import { createSimpleEmailFake } from "./mock.js";
 // Importing this package (its hooks import this module) is all an app does
@@ -27,67 +30,32 @@ function requireAppId() {
 }
 // ── 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`.
+ * The template send: `POST /accounts/{app_id}/templates/{template_id}/send`
+ * with the page's own app id. Sends that template, filled from `variables`,
+ * to the one recipient the owner stored on it — the caller can never point
+ * it anywhere else. `variables` is the body itself: each placeholder of the
+ * template's subject and html is read from the field of the same name, and
+ * every other field is ignored. A missing placeholder is a 400 and nothing
+ * is sent. The service admits the caller only when it is in the template's
+ * `send_group` and not in its `deny_group`; everyone else, an unknown
+ * template and an exhausted owner balance alike, gets the uniform 404.
  */
-export async function send(input, { challenge } = {}) {
-    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",
-        body,
-        challenge,
-    });
-}
-/** `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 = {}, { challenge } = {}) {
+export async function sendTemplate(templateId, variables = {}, { challenge } = {}) {
     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,
-        },
+        path: `/accounts/${requireAppId()}/templates/${templateId}/send`,
+        body: variables,
         challenge,
     });
-    return { sends: json.sends, next_cursor: json.next_cursor };
-}
-export async function listAllSends(request = {}) {
-    return collectPages(async (cursor) => {
-        const page = await listSends({ limit: 100, ...(cursor ?? {}) }, request);
-        return { rows: page.sends, nextCursor: page.next_cursor };
-    });
+    return { send_id: json.send_id };
 }
 // ── 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. `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).
- *  `replyTo` is optional as well: `undefined` leaves the key off the wire,
- *  and omitted or `null` both mean no reply-to. */
-export async function createAccount(sendGroup, accountSenders, replyTo, { challenge } = {}) {
-    const body = {
-        app_id: requireAppId(),
-    };
-    if (sendGroup !== undefined) {
-        body.send_group = sendGroup;
-    }
-    if (accountSenders !== undefined) {
-        body.account_senders = accountSenders;
-    }
+/** `replyTo` is optional: `undefined` leaves the key off the wire, and
+ *  omitted or `null` both mean no reply-to. The account carries no send
+ *  access of its own — who may send is each template's groups, and the
+ *  app's backend. */
+export async function createAccount(replyTo, { challenge } = {}) {
+    const body = { app_id: requireAppId() };
     if (replyTo !== undefined) {
         body.reply_to = replyTo;
     }
@@ -139,23 +107,6 @@ export async function accountInfo({ challenge } = {}) {
 export async function deleteAccount({ challenge } = {}) {
     await call({ service: "simple-email", path: `/accounts/${requireAppId()}/delete`, challenge });
 }
-/** `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. `accountSenders` is optional: `undefined` leaves the
- *  key off the wire, which KEEPS the account's current value. */
-export async function setAccountAccess(sendGroup, accountSenders, { challenge } = {}) {
-    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,
-        challenge,
-    });
-    return json.account;
-}
 /** `replyTo` is REQUIRED and its key is always sent, even `null` — the
  *  server refuses a missing key with a 400, so a typo can never silently
  *  clear it. An address sets where recipients' replies go (every send from
@@ -173,14 +124,14 @@ export async function setReplyTo(replyTo, { challenge } = {}) {
 /** 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, { challenge } = {}) {
+ *  `name` is nullable because the service accepts a nameless template: pass
+ *  an explicit `null`, and `TemplateMeta.name` comes back `null`. An
+ *  omitted group is left off the wire (an empty group). */
+export async function createTemplate(body, { challenge } = {}) {
     const json = await call({
         service: "simple-email",
         path: `/accounts/${requireAppId()}/templates/create`,
-        body: { name, subject, html },
+        body,
         challenge,
     });
     return json.template;
@@ -216,9 +167,11 @@ export async function templateInfo(templateNanoid, { challenge } = {}) {
     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`.
+ * A FULL REPLACE of both `subject` and `html`; `recipient`, `send_group` and
+ * `deny_group` change only when their key is sent. `name` is not updatable
+ * at all. Returns metadata only, like `createTemplate`. An oversize body is
+ * rejected by the server before any handler runs, so the thrown
+ * `PilelyError` carries a null `code`.
  */
 export async function updateTemplate(templateNanoid, body, { challenge } = {}) {
     const json = await call({