@pilely/simple-email 0.2.1 → 0.4.0

package/README.md

@@ -1,74 +1,90 @@
 # `@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? }` |
+| `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 |
+| `useDeleteEmailAccount()` | `accounts/{app}/delete` | mutation, no variables |
+| `useSetEmailAccountAccess()` | `accounts/{app}/access/set` | mutation, the send group (`null` = owner-only) |
+| `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.
+
+## 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}</li>)}</ul>
+    </>
+  );
+}
 ```
 
-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.
-
-## Where the app id lives
-
-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.
+## Query keys
 
-## Templates live under the account
+| 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` |
 
-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.
+## Templates can be nameless, and can lose their body
 
-## Status
+`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.
 
-This is a pre-1.0 package and moves with the platform. Nothing here is
-published to the registry yet. Zero runtime dependencies.
+## Mock mode
 
-## Templates can be nameless, and can lose their body
+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.
 
-Two degraded shapes the service keeps deliberately visible, both reflected
-in the types:
+**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.
 
-- `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: **`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).
 
-**`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, 200 sends per app per UTC day.
 
-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,95 @@
+import type { Account, AccountCursor, AccountInfoEnvelope, SendCursor, SendRow, Template, TemplateCursor, TemplateMeta } from "./types.js";
+/** `to` is capped at the service's `max_recipients_per_send` (50 by default). */
+export type SendContent = {
+    template_id: string;
+    variables?: Record<string, string>;
+} | {
+    subject: string;
+    html: string;
+};
+export type SendInput = {
+    to: string[];
+} & SendContent;
+export interface ListSendsOptions {
+    limit?: number;
+    after_created_time_stamp?: number;
+    after_send_id?: string;
+}
+export interface ListAccountsOptions {
+    limit?: number;
+    after_created_time_stamp?: number;
+    after_app_id?: string;
+}
+export interface ListTemplatesOptions {
+    limit?: number;
+    after_created_time_stamp?: number;
+    after_template_id?: string;
+}
+/** Both keys are REQUIRED — the server rejects either one missing with a
+ *  400 (`ContentField::validate`), matching `updateTemplate`'s full-replace
+ *  contract: there is no patch form on this route. */
+export interface UpdateTemplateBody {
+    subject: string;
+    html: string;
+}
+/**
+ * `app_id` is added from core's `appId()` — it is not a caller parameter.
+ * Body size is capped on this route (like `createTemplate`/`updateTemplate`):
+ * an oversize body is rejected by the server before any handler runs, so
+ * the failure is not an `{ok:false}` envelope and the thrown `PilelyError`
+ * carries a null `code`.
+ */
+export declare function send(input: SendInput): Promise<{
+    send_id: string;
+    recipient_count: number;
+}>;
+/** `app_id` lives in the body here, like `send` — not in the path. The
+ *  paged primitive; use `listAllSends` to walk to the end. */
+export declare function listSends(options?: ListSendsOptions): Promise<{
+    sends: SendRow[];
+    next_cursor: SendCursor | null;
+}>;
+export declare function listAllSends(): Promise<SendRow[]>;
+/** `sendGroup` is optional here — omit it (or pass `undefined`) and the
+ *  key is left off the wire, meaning owner-only. `setAccountAccess` below
+ *  is the opposite: its key is always required. */
+export declare function createAccount(sendGroup?: string | null): Promise<Account>;
+/** No `app_id` anywhere on this route — `after_app_id` is a cursor field,
+ *  not a selector. The paged primitive; use `listAllAccounts` to walk to
+ *  the end. */
+export declare function listAccounts(options?: ListAccountsOptions): Promise<{
+    accounts: Account[];
+    next_cursor: AccountCursor | null;
+}>;
+export declare function listAllAccounts(): Promise<Account[]>;
+/** Returns the account plus its live operational state — the four extra
+ *  fields are nullable siblings of `account`, not nested inside it. */
+export declare function accountInfo(): Promise<AccountInfoEnvelope>;
+export declare function deleteAccount(): Promise<void>;
+/** `sendGroup` is REQUIRED here and its key is always sent, even `null` —
+ *  the opposite of `createAccount`, where the key is optional. `null`
+ *  means owner-only. */
+export declare function setAccountAccess(sendGroup: string | null): Promise<Account>;
+/** Returns metadata only — no `html`. Use `templateInfo` to read the body
+ *  back.
+ *
+ *  `name` is nullable because the service accepts a nameless template. It
+ *  stays a required POSITIONAL parameter — pass an explicit `null`, not
+ *  nothing — and `TemplateMeta.name` then comes back `null`. */
+export declare function createTemplate(name: string | null, subject: string, html: string): Promise<TemplateMeta>;
+/** The paged primitive; use `listAllTemplates` to walk to the end. Rows
+ *  carry metadata only — no `html`. */
+export declare function listTemplates(options?: ListTemplatesOptions): Promise<{
+    templates: TemplateMeta[];
+    next_cursor: TemplateCursor | null;
+}>;
+export declare function listAllTemplates(): Promise<TemplateMeta[]>;
+/** The only template route whose answer carries `html`. */
+export declare function templateInfo(templateNanoid: string): Promise<Template>;
+/**
+ * A FULL REPLACE of both `subject` and `html` — never a patch — and `name`
+ * is not updatable at all. Returns metadata only, like `createTemplate`.
+ * Subject to the same oversize-body caveat as `send`/`createTemplate`.
+ */
+export declare function updateTemplate(templateNanoid: string, body: UpdateTemplateBody): Promise<TemplateMeta>;
+export declare function deleteTemplate(templateNanoid: string): Promise<void>;

package/dist/api.js

@@ -0,0 +1,192 @@
+// 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 body = "template_id" in input
+        ? { app_id: requireAppId(), to: input.to, template_id: input.template_id, variables: input.variables }
+        : { app_id: requireAppId(), to: input.to, subject: input.subject, html: input.html };
+    return call({
+        service: "simple-email",
+        path: "/send",
+        body,
+    });
+}
+/** `app_id` lives in the body here, like `send` — not in the path. The
+ *  paged primitive; use `listAllSends` to walk to the end. */
+export async function listSends(options = {}) {
+    const json = await call({
+        service: "simple-email",
+        path: "/sends/list",
+        body: {
+            app_id: requireAppId(),
+            limit: options.limit,
+            after_created_time_stamp: options.after_created_time_stamp,
+            after_send_id: options.after_send_id,
+        },
+    });
+    return { sends: json.sends, next_cursor: json.next_cursor };
+}
+export async function listAllSends() {
+    return collectPages(async (cursor) => {
+        const page = await listSends({ limit: 100, ...(cursor ?? {}) });
+        return { rows: page.sends, nextCursor: page.next_cursor };
+    });
+}
+// ── Accounts ─────────────────────────────────────────────────────────────
+/** `sendGroup` is optional here — omit it (or pass `undefined`) and the
+ *  key is left off the wire, meaning owner-only. `setAccountAccess` below
+ *  is the opposite: its key is always required. */
+export async function createAccount(sendGroup) {
+    const body = { app_id: requireAppId() };
+    if (sendGroup !== undefined) {
+        body.send_group = sendGroup;
+    }
+    const json = await call({
+        service: "simple-email",
+        path: "/accounts/create",
+        body,
+    });
+    return json.account;
+}
+/** No `app_id` anywhere on this route — `after_app_id` is a cursor field,
+ *  not a selector. The paged primitive; use `listAllAccounts` to walk to
+ *  the end. */
+export async function listAccounts(options = {}) {
+    const json = await call({
+        service: "simple-email",
+        path: "/accounts/list",
+        body: {
+            limit: options.limit,
+            after_created_time_stamp: options.after_created_time_stamp,
+            after_app_id: options.after_app_id,
+        },
+    });
+    return { accounts: json.accounts, next_cursor: json.next_cursor };
+}
+export async function listAllAccounts() {
+    return collectPages(async (cursor) => {
+        const page = await listAccounts({ limit: 100, ...(cursor ?? {}) });
+        return { rows: page.accounts, nextCursor: page.next_cursor };
+    });
+}
+/** Returns the account plus its live operational state — the four extra
+ *  fields are nullable siblings of `account`, not nested inside it. */
+export async function accountInfo() {
+    const json = await call({
+        service: "simple-email",
+        path: `/accounts/${requireAppId()}/info`,
+    });
+    return {
+        account: json.account,
+        daily_cap: json.daily_cap,
+        sent_today: json.sent_today,
+        credit_blocked: json.credit_blocked,
+        phone_verified: json.phone_verified,
+    };
+}
+export async function deleteAccount() {
+    await call({ service: "simple-email", path: `/accounts/${requireAppId()}/delete` });
+}
+/** `sendGroup` is REQUIRED here and its key is always sent, even `null` —
+ *  the opposite of `createAccount`, where the key is optional. `null`
+ *  means owner-only. */
+export async function setAccountAccess(sendGroup) {
+    const json = await call({
+        service: "simple-email",
+        path: `/accounts/${requireAppId()}/access/set`,
+        body: { send_group: sendGroup },
+    });
+    return json.account;
+}
+// ── Templates (nested under the account) ────────────────────────────────
+/** Returns metadata only — no `html`. Use `templateInfo` to read the body
+ *  back.
+ *
+ *  `name` is nullable because the service accepts a nameless template. It
+ *  stays a required POSITIONAL parameter — pass an explicit `null`, not
+ *  nothing — and `TemplateMeta.name` then comes back `null`. */
+export async function createTemplate(name, subject, html) {
+    const json = await call({
+        service: "simple-email",
+        path: `/accounts/${requireAppId()}/templates/create`,
+        body: { name, subject, html },
+    });
+    return json.template;
+}
+/** The paged primitive; use `listAllTemplates` to walk to the end. Rows
+ *  carry metadata only — no `html`. */
+export async function listTemplates(options = {}) {
+    const json = await call({
+        service: "simple-email",
+        path: `/accounts/${requireAppId()}/templates/list`,
+        body: {
+            limit: options.limit,
+            after_created_time_stamp: options.after_created_time_stamp,
+            after_template_id: options.after_template_id,
+        },
+    });
+    return { templates: json.templates, next_cursor: json.next_cursor };
+}
+export async function listAllTemplates() {
+    return collectPages(async (cursor) => {
+        const page = await listTemplates({ limit: 100, ...(cursor ?? {}) });
+        return { rows: page.templates, nextCursor: page.next_cursor };
+    });
+}
+/** The only template route whose answer carries `html`. */
+export async function templateInfo(templateNanoid) {
+    const json = await call({
+        service: "simple-email",
+        path: `/accounts/${requireAppId()}/templates/${templateNanoid}/info`,
+    });
+    return json.template;
+}
+/**
+ * A FULL REPLACE of both `subject` and `html` — never a patch — and `name`
+ * is not updatable at all. Returns metadata only, like `createTemplate`.
+ * Subject to the same oversize-body caveat as `send`/`createTemplate`.
+ */
+export async function updateTemplate(templateNanoid, body) {
+    const json = await call({
+        service: "simple-email",
+        path: `/accounts/${requireAppId()}/templates/${templateNanoid}/update`,
+        body,
+    });
+    return json.template;
+}
+export async function deleteTemplate(templateNanoid) {
+    await call({
+        service: "simple-email",
+        path: `/accounts/${requireAppId()}/templates/${templateNanoid}/delete`,
+    });
+}

package/dist/hooks.d.ts

@@ -0,0 +1,46 @@
+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";
+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;
+}
+/** 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>;
+/** 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). */
+export declare function useCreateEmailAccount(): UseMutationResult<Account, Error, string | null | void>;
+/** 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>;
+/** 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>;

package/dist/hooks.js

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/mock.d.ts

@@ -0,0 +1,2 @@
+import type { MockServiceFactory } from "@pilely/core";
+export declare const createSimpleEmailFake: MockServiceFactory;

package/dist/mock.js

@@ -0,0 +1,289 @@
+// The in-browser fake of the simple_email service that `@pilely/core`'s
+// mock runtime routes to in mock mode. It answers every route this
+// package's wrapper calls with the JSON the real service returns. Nothing
+// is ever sent: `send` appends to an in-memory outbox (the rows `listSends`
+// answers) and logs the message to the console. Accounts and templates
+// live in memory and persist through the core store; an app's account is
+// created on its first send if it does not exist yet. It models shape, not
+// policy: no send groups, daily caps, phone gates or credit checks. 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
+// it.
+const MARKER = "pilely-mock-fake:simple-email";
+const DEFAULT_PAGE_SIZE = 50;
+const MAX_PAGE_SIZE = 100;
+const MAX_RECIPIENTS = 50;
+const DAILY_CAP = 200;
+const SENDING_DOMAIN = "mail.pilely.invalid";
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function compare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+function pageSize(body) {
+    const raw = body.limit === undefined || body.limit === null ? DEFAULT_PAGE_SIZE : Number(body.limit);
+    return Math.min(MAX_PAGE_SIZE, Math.max(1, Number.isFinite(raw) ? Math.trunc(raw) : DEFAULT_PAGE_SIZE));
+}
+function render(text, variables) {
+    return text.replace(/\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g, (whole, name) => name in variables ? String(variables[name]) : whole);
+}
+function accountPayload(account) {
+    return {
+        app_id: account.app_id,
+        address: account.address,
+        display_name: account.display_name,
+        send_group: account.send_group,
+        created_time_stamp: account.created_time_stamp,
+    };
+}
+function templateMeta(template) {
+    return {
+        template_id: template.template_id,
+        name: template.name,
+        subject: template.subject,
+        created_time_stamp: template.created_time_stamp,
+        updated_time_stamp: template.updated_time_stamp,
+    };
+}
+/**
+ * Newest-first keyset paging over rows already sorted, with the cursor
+ * taken from the last row whenever the page is full — the service's rule.
+ */
+function keysetPage(rows, body, keys, key, cursor) {
+    const [msKey, idKey] = keys;
+    const hasMs = body[msKey] !== undefined && body[msKey] !== null;
+    const hasId = body[idKey] !== undefined && body[idKey] !== null;
+    if (hasMs !== hasId)
+        return null;
+    const limit = pageSize(body);
+    let sorted = [...rows].sort((a, b) => {
+        const [am, ai] = key(a);
+        const [bm, bi] = key(b);
+        return compare(bm, am) || compare(bi, ai);
+    });
+    if (hasMs) {
+        const afterMs = Number(body[msKey]);
+        const afterId = String(body[idKey]);
+        sorted = sorted.filter((row) => {
+            const [ms, id] = key(row);
+            return ms < afterMs || (ms === afterMs && id < afterId);
+        });
+    }
+    const page = sorted.slice(0, limit);
+    const last = page[page.length - 1];
+    return { page, next: page.length === limit && last ? cursor(last) : null };
+}
+export const createSimpleEmailFake = (ctx) => {
+    const state = ctx.load() ?? { accounts: [], sends: [] };
+    const save = () => ctx.save(state);
+    const cursorRefusal = () => ctx.refuse(400, "bad_request", "cursor needs BOTH keys or neither");
+    function findAccount(appId) {
+        return state.accounts.find((a) => a.app_id === appId);
+    }
+    function createAccount(appId, sendGroup) {
+        const account = {
+            app_id: appId,
+            address: `${appId}@${SENDING_DOMAIN}`,
+            display_name: null,
+            send_group: sendGroup,
+            created_time_stamp: ctx.now(),
+            templates: [],
+        };
+        state.accounts.push(account);
+        return account;
+    }
+    function send(body) {
+        if (typeof body.app_id !== "string" || body.app_id === "") {
+            return ctx.refuse(400, "bad_request", "app_id is required");
+        }
+        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 hasTemplate = body.template_id !== undefined && body.template_id !== null;
+        const hasInline = body.subject !== undefined || body.html !== undefined;
+        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);
+        let subject;
+        let html;
+        let templateId = null;
+        if (hasTemplate) {
+            const template = account.templates.find((t) => t.template_id === body.template_id);
+            if (!template) {
+                return ctx.refuse(400, "bad_request", "template_id names no template of this account");
+            }
+            const variables = isObject(body.variables) ? body.variables : {};
+            subject = render(template.subject, variables);
+            html = render(template.html, variables);
+            templateId = template.template_id;
+        }
+        else {
+            if (typeof body.subject !== "string" || typeof body.html !== "string") {
+                return ctx.refuse(400, "bad_request", "subject and html are required together");
+            }
+            subject = body.subject;
+            html = body.html;
+        }
+        const now = ctx.now();
+        const row = {
+            app_id: account.app_id,
+            send_id: ctx.nanoid(),
+            requester_user_id: ctx.user()?.id ?? "mock-user",
+            via_app: true,
+            kind: hasTemplate ? "template" : "inline",
+            template_id: templateId,
+            subject,
+            recipients: [...to],
+            recipient_count: to.length,
+            outcome: "sent",
+            outcome_reason: 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,
+            subject,
+            html,
+        });
+        return ctx.ok({ ok: true, send_id: row.send_id, recipient_count: row.recipient_count });
+    }
+    function handle(path, rawBody) {
+        const body = isObject(rawBody) ? rawBody : {};
+        const signedIn = ctx.user() !== null;
+        if (path === "/send") {
+            if (!signedIn)
+                return ctx.notFound();
+            return send(body);
+        }
+        if (path === "/sends/list") {
+            const appId = typeof body.app_id === "string" ? body.app_id : "";
+            const rows = state.sends.filter((s) => s.app_id === appId);
+            const result = keysetPage(rows, body, ["after_created_time_stamp", "after_send_id"], (s) => [s.fired_at, s.send_id], (s) => ({ after_created_time_stamp: s.fired_at, after_send_id: s.send_id }));
+            if (!result)
+                return cursorRefusal();
+            const sends = result.page.map(({ app_id: _appId, ...row }) => row);
+            return ctx.ok({ ok: true, sends, next_cursor: result.next });
+        }
+        if (path === "/accounts/create") {
+            if (!signedIn)
+                return ctx.notFound();
+            if (typeof body.app_id !== "string" || body.app_id === "") {
+                return ctx.refuse(400, "bad_request", "app_id is required");
+            }
+            if (findAccount(body.app_id)) {
+                return ctx.refuse(409, "account_exists", "this app already has an email account");
+            }
+            const sendGroup = typeof body.send_group === "string" ? body.send_group : null;
+            const account = createAccount(body.app_id, sendGroup);
+            save();
+            return ctx.ok({ ok: true, account: accountPayload(account) });
+        }
+        if (path === "/accounts/list") {
+            const result = keysetPage(state.accounts, body, ["after_created_time_stamp", "after_app_id"], (a) => [a.created_time_stamp, a.app_id], (a) => ({ after_created_time_stamp: a.created_time_stamp, after_app_id: a.app_id }));
+            if (!result)
+                return cursorRefusal();
+            return ctx.ok({ ok: true, accounts: result.page.map(accountPayload), next_cursor: result.next });
+        }
+        const parts = path.split("/").filter((p) => p !== "").map(decodeURIComponent);
+        if (parts[0] !== "accounts" || parts[1] === undefined)
+            return null;
+        const account = findAccount(parts[1]);
+        const rest = parts.slice(2);
+        const route = rest.join("/");
+        if (route === "info") {
+            if (!account)
+                return ctx.notFound();
+            const today = new Date().toISOString().slice(0, 10);
+            const sentToday = state.sends
+                .filter((s) => s.app_id === account.app_id && new Date(s.fired_at).toISOString().slice(0, 10) === today)
+                .reduce((sum, s) => sum + s.recipient_count, 0);
+            return ctx.ok({
+                ok: true,
+                account: accountPayload(account),
+                daily_cap: DAILY_CAP,
+                sent_today: sentToday,
+                credit_blocked: false,
+                phone_verified: true,
+            });
+        }
+        if (route === "delete") {
+            if (!signedIn || !account)
+                return ctx.notFound();
+            state.accounts = state.accounts.filter((a) => a !== account);
+            save();
+            return ctx.ok({ ok: true });
+        }
+        if (route === "access/set") {
+            if (!signedIn || !account)
+                return ctx.notFound();
+            if (!("send_group" in body))
+                return ctx.refuse(400, "bad_request", "send_group is required");
+            account.send_group = typeof body.send_group === "string" ? body.send_group : null;
+            save();
+            return ctx.ok({ ok: true, account: accountPayload(account) });
+        }
+        if (route === "templates/create") {
+            if (!signedIn || !account)
+                return ctx.notFound();
+            if (typeof body.subject !== "string" || typeof body.html !== "string") {
+                return ctx.refuse(400, "bad_request", "subject and html are required");
+            }
+            const now = ctx.now();
+            const template = {
+                template_id: ctx.nanoid(),
+                name: typeof body.name === "string" ? body.name : null,
+                subject: body.subject,
+                html: body.html,
+                created_time_stamp: now,
+                updated_time_stamp: now,
+            };
+            account.templates.push(template);
+            save();
+            return ctx.ok({ ok: true, template: templateMeta(template) });
+        }
+        if (route === "templates/list") {
+            if (!account)
+                return ctx.notFound();
+            const result = keysetPage(account.templates, body, ["after_created_time_stamp", "after_template_id"], (t) => [t.created_time_stamp, t.template_id], (t) => ({ after_created_time_stamp: t.created_time_stamp, after_template_id: t.template_id }));
+            if (!result)
+                return cursorRefusal();
+            return ctx.ok({ ok: true, templates: result.page.map(templateMeta), next_cursor: result.next });
+        }
+        if (rest[0] !== "templates" || rest[1] === undefined || rest.length !== 3)
+            return null;
+        const template = account?.templates.find((t) => t.template_id === rest[1]);
+        const action = rest[2];
+        if (action === "info") {
+            if (!template)
+                return ctx.notFound();
+            return ctx.ok({ ok: true, template: { ...templateMeta(template), html: template.html } });
+        }
+        if (action === "update") {
+            if (!signedIn || !template)
+                return ctx.notFound();
+            if (typeof body.subject !== "string" || typeof body.html !== "string") {
+                return ctx.refuse(400, "bad_request", "subject and html are both required");
+            }
+            template.subject = body.subject;
+            template.html = body.html;
+            template.updated_time_stamp = ctx.now();
+            save();
+            return ctx.ok({ ok: true, template: templateMeta(template) });
+        }
+        if (action === "delete") {
+            if (!signedIn || !account || !template)
+                return ctx.notFound();
+            account.templates = account.templates.filter((t) => t !== template);
+            save();
+            return ctx.ok({ ok: true });
+        }
+        return null;
+    }
+    return { marker: MARKER, handle: (request) => handle(request.path, request.body) };
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pilely/simple-email",
-  "version": "0.2.1",
-  "description": "A typed client for the simple_email service.",
+  "version": "0.4.0",
+  "description": "React hooks for the simple_email service.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,7 +21,9 @@
     "directory": "npm/simple-email"
   },
   "peerDependencies": {
-    "@pilely/core": "^0.2.0"
+    "@pilely/core": "^0.4.0",
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.3.0 || ^19.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",