@pilely/simple-email 0.3.0 → 0.4.0

package/README.md

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pilely/simple-email",
-  "version": "0.3.0",
-  "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.3.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",