@pilely/simple-email 0.3.0 → 0.4.2

package/README.md

@@ -1,98 +1,117 @@
 # `@pilely/simple-email`
 
-A typed client for the `simple_email` service — the platform's managed
-transactional email. Wraps all 12 of its POST routes: sending, account
-provisioning, and templates.
-
-## Install
-
-```sh
-npm install @pilely/simple-email @pilely/core
+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>`.
+
+## Hooks
+
+| Hook | 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[]` |
+| `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, or `{ send_group?, account_senders? }` |
+| `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) |
+| `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 |
+| `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.
+
+## 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 |
+| --- | --- |
+| send | `useSends()` |
+| account create / set access | `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}` });
+}
 ```
 
-Always install with the scope — `pilely-email` and similar unscoped names
-are not owned by this project and are squattable. `@pilely/core` is a peer
-dependency; an app has exactly one facade, never two.
+## Query keys
 
-## Where the app id lives
+| 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` |
+| `["pilely", "simple-email", "template", templateId]` | `useTemplate` |
 
-Unlike the other three service packages, this one splits: `send()` and
-`listSends()` put the app id in the request **body**; every account and
-template method puts it in the request **path**. `listAccounts()` takes no
-app id at all — it lists every account the caller owns. Every method adds
-the id itself from `@pilely/core`'s `appId()`; it is never a parameter you
-pass.
-
-## Templates live under the account
+## Templates can be nameless, and can lose their body
 
-There is no top-level `templates/...` route. Every template call is
-`accounts/{app}/templates/...` — a template belongs to one account, and
-`createTemplate`/`listTemplates`/`templateInfo`/`updateTemplate`/`deleteTemplate`
-all reach it that way.
+`name` is `string | null`: a nameless template is legal. `html` on `useTemplate`'s data is optional, not nullable — when the stored body is missing the service omits the key. Check `"html" in template` before rendering it.
 
 ## Mock mode
 
-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. Every method here then answers from memory with the
-JSON the real service returns.
-
-**Nothing is ever sent.** `send()` appends the message to an in-memory
-outbox — the rows `listSends()` answers — and logs it to the console.
-Accounts and templates are kept in memory and persisted to `localStorage`
-across reloads; an app's account is created on its first send if it does
-not exist yet. 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 on a send is kept, since it is the request's shape.
-
-What it does not: send groups, the daily cap, the phone gate, rate limits
-and credit checks.
+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.
 
-Writes need a signed-in user: a signed-out write answers the uniform bare
-404, which reaches the app as `PilelyError(404, null)`, exactly where the
-real service would hide it. Mock mode is on only in a Vite build with
-`VITE_PILELY_MOCK=1`; see [`@pilely/core`](../core#mock-mode) for the
-switch, `seedMock()` and `resetMock()`.
+**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.
 
-## Status
+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`.
 
-This is a pre-1.0 package and moves with the platform. Nothing here is
-published to the registry yet. Zero runtime dependencies.
-
-## Templates can be nameless, and can lose their body
-
-Two degraded shapes the service keeps deliberately visible, both reflected
-in the types:
-
-- `name` is `string | null`. A nameless template is legal — `createTemplate`
-  takes `string | null` and hands the `null` straight back.
-- `html` is **optional, not nullable**. When the stored object behind a
-  template is missing, `templateInfo` omits the key rather than sending
-  `null`. Discriminate with `"html" in template`, and never assume a body.
+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` with a `code` drawn from
-`SimpleEmailErrorCode`. Here matching on the code is not optional:
+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.
 
-**`daily_cap_exceeded` and `rate_limited` both answer 429.** One means the
-app has spent its UTC-day send allowance (retry tomorrow, or not at all);
-the other is an ordinary burst window (retry shortly). The status cannot
-tell them apart — only the code can.
+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`.
 
-`send` can also answer `phone_verification_required` (403) and
-`phone_verification_unavailable` (503) from the phone gate, and
-`out_of_traffic_credits` (503). Provisioning adds `account_exists`,
-`account_limit_reached` and `template_limit_reached` (all 409). The
-remainder: `not_found` (404, the uniform hide), `bad_request` (400),
-`unauthenticated` (401), `bad_forwarded_identity` (401), `internal` (500).
+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.
 
-A member-role caller sees a uniform 404 where the owner would see a 503
-`out_of_traffic_credits` — worth knowing before debugging a member's send.
+## Install
 
-## Limits worth knowing before you call `send`
+```sh
+npm install @pilely/simple-email @pilely/core @tanstack/react-query
+```
 
-- Billed **per recipient**, not per call.
-- At most 50 recipients per send.
-- 200 sends per app per UTC day — the `daily_cap_exceeded` wall above.
-- `send_id` is the idempotency key.
+`@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.

package/dist/api.d.ts

@@ -0,0 +1,133 @@
+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;
+}
+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<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<{
+    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. `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. */
+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. `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.
+ *
+ *  `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>;

package/dist/api.js

@@ -0,0 +1,208 @@
+// The simple_email service's 12 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.
+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
+// 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 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,
+    });
+}
+/** `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. `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",
+        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. `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,
+    });
+    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`,
+    });
+}

package/dist/hooks.d.ts

@@ -0,0 +1,59 @@
+import type { UseInfiniteQueryResult, UseMutationResult, UseQueryResult } from "@tanstack/react-query";
+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;
+}
+export interface CreateTemplateInput {
+    /** `null` for a nameless template. */
+    name: string | null;
+    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: 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. */
+export declare function useEmailAccounts(options?: PageOptions): UseInfiniteQueryResult<Account[], Error>;
+/** This app's account with its live state: daily cap, sent today, credit
+ *  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), 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); 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. */
+export declare function useTemplate(templateId: string | undefined): UseQueryResult<Template, Error>;
+export declare function useCreateTemplate(): UseMutationResult<TemplateMeta, Error, CreateTemplateInput>;
+export declare function useUpdateTemplate(): UseMutationResult<TemplateMeta, Error, UpdateTemplateInput>;
+export declare function useDeleteTemplate(): UseMutationResult<void, Error, string>;