@pilely/simple-email 0.4.3 → 0.4.5

package/README.md

@@ -8,7 +8,7 @@ React hooks for the `simple_email` service — the platform's managed transactio
 | --- | --- | --- |
 | `useSend()` | `/send` | mutation, `{ to, subject, html }` or `{ to, template_id, variables? }` (a raw send), or `{ to_account, template_id, variables? }` (an account send); each takes an optional `idempotency_key`. Answers `{ send_id, recipient_count, replayed }` |
 | `useSends({ limit? })` | `/sends/list`, paged | infinite query; this app's outbox, `SendRow[]` |
-| `useEmailAccount()` | `accounts/{app}/info` | query; this app's account with its daily cap, sent today, credit and phone state |
+| `useEmailAccount()` | `accounts/{app}/info` | query; this app's account with its daily cap, sent today and credit state |
 | `useEmailAccounts({ limit? })` | `accounts/list`, paged | infinite query; every account the caller owns |
 | `useCreateEmailAccount()` | `accounts/create` | mutation, the optional send group, or `{ send_group?, account_senders?, reply_to? }` |
 | `useDeleteEmailAccount()` | `accounts/{app}/delete` | mutation, no variables |
@@ -22,6 +22,19 @@ React hooks for the `simple_email` service — the platform's managed transactio
 
 The app id is added from `@pilely/core` on every route; it is never a variable. Every write waits for the server: an email "sent" before the server accepted it would be a lie.
 
+## Bot checks: `{ challenge }`
+
+The app's owner can put a **challenge policy** on any route of `simple-email.pilely.app` for the app, typically `POST /send` (`https://simple-limiter.pilely.app/README.md`); root then refuses every send through the app that carries no solved bot check with `403 challenge_required`, before the service sees it — the owner's and the app's server's sends included. Every hook takes a `challenge` option for that, in its options object or as its last argument where it has none (`useSend({ challenge })`, `useTemplate(templateId, { challenge })`):
+
+```tsx
+import { getChallenge, solveChallenge } from "@pilely/simple-limiter";
+
+const send = useSend({ challenge: async () => solveChallenge(await getChallenge()) });
+await send.mutateAsync({ to_account: "owner", template_id, variables }); // a fresh answer per send
+```
+
+A string, or a function answering one (it may be async, and may answer `undefined`) asked once for each request the hook sends; every request carries it as the `X-Pilely-Challenge` header, and root uses it up only on a call a policy matches. One answer works for one call, within 5 minutes of `getChallenge()`, so give a function to a hook that sends more than once. A refusal is a `PilelyError` with `challenge_required` or `challenge_failed` (both 403) and is never retried; get and solve a new one to start over.
+
 ## Raw sends and account sends
 
 A **raw send** (`to`) goes to the addresses you name, with template or inline content. An **account send** (`to_account`) sends a template to one address the service looks up itself: the caller's own Pilely account email (`"self"`) or the app owner's (`"owner"`). The caller never supplies or sees that address — not in the answer, and not on the `"self"` row of the owner's `useSends()` (its `recipients` is `[]`). An account send is template-only: `to` with `to_account`, or `subject` / `html` on an account send, does not typecheck. It counts 1 recipient toward the daily cap and is billed to the owner like any other send.
@@ -101,15 +114,17 @@ Importing this package in a build made with `VITE_PILELY_MOCK=1` registers an in
 
 **Nothing is ever sent.** A send is appended to an in-memory outbox — the rows `useSends` answers — and logged to the console. Accounts and templates persist to `localStorage` across reloads; the app's account is created on its first send. A missing account or template answers the bare 404, and a second account for the same app answers `account_exists` (409). The 50-recipient bound is kept.
 
-It models the send shapes and `idempotency_key`: an account send's row carries `to_account` and one recipient (`recipients: []` for `"self"`, a stand-in owner address for `"owner"` — the fake has no real account emails); a body with both `to` and `to_account`, or an account send with inline content, is `bad_request`; a repeat with the same key, body and caller answers `replayed: true` without a new row, and the same key with another body is `idempotency_key_reused`. Accounts carry `account_senders`, settable on create and access/set, and `reply_to`, settable on create and set_reply_to (a missing key or a non-string value on set_reply_to is `bad_request`; the address rules and refused domains are not checked). It does not model send groups, `account_senders` gating, the daily cap, the phone gate, rate limits, credit checks or `idempotency_key_in_progress`.
+It models the send shapes and `idempotency_key`: an account send's row carries `to_account` and one recipient (`recipients: []` for `"self"`, a stand-in owner address for `"owner"` — the fake has no real account emails); a body with both `to` and `to_account`, or an account send with inline content, is `bad_request`; a repeat with the same key, body and caller answers `replayed: true` without a new row, and the same key with another body is `idempotency_key_reused`. Accounts carry `account_senders`, settable on create and access/set, and `reply_to`, settable on create and set_reply_to (a missing key or a non-string value on set_reply_to is `bad_request`; the address rules and refused domains are not checked). It does not model send groups, `account_senders` gating, the daily cap, rate limits, credit checks or `idempotency_key_in_progress`.
 
 Writes need a signed-in user: a signed-out write answers the uniform bare 404, which reaches the hook's `error` as `PilelyError(404, null)`. See [`@pilely/core`](../core#mock-mode) for the switch, `seedMock()` and `resetMock()`.
 
 ## Error codes
 
-Refusals arrive as `PilelyError` in the hook's `error`, with a `code` drawn from `SimpleEmailErrorCode`. Match on the code, not the status: **`out_of_traffic_credits` and `phone_verification_unavailable` both answer 503** — one means the owner's traffic balance is used up (the owner must top up), the other is transient (retry shortly). `daily_cap_exceeded` (429) means the app spent its UTC-day allowance (retry tomorrow). `rate_limited` (429) means the caller is over a `@simple_limiter` policy the app's owner set on this app's sends; root answers it with a `Retry-After` header (retry after that many seconds). `idempotency_key_reused` (409) means the key already belongs to a different request on this app in the last 24 hours — nothing was sent, use a new key for a different email; `idempotency_key_in_progress` (409) means the first request with that key is still being handed to the provider — retry in a few seconds with the same key.
+Refusals arrive as `PilelyError` in the hook's `error`, with a `code` drawn from `SimpleEmailErrorCode`. Match on the code, not the status: **`daily_cap_exceeded` and `rate_limited` both answer 429**. `daily_cap_exceeded` means the app spent its UTC-day allowance (retry tomorrow). `rate_limited` means the caller is over a `@simple_limiter` policy the app's owner set on this app's sends; root answers it with a `Retry-After` header (retry after that many seconds). `idempotency_key_reused` (409) means the key already belongs to a different request on this app in the last 24 hours — nothing was sent, use a new key for a different email; `idempotency_key_in_progress` (409) means the first request with that key is still being handed to the provider — retry in a few seconds with the same key.
+
+A send can also answer `out_of_traffic_credits` (503): the owner's traffic balance is used up, and the owner must top up. Provisioning adds `account_exists`, `account_limit_reached` and `template_limit_reached` (all 409). The rest: `not_found` (404, the uniform hide), `bad_request` (400), `unauthenticated` (401), `bad_forwarded_identity` (401), `internal` (500).
 
-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`.
+A route the app's owner put a challenge policy on (`## Bot checks: { challenge }`) answers two more, from root before the service: `challenge_required` (403, the call carried no `challenge`; nothing was sent) and `challenge_failed` (403, the `challenge` was malformed, wrong, expired, started through another app, or already used — get and solve a new one). An oversize send or template body is refused before any handler runs, so its `code` is `null`.
 
 Limits: billed per recipient, at most 50 recipients per send (an account send has exactly 1), 200 recipients per app per UTC day by default. `useEmailAccount()`'s `daily_cap` shows the cap in force for this app; for a higher one, open a support ticket on `@customer` naming the app, the cap you want and what the mail is.
 

package/dist/api.d.ts

@@ -1,3 +1,4 @@
+import type { ChallengeOption } from "@pilely/core";
 import type { Account, AccountCursor, AccountInfoEnvelope, AccountSenders, SendCursor, SendRow, Template, TemplateCursor, TemplateMeta, ToAccount } from "./types.js";
 /** `to` is capped at the service's `max_recipients_per_send` (50 by default). */
 export type SendContent = {
@@ -77,14 +78,14 @@ export interface UpdateTemplateBody {
  * the failure is not an `{ok:false}` envelope and the thrown `PilelyError`
  * carries a null `code`.
  */
-export declare function send(input: SendInput): Promise<SendResult>;
+export declare function send(input: SendInput, { challenge }?: ChallengeOption): Promise<SendResult>;
 /** `app_id` lives in the body here, like `send` — not in the path. The
  *  paged primitive; use `listAllSends` to walk to the end. */
-export declare function listSends(options?: ListSendsOptions): Promise<{
+export declare function listSends(options?: ListSendsOptions, { challenge }?: ChallengeOption): Promise<{
     sends: SendRow[];
     next_cursor: SendCursor | null;
 }>;
-export declare function listAllSends(): Promise<SendRow[]>;
+export declare function listAllSends(request?: ChallengeOption): Promise<SendRow[]>;
 /** `sendGroup` is optional here — omit it (or pass `undefined`) and the
  *  key is left off the wire, meaning owner-only. `setAccountAccess` below
  *  is the opposite: its key is always required. `accountSenders` is
@@ -92,49 +93,49 @@ export declare function listAllSends(): Promise<SendRow[]>;
  *  uses `"send_group"`; it refuses an explicit `null` with a 400).
  *  `replyTo` is optional as well: `undefined` leaves the key off the wire,
  *  and omitted or `null` both mean no reply-to. */
-export declare function createAccount(sendGroup?: string | null, accountSenders?: AccountSenders, replyTo?: string | null): Promise<Account>;
+export declare function createAccount(sendGroup?: string | null, accountSenders?: AccountSenders, replyTo?: string | null, { challenge }?: ChallengeOption): Promise<Account>;
 /** No `app_id` anywhere on this route — `after_app_id` is a cursor field,
  *  not a selector. The paged primitive; use `listAllAccounts` to walk to
  *  the end. */
-export declare function listAccounts(options?: ListAccountsOptions): Promise<{
+export declare function listAccounts(options?: ListAccountsOptions, { challenge }?: ChallengeOption): Promise<{
     accounts: Account[];
     next_cursor: AccountCursor | null;
 }>;
-export declare function listAllAccounts(): Promise<Account[]>;
+export declare function listAllAccounts(request?: ChallengeOption): 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>;
+export declare function accountInfo({ challenge }?: ChallengeOption): Promise<AccountInfoEnvelope>;
+export declare function deleteAccount({ challenge }?: ChallengeOption): Promise<void>;
 /** `sendGroup` is REQUIRED here and its key is always sent, even `null` —
  *  the opposite of `createAccount`, where the key is optional. `null`
  *  means owner-only. `accountSenders` is optional: `undefined` leaves the
  *  key off the wire, which KEEPS the account's current value. */
-export declare function setAccountAccess(sendGroup: string | null, accountSenders?: AccountSenders): Promise<Account>;
+export declare function setAccountAccess(sendGroup: string | null, accountSenders?: AccountSenders, { challenge }?: ChallengeOption): Promise<Account>;
 /** `replyTo` is REQUIRED and its key is always sent, even `null` — the
  *  server refuses a missing key with a 400, so a typo can never silently
  *  clear it. An address sets where recipients' replies go (every send from
  *  the account carries it as its `Reply-To`); `null` clears it. */
-export declare function setReplyTo(replyTo: string | null): Promise<Account>;
+export declare function setReplyTo(replyTo: string | null, { challenge }?: ChallengeOption): 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>;
+export declare function createTemplate(name: string | null, subject: string, html: string, { challenge }?: ChallengeOption): Promise<TemplateMeta>;
 /** The paged primitive; use `listAllTemplates` to walk to the end. Rows
  *  carry metadata only — no `html`. */
-export declare function listTemplates(options?: ListTemplatesOptions): Promise<{
+export declare function listTemplates(options?: ListTemplatesOptions, { challenge }?: ChallengeOption): Promise<{
     templates: TemplateMeta[];
     next_cursor: TemplateCursor | null;
 }>;
-export declare function listAllTemplates(): Promise<TemplateMeta[]>;
+export declare function listAllTemplates(request?: ChallengeOption): Promise<TemplateMeta[]>;
 /** The only template route whose answer carries `html`. */
-export declare function templateInfo(templateNanoid: string): Promise<Template>;
+export declare function templateInfo(templateNanoid: string, { challenge }?: ChallengeOption): Promise<Template>;
 /**
  * A FULL REPLACE of both `subject` and `html` — never a patch — and `name`
  * is not updatable at all. Returns metadata only, like `createTemplate`.
  * Subject to the same oversize-body caveat as `send`/`createTemplate`.
  */
-export declare function updateTemplate(templateNanoid: string, body: UpdateTemplateBody): Promise<TemplateMeta>;
-export declare function deleteTemplate(templateNanoid: string): Promise<void>;
+export declare function updateTemplate(templateNanoid: string, body: UpdateTemplateBody, { challenge }?: ChallengeOption): Promise<TemplateMeta>;
+export declare function deleteTemplate(templateNanoid: string, { challenge }?: ChallengeOption): Promise<void>;

package/dist/api.js

@@ -1,7 +1,9 @@
 // The simple_email service's 13 POST routes, one function each. This is the
 // internal layer the hooks in hooks.ts call; the package exports the hooks,
 // not these. app_id moves between the body and the path from route to
-// route on this service.
+// route on this service. Every function takes `{ challenge }` — a bot-check
+// answer, or a function asked once per request — and every request it sends
+// carries it.
 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
@@ -31,7 +33,7 @@ function requireAppId() {
  * the failure is not an `{ok:false}` envelope and the thrown `PilelyError`
  * carries a null `code`.
  */
-export async function send(input) {
+export async function send(input, { challenge } = {}) {
     const app_id = requireAppId();
     const idempotency_key = input.idempotency_key;
     const body = input.to_account !== undefined
@@ -43,11 +45,12 @@ export async function send(input) {
         service: "simple-email",
         path: "/send",
         body,
+        challenge,
     });
 }
 /** `app_id` lives in the body here, like `send` — not in the path. The
  *  paged primitive; use `listAllSends` to walk to the end. */
-export async function listSends(options = {}) {
+export async function listSends(options = {}, { challenge } = {}) {
     const json = await call({
         service: "simple-email",
         path: "/sends/list",
@@ -57,12 +60,13 @@ export async function listSends(options = {}) {
             after_created_time_stamp: options.after_created_time_stamp,
             after_send_id: options.after_send_id,
         },
+        challenge,
     });
     return { sends: json.sends, next_cursor: json.next_cursor };
 }
-export async function listAllSends() {
+export async function listAllSends(request = {}) {
     return collectPages(async (cursor) => {
-        const page = await listSends({ limit: 100, ...(cursor ?? {}) });
+        const page = await listSends({ limit: 100, ...(cursor ?? {}) }, request);
         return { rows: page.sends, nextCursor: page.next_cursor };
     });
 }
@@ -74,7 +78,7 @@ export async function listAllSends() {
  *  uses `"send_group"`; it refuses an explicit `null` with a 400).
  *  `replyTo` is optional as well: `undefined` leaves the key off the wire,
  *  and omitted or `null` both mean no reply-to. */
-export async function createAccount(sendGroup, accountSenders, replyTo) {
+export async function createAccount(sendGroup, accountSenders, replyTo, { challenge } = {}) {
     const body = {
         app_id: requireAppId(),
     };
@@ -91,13 +95,14 @@ export async function createAccount(sendGroup, accountSenders, replyTo) {
         service: "simple-email",
         path: "/accounts/create",
         body,
+        challenge,
     });
     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 = {}) {
+export async function listAccounts(options = {}, { challenge } = {}) {
     const json = await call({
         service: "simple-email",
         path: "/accounts/list",
@@ -106,38 +111,39 @@ export async function listAccounts(options = {}) {
             after_created_time_stamp: options.after_created_time_stamp,
             after_app_id: options.after_app_id,
         },
+        challenge,
     });
     return { accounts: json.accounts, next_cursor: json.next_cursor };
 }
-export async function listAllAccounts() {
+export async function listAllAccounts(request = {}) {
     return collectPages(async (cursor) => {
-        const page = await listAccounts({ limit: 100, ...(cursor ?? {}) });
+        const page = await listAccounts({ limit: 100, ...(cursor ?? {}) }, request);
         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() {
+export async function accountInfo({ challenge } = {}) {
     const json = await call({
         service: "simple-email",
         path: `/accounts/${requireAppId()}/info`,
+        challenge,
     });
     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` });
+export async function deleteAccount({ challenge } = {}) {
+    await call({ service: "simple-email", path: `/accounts/${requireAppId()}/delete`, challenge });
 }
 /** `sendGroup` is REQUIRED here and its key is always sent, even `null` —
  *  the opposite of `createAccount`, where the key is optional. `null`
  *  means owner-only. `accountSenders` is optional: `undefined` leaves the
  *  key off the wire, which KEEPS the account's current value. */
-export async function setAccountAccess(sendGroup, accountSenders) {
+export async function setAccountAccess(sendGroup, accountSenders, { challenge } = {}) {
     const body = { send_group: sendGroup };
     if (accountSenders !== undefined) {
         body.account_senders = accountSenders;
@@ -146,6 +152,7 @@ export async function setAccountAccess(sendGroup, accountSenders) {
         service: "simple-email",
         path: `/accounts/${requireAppId()}/access/set`,
         body,
+        challenge,
     });
     return json.account;
 }
@@ -153,11 +160,12 @@ export async function setAccountAccess(sendGroup, accountSenders) {
  *  server refuses a missing key with a 400, so a typo can never silently
  *  clear it. An address sets where recipients' replies go (every send from
  *  the account carries it as its `Reply-To`); `null` clears it. */
-export async function setReplyTo(replyTo) {
+export async function setReplyTo(replyTo, { challenge } = {}) {
     const json = await call({
         service: "simple-email",
         path: `/accounts/${requireAppId()}/set_reply_to`,
         body: { reply_to: replyTo },
+        challenge,
     });
     return json.account;
 }
@@ -168,17 +176,18 @@ export async function setReplyTo(replyTo) {
  *  `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) {
+export async function createTemplate(name, subject, html, { challenge } = {}) {
     const json = await call({
         service: "simple-email",
         path: `/accounts/${requireAppId()}/templates/create`,
         body: { name, subject, html },
+        challenge,
     });
     return json.template;
 }
 /** The paged primitive; use `listAllTemplates` to walk to the end. Rows
  *  carry metadata only — no `html`. */
-export async function listTemplates(options = {}) {
+export async function listTemplates(options = {}, { challenge } = {}) {
     const json = await call({
         service: "simple-email",
         path: `/accounts/${requireAppId()}/templates/list`,
@@ -187,20 +196,22 @@ export async function listTemplates(options = {}) {
             after_created_time_stamp: options.after_created_time_stamp,
             after_template_id: options.after_template_id,
         },
+        challenge,
     });
     return { templates: json.templates, next_cursor: json.next_cursor };
 }
-export async function listAllTemplates() {
+export async function listAllTemplates(request = {}) {
     return collectPages(async (cursor) => {
-        const page = await listTemplates({ limit: 100, ...(cursor ?? {}) });
+        const page = await listTemplates({ limit: 100, ...(cursor ?? {}) }, request);
         return { rows: page.templates, nextCursor: page.next_cursor };
     });
 }
 /** The only template route whose answer carries `html`. */
-export async function templateInfo(templateNanoid) {
+export async function templateInfo(templateNanoid, { challenge } = {}) {
     const json = await call({
         service: "simple-email",
         path: `/accounts/${requireAppId()}/templates/${templateNanoid}/info`,
+        challenge,
     });
     return json.template;
 }
@@ -209,17 +220,19 @@ export async function templateInfo(templateNanoid) {
  * 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) {
+export async function updateTemplate(templateNanoid, body, { challenge } = {}) {
     const json = await call({
         service: "simple-email",
         path: `/accounts/${requireAppId()}/templates/${templateNanoid}/update`,
         body,
+        challenge,
     });
     return json.template;
 }
-export async function deleteTemplate(templateNanoid) {
+export async function deleteTemplate(templateNanoid, { challenge } = {}) {
     await call({
         service: "simple-email",
         path: `/accounts/${requireAppId()}/templates/${templateNanoid}/delete`,
+        challenge,
     });
 }

package/dist/hooks.d.ts

@@ -1,7 +1,8 @@
+import type { ChallengeOption } from "@pilely/core";
 import type { UseInfiniteQueryResult, UseMutationResult, UseQueryResult } from "@tanstack/react-query";
 import type { SendInput, SendResult } from "./api.js";
 import type { Account, AccountInfoEnvelope, AccountSenders, SendRow, Template, TemplateMeta } from "./types.js";
-export interface PageOptions {
+export interface PageOptions extends ChallengeOption {
     /** Rows per page; the server defaults to 50 and caps at 100. */
     limit?: number;
 }
@@ -36,30 +37,30 @@ export interface UpdateTemplateInput {
  *  send (`to_account: "self" | "owner"`). Not optimistic: a send counts only
  *  once the server accepted it. A repeat carrying the same `idempotency_key`
  *  answers the first send with `replayed: true`. */
-export declare function useSend(): UseMutationResult<SendResult, Error, SendInput>;
+export declare function useSend(options?: ChallengeOption): UseMutationResult<SendResult, Error, SendInput>;
 /** This app's outbox, newest first, as an infinite query. */
 export declare function useSends(options?: PageOptions): UseInfiniteQueryResult<SendRow[], Error>;
 /** The caller's email accounts across apps, as an infinite query. */
 export declare function useEmailAccounts(options?: PageOptions): UseInfiniteQueryResult<Account[], Error>;
-/** This app's account with its live state: daily cap, sent today, credit
- *  and phone verification. */
-export declare function useEmailAccount(): UseQueryResult<AccountInfoEnvelope, Error>;
+/** This app's account with its live state: daily cap, sent today and
+ *  credit. */
+export declare function useEmailAccount(options?: ChallengeOption): UseQueryResult<AccountInfoEnvelope, Error>;
 /** Creates this app's account; the variable is its optional send group
  *  (`null` or omitted: owner-only), or `{ send_group?, account_senders?, reply_to? }`. */
-export declare function useCreateEmailAccount(): UseMutationResult<Account, Error, string | null | void | CreateEmailAccountInput>;
+export declare function useCreateEmailAccount(options?: ChallengeOption): UseMutationResult<Account, Error, string | null | void | CreateEmailAccountInput>;
 /** Deletes this app's account and the templates under it. */
-export declare function useDeleteEmailAccount(): UseMutationResult<void, Error, void>;
+export declare function useDeleteEmailAccount(options?: ChallengeOption): UseMutationResult<void, Error, void>;
 /** Replaces this app's send group (`null` means owner-only); the object form
  *  `{ send_group, account_senders? }` also sets who may make account sends. */
-export declare function useSetEmailAccountAccess(): UseMutationResult<Account, Error, string | null | SetEmailAccountAccessInput>;
+export declare function useSetEmailAccountAccess(options?: ChallengeOption): UseMutationResult<Account, Error, string | null | SetEmailAccountAccessInput>;
 /** Sets this app's reply-to address — where recipients' replies go; every
  *  send from the account carries it as its `Reply-To` — or clears it with
  *  `null`. The variable is required: there is no "keep" form. */
-export declare function useSetEmailReplyTo(): UseMutationResult<Account, Error, string | null>;
+export declare function useSetEmailReplyTo(options?: ChallengeOption): 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>;
+export declare function useTemplate(templateId: string | undefined, options?: ChallengeOption): UseQueryResult<Template, Error>;
+export declare function useCreateTemplate(options?: ChallengeOption): UseMutationResult<TemplateMeta, Error, CreateTemplateInput>;
+export declare function useUpdateTemplate(options?: ChallengeOption): UseMutationResult<TemplateMeta, Error, UpdateTemplateInput>;
+export declare function useDeleteTemplate(options?: ChallengeOption): UseMutationResult<void, Error, string>;

package/dist/hooks.js

@@ -15,19 +15,20 @@ const templateKey = (templateId) => serviceQueryKey("simple-email", "template",
  *  send (`to_account: "self" | "owner"`). Not optimistic: a send counts only
  *  once the server accepted it. A repeat carrying the same `idempotency_key`
  *  answers the first send with `replayed: true`. */
-export function useSend() {
+export function useSend(options = {}) {
+    const { challenge } = options;
     return useServiceMutation("useSend", {
-        mutationFn: send,
+        mutationFn: (input) => send(input, { challenge }),
         invalidates: () => [sendsKey()],
     });
 }
 /** This app's outbox, newest first, as an infinite query. */
 export function useSends(options = {}) {
-    const { limit } = options;
+    const { limit, challenge } = options;
     return useServiceInfiniteQuery("useSends", {
         queryKey: [...sendsKey(), { limit }],
         fetchPage: async (cursor) => {
-            const page = await listSends({ limit, ...(cursor ?? {}) });
+            const page = await listSends({ limit, ...(cursor ?? {}) }, { challenge });
             return { rows: page.sends, nextCursor: page.next_cursor };
         },
     });
@@ -35,91 +36,103 @@ export function useSends(options = {}) {
 // ── Accounts ─────────────────────────────────────────────────────────────
 /** The caller's email accounts across apps, as an infinite query. */
 export function useEmailAccounts(options = {}) {
-    const { limit } = options;
+    const { limit, challenge } = options;
     return useServiceInfiniteQuery("useEmailAccounts", {
         queryKey: [...accountsKey(), { limit }],
         fetchPage: async (cursor) => {
-            const page = await listAccounts({ limit, ...(cursor ?? {}) });
+            const page = await listAccounts({ limit, ...(cursor ?? {}) }, { challenge });
             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 });
+/** This app's account with its live state: daily cap, sent today and
+ *  credit. */
+export function useEmailAccount(options = {}) {
+    const { challenge } = options;
+    return useServiceQuery("useEmailAccount", {
+        queryKey: accountKey(),
+        queryFn: () => accountInfo({ challenge }),
+    });
 }
 /** Creates this app's account; the variable is its optional send group
  *  (`null` or omitted: owner-only), or `{ send_group?, account_senders?, reply_to? }`. */
-export function useCreateEmailAccount() {
+export function useCreateEmailAccount(options = {}) {
+    const { challenge } = options;
     return useServiceMutation("useCreateEmailAccount", {
         mutationFn: (input) => typeof input === "object" && input !== null
-            ? createAccount(input.send_group, input.account_senders, input.reply_to)
-            : createAccount(input ?? undefined),
+            ? createAccount(input.send_group, input.account_senders, input.reply_to, { challenge })
+            : createAccount(input ?? undefined, undefined, undefined, { challenge }),
         invalidates: () => [accountsKey(), accountKey()],
     });
 }
 /** Deletes this app's account and the templates under it. */
-export function useDeleteEmailAccount() {
+export function useDeleteEmailAccount(options = {}) {
+    const { challenge } = options;
     return useServiceMutation("useDeleteEmailAccount", {
-        mutationFn: () => deleteAccount(),
+        mutationFn: () => deleteAccount({ challenge }),
         invalidates: () => [accountsKey(), accountKey(), templatesKey(), serviceQueryKey("simple-email", "template")],
     });
 }
 /** Replaces this app's send group (`null` means owner-only); the object form
  *  `{ send_group, account_senders? }` also sets who may make account sends. */
-export function useSetEmailAccountAccess() {
+export function useSetEmailAccountAccess(options = {}) {
+    const { challenge } = options;
     return useServiceMutation("useSetEmailAccountAccess", {
         mutationFn: (input) => typeof input === "object" && input !== null
-            ? setAccountAccess(input.send_group, input.account_senders)
-            : setAccountAccess(input),
+            ? setAccountAccess(input.send_group, input.account_senders, { challenge })
+            : setAccountAccess(input, undefined, { challenge }),
         invalidates: () => [accountsKey(), accountKey()],
     });
 }
 /** Sets this app's reply-to address — where recipients' replies go; every
  *  send from the account carries it as its `Reply-To` — or clears it with
  *  `null`. The variable is required: there is no "keep" form. */
-export function useSetEmailReplyTo() {
+export function useSetEmailReplyTo(options = {}) {
+    const { challenge } = options;
     return useServiceMutation("useSetEmailReplyTo", {
-        mutationFn: (replyTo) => setReplyTo(replyTo),
+        mutationFn: (replyTo) => setReplyTo(replyTo, { challenge }),
         invalidates: () => [accountsKey(), accountKey()],
     });
 }
 // ── Templates ────────────────────────────────────────────────────────────
 /** This app's templates (metadata only), as an infinite query. */
 export function useTemplates(options = {}) {
-    const { limit } = options;
+    const { limit, challenge } = options;
     return useServiceInfiniteQuery("useTemplates", {
         queryKey: [...templatesKey(), { limit }],
         fetchPage: async (cursor) => {
-            const page = await listTemplates({ limit, ...(cursor ?? {}) });
+            const page = await listTemplates({ limit, ...(cursor ?? {}) }, { challenge });
             return { rows: page.templates, nextCursor: page.next_cursor };
         },
     });
 }
 /** One template with its `html`. An `undefined` id disables the query. */
-export function useTemplate(templateId) {
+export function useTemplate(templateId, options = {}) {
+    const { challenge } = options;
     return useServiceQuery("useTemplate", {
         queryKey: templateKey(templateId),
-        queryFn: () => templateInfo(templateId),
+        queryFn: () => templateInfo(templateId, { challenge }),
         enabled: templateId !== undefined,
     });
 }
-export function useCreateTemplate() {
+export function useCreateTemplate(options = {}) {
+    const { challenge } = options;
     return useServiceMutation("useCreateTemplate", {
-        mutationFn: ({ name, subject, html }) => createTemplate(name, subject, html),
+        mutationFn: ({ name, subject, html }) => createTemplate(name, subject, html, { challenge }),
         invalidates: () => [templatesKey()],
     });
 }
-export function useUpdateTemplate() {
+export function useUpdateTemplate(options = {}) {
+    const { challenge } = options;
     return useServiceMutation("useUpdateTemplate", {
-        mutationFn: ({ templateId, subject, html }) => updateTemplate(templateId, { subject, html }),
+        mutationFn: ({ templateId, subject, html }) => updateTemplate(templateId, { subject, html }, { challenge }),
         invalidates: (_template, { templateId }) => [templatesKey(), templateKey(templateId)],
     });
 }
-export function useDeleteTemplate() {
+export function useDeleteTemplate(options = {}) {
+    const { challenge } = options;
     return useServiceMutation("useDeleteTemplate", {
-        mutationFn: deleteTemplate,
+        mutationFn: (templateId) => deleteTemplate(templateId, { challenge }),
         invalidates: (_none, templateId) => [templatesKey(), templateKey(templateId)],
     });
 }

package/dist/mock.js

@@ -5,8 +5,8 @@
 // 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, `account_senders` gating, daily caps, phone gates
-// or credit checks. It does model the send shapes (raw and account sends)
+// policy: no send groups, `account_senders` gating, daily caps or credit
+// checks. It does model the send shapes (raw and account sends)
 // and `idempotency_key`: a repeat with the same key, body and caller within
 // 24 hours answers the first send with `replayed: true` and adds no row; the
 // same key with another body or caller is `409 idempotency_key_reused`. An
@@ -322,7 +322,6 @@ export const createSimpleEmailFake = (ctx) => {
                 daily_cap: DAILY_CAP,
                 sent_today: sentToday,
                 credit_blocked: false,
-                phone_verified: true,
             });
         }
         if (route === "delete") {

package/dist/types.d.ts

@@ -2,10 +2,10 @@
  *  refusal, including the two `idempotency_key_*` conflicts, checked
  *  against the service's `response_json.rs` and `render.rs`.
  *
- *  This is the union that most earns its keep: `out_of_traffic_credits` and
- *  `phone_verification_unavailable` BOTH answer 503, so a consumer cannot tell
- *  a used-up owner balance (the owner must top up) from a transient outage
- *  (retry shortly) by status alone — only by matching this code. */
+ *  Status alone does not say what to do: `daily_cap_exceeded` and
+ *  `rate_limited` BOTH answer 429, so a consumer cannot tell a spent UTC-day
+ *  allowance (retry tomorrow) from a limiter policy (retry after
+ *  `Retry-After`) by status alone — only by matching this code. */
 export type SimpleEmailErrorCode = "unauthenticated" | "bad_forwarded_identity" | "bad_request" | "not_found" | "account_exists" | "account_limit_reached" | "template_limit_reached"
 /** 409 — this `idempotency_key` already belongs to a different request
  *  (another body or another caller) on this app in the last 24 hours;
@@ -15,10 +15,18 @@ export type SimpleEmailErrorCode = "unauthenticated" | "bad_forwarded_identity"
  *  handed to the provider; retry in a few seconds. */
  | "idempotency_key_in_progress"
 /** 429 — the per-app UTC-day send cap. */
- | "daily_cap_exceeded" | "phone_verification_required" | "phone_verification_unavailable" | "out_of_traffic_credits"
+ | "daily_cap_exceeded" | "out_of_traffic_credits"
 /** 429 — over a `@simple_limiter` policy the app's owner set on this
  *  app's sends; root answers it with a `Retry-After` header. */
- | "rate_limited" | "internal";
+ | "rate_limited"
+/** 403 — root's challenge check: a challenge policy the app's owner set
+ *  on this route (for example `POST /send`) matches the call, and it
+ *  carried no `challenge`. Nothing was sent. */
+ | "challenge_required"
+/** 403 — root's challenge check refused the `challenge` sent: malformed,
+ *  wrong, expired, started through another app, or already used. Get and
+ *  solve a new one (`@pilely/simple-limiter`) and send the call again. */
+ | "challenge_failed" | "internal";
 /** Who besides the owner may make account sends (`to_account`):
  *  `"send_group"` (the default) keeps them to the owner and the send group's
  *  members; `"app_users"` also lets every signed-in user arriving through the
@@ -35,8 +43,8 @@ export interface Account {
     app_id: string;
     address: string | null;
     display_name: string | null;
-    /** `null` means owner-only — the opposite polarity from simple_db's
-     *  `read_group`/`write_group`, where `null` means everyone. */
+    /** `null` means owner-only. Unlike a simple_db policy's `group`, it
+     *  cannot name the platform-wide anonymous or authenticated group. */
     send_group: string | null;
     account_senders: AccountSenders;
     /** The address recipients' replies go to: every send from the account
@@ -51,7 +59,6 @@ export interface AccountInfoEnvelope {
     daily_cap: number;
     sent_today: number | null;
     credit_blocked: boolean | null;
-    phone_verified: boolean | null;
 }
 /** What `templates/create` and `templates/update` answer with — no `html`. */
 export interface TemplateMeta {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilely/simple-email",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "React hooks for the simple_email service.",
   "license": "MIT",
   "type": "module",
@@ -21,7 +21,7 @@
     "directory": "npm/simple-email"
   },
   "peerDependencies": {
-    "@pilely/core": "^0.4.0",
+    "@pilely/core": "^0.4.4",
     "@tanstack/react-query": "^5.0.0",
     "react": "^18.3.0 || ^19.0.0"
   },