@pilely/simple-email 0.4.2 → 0.4.3

package/README.md

@@ -10,9 +10,10 @@ React hooks for the `simple_email` service — the platform's managed transactio
 | `useSends({ limit? })` | `/sends/list`, paged | infinite query; this app's outbox, `SendRow[]` |
 | `useEmailAccount()` | `accounts/{app}/info` | query; this app's account with its daily cap, sent today, credit and phone state |
 | `useEmailAccounts({ limit? })` | `accounts/list`, paged | infinite query; every account the caller owns |
-| `useCreateEmailAccount()` | `accounts/create` | mutation, the optional send group, or `{ send_group?, account_senders? }` |
+| `useCreateEmailAccount()` | `accounts/create` | mutation, the optional send group, or `{ send_group?, account_senders?, reply_to? }` |
 | `useDeleteEmailAccount()` | `accounts/{app}/delete` | mutation, no variables |
 | `useSetEmailAccountAccess()` | `accounts/{app}/access/set` | mutation, the send group (`null` = owner-only), or `{ send_group, account_senders? }` (an omitted `account_senders` keeps the current value) |
+| `useSetEmailReplyTo()` | `accounts/{app}/set_reply_to` | mutation, the reply-to address, or `null` to clear it; always sent, never "keep" |
 | `useTemplates({ limit? })` | `templates/list`, paged | infinite query; metadata only |
 | `useTemplate(templateId)` | `templates/{t}/info` | query; the template with its `html`; an `undefined` id disables it |
 | `useCreateTemplate()` | `templates/create` | mutation, `{ name, subject, html }` (`name` may be `null`) |
@@ -27,6 +28,10 @@ A **raw send** (`to`) goes to the addresses you name, with template or inline co
 
 Who may make account sends is the account's `account_senders`: `"send_group"` (the default — the owner and the send group's members) or `"app_users"` (also every signed-in user of the app, through the app; raw sends stay closed to them). When you choose `"app_users"`, add a per-user `@simple_limiter` policy on `simple-email.<endpoint>` `/send` — without it one user can use up the app's daily cap and spend your balance. The service README's `### Who can send from an account` has the full table.
 
+## Replies: `reply_to`
+
+An account's `reply_to` is the address recipients' replies go to: every send from the account — raw, template and account sends — carries it as its `Reply-To`. `null` (the default) means none, and replies go nowhere. Set it on create (`useCreateEmailAccount()`'s `{ reply_to }`) or later with `useSetEmailReplyTo()`, which takes the address or `null` to clear it. It must be one bare address (no display name, no list) and not on `pilely-app-email.com`, `pilely.ai` or `pilely.app` nor a subdomain of one; the server answers anything else `bad_request` (400) with a reason naming the rule. Every `Account` carries it.
+
 ## Retries: `idempotency_key`
 
 Give a send an `idempotency_key` (1–128 characters of `[A-Za-z0-9._:-]`, held per app for 24 hours) and a repeat with the same key, the same body and the same caller answers the FIRST send's `send_id` with `replayed: true` — nothing is sent, billed or counted again. The same key with another body or from another caller is `idempotency_key_reused` (409); a repeat while the first is still being handed to the provider is `idempotency_key_in_progress` (409, retry in a few seconds). Pick keys stable per logical email — `confirm:<row id>`, `digest:<user id>:<YYYY-MM-DD>` — so a retry after a crash or a timeout repeats the same key. Without a key every request is a new send, and `replayed` is `false`.
@@ -36,7 +41,7 @@ Give a send an `idempotency_key` (1–128 characters of `[A-Za-z0-9._:-]`, held
 | Write | Invalidates |
 | --- | --- |
 | send | `useSends()` |
-| account create / set access | `useEmailAccounts()`, `useEmailAccount()` |
+| account create / set access / set reply-to | `useEmailAccounts()`, `useEmailAccount()` |
 | account delete | `useEmailAccounts()`, `useEmailAccount()`, and the templates under it |
 | template create | `useTemplates()` |
 | template update / delete on `t` | `useTemplates()`, `useTemplate(t)` |
@@ -96,7 +101,7 @@ 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. 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, the phone gate, 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()`.
 

package/dist/api.d.ts

@@ -89,8 +89,10 @@ export declare function listAllSends(): Promise<SendRow[]>;
  *  key is left off the wire, meaning owner-only. `setAccountAccess` below
  *  is the opposite: its key is always required. `accountSenders` is
  *  optional too, and left off the wire when `undefined` (the server then
- *  uses `"send_group"`; it refuses an explicit `null` with a 400). */
-export declare function createAccount(sendGroup?: string | null, accountSenders?: AccountSenders): Promise<Account>;
+ *  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>;
 /** 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. */
@@ -108,6 +110,11 @@ export declare function deleteAccount(): Promise<void>;
  *  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>;
+/** `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>;
 /** Returns metadata only — no `html`. Use `templateInfo` to read the body
  *  back.
  *

package/dist/api.js

@@ -1,4 +1,4 @@
-// The simple_email service's 12 POST routes, one function each. This is the
+// 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.
@@ -71,8 +71,10 @@ export async function listAllSends() {
  *  key is left off the wire, meaning owner-only. `setAccountAccess` below
  *  is the opposite: its key is always required. `accountSenders` is
  *  optional too, and left off the wire when `undefined` (the server then
- *  uses `"send_group"`; it refuses an explicit `null` with a 400). */
-export async function createAccount(sendGroup, accountSenders) {
+ *  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) {
     const body = {
         app_id: requireAppId(),
     };
@@ -82,6 +84,9 @@ export async function createAccount(sendGroup, accountSenders) {
     if (accountSenders !== undefined) {
         body.account_senders = accountSenders;
     }
+    if (replyTo !== undefined) {
+        body.reply_to = replyTo;
+    }
     const json = await call({
         service: "simple-email",
         path: "/accounts/create",
@@ -144,6 +149,18 @@ export async function setAccountAccess(sendGroup, accountSenders) {
     });
     return json.account;
 }
+/** `replyTo` is REQUIRED and its key is always sent, even `null` — the
+ *  server refuses a missing key with a 400, so a typo can never silently
+ *  clear it. An address sets where recipients' replies go (every send from
+ *  the account carries it as its `Reply-To`); `null` clears it. */
+export async function setReplyTo(replyTo) {
+    const json = await call({
+        service: "simple-email",
+        path: `/accounts/${requireAppId()}/set_reply_to`,
+        body: { reply_to: replyTo },
+    });
+    return json.account;
+}
 // ── Templates (nested under the account) ────────────────────────────────
 /** Returns metadata only — no `html`. Use `templateInfo` to read the body
  *  back.

package/dist/hooks.d.ts

@@ -11,12 +11,14 @@ export interface CreateTemplateInput {
     subject: string;
     html: string;
 }
-/** `useCreateEmailAccount`'s object form. Both keys are optional: an omitted
+/** `useCreateEmailAccount`'s object form. Every key is optional: an omitted
  *  `send_group` means owner-only, an omitted `account_senders` means
- *  `"send_group"`. */
+ *  `"send_group"`, and an omitted (or `null`) `reply_to` means no reply-to. */
 export interface CreateEmailAccountInput {
     send_group?: string | null;
     account_senders?: AccountSenders;
+    /** The address recipients' replies go to. */
+    reply_to?: string | null;
 }
 /** `useSetEmailAccountAccess`'s object form. `send_group` is required (`null`
  *  = owner-only); an omitted `account_senders` keeps the current value. */
@@ -43,13 +45,17 @@ export declare function useEmailAccounts(options?: PageOptions): UseInfiniteQuer
  *  and phone verification. */
 export declare function useEmailAccount(): UseQueryResult<AccountInfoEnvelope, Error>;
 /** Creates this app's account; the variable is its optional send group
- *  (`null` or omitted: owner-only), or `{ send_group?, account_senders? }`. */
+ *  (`null` or omitted: owner-only), or `{ send_group?, account_senders?, reply_to? }`. */
 export declare function useCreateEmailAccount(): UseMutationResult<Account, Error, string | null | void | CreateEmailAccountInput>;
 /** Deletes this app's account and the templates under it. */
 export declare function useDeleteEmailAccount(): UseMutationResult<void, Error, void>;
 /** Replaces this app's send group (`null` means owner-only); the object form
  *  `{ send_group, account_senders? }` also sets who may make account sends. */
 export declare function useSetEmailAccountAccess(): UseMutationResult<Account, Error, string | null | SetEmailAccountAccessInput>;
+/** 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>;
 /** 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. */

package/dist/hooks.js

@@ -1,5 +1,5 @@
 import { serviceQueryKey, useServiceInfiniteQuery, useServiceMutation, useServiceQuery } from "@pilely/core";
-import { accountInfo, createAccount, createTemplate, deleteAccount, deleteTemplate, listAccounts, listSends, listTemplates, send, setAccountAccess, templateInfo, updateTemplate, } from "./api.js";
+import { accountInfo, createAccount, createTemplate, deleteAccount, deleteTemplate, listAccounts, listSends, listTemplates, send, setAccountAccess, setReplyTo, templateInfo, updateTemplate, } from "./api.js";
 /** `["pilely", "simple-email", "sends", options]` */
 const sendsKey = () => serviceQueryKey("simple-email", "sends");
 /** `["pilely", "simple-email", "accounts", options]` */
@@ -50,11 +50,11 @@ 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), or `{ send_group?, account_senders? }`. */
+ *  (`null` or omitted: owner-only), or `{ send_group?, account_senders?, reply_to? }`. */
 export function useCreateEmailAccount() {
     return useServiceMutation("useCreateEmailAccount", {
         mutationFn: (input) => typeof input === "object" && input !== null
-            ? createAccount(input.send_group, input.account_senders)
+            ? createAccount(input.send_group, input.account_senders, input.reply_to)
             : createAccount(input ?? undefined),
         invalidates: () => [accountsKey(), accountKey()],
     });
@@ -76,6 +76,15 @@ export function useSetEmailAccountAccess() {
         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() {
+    return useServiceMutation("useSetEmailReplyTo", {
+        mutationFn: (replyTo) => setReplyTo(replyTo),
+        invalidates: () => [accountsKey(), accountKey()],
+    });
+}
 // ── Templates ────────────────────────────────────────────────────────────
 /** This app's templates (metadata only), as an infinite query. */
 export function useTemplates(options = {}) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { useCreateEmailAccount, useCreateTemplate, useDeleteEmailAccount, useDeleteTemplate, useEmailAccount, useEmailAccounts, useSend, useSends, useSetEmailAccountAccess, useTemplate, useTemplates, useUpdateTemplate, } from "./hooks.js";
+export { useCreateEmailAccount, useCreateTemplate, useDeleteEmailAccount, useDeleteTemplate, useEmailAccount, useEmailAccounts, useSend, useSends, useSetEmailAccountAccess, useSetEmailReplyTo, useTemplate, useTemplates, useUpdateTemplate, } from "./hooks.js";
 export type { CreateEmailAccountInput, CreateTemplateInput, PageOptions, SetEmailAccountAccessInput, UpdateTemplateInput, } from "./hooks.js";
 export type { AccountSendInput, RawSendInput, SendContent, SendInput, SendKey, SendResult } from "./api.js";
 export type { Account, AccountSenders, SimpleEmailErrorCode, AccountCursor, AccountInfoEnvelope, SendCursor, SendRow, Template, TemplateCursor, TemplateMeta, ToAccount, } from "./types.js";

package/dist/index.js

@@ -1,4 +1,4 @@
 // @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";
+export { useCreateEmailAccount, useCreateTemplate, useDeleteEmailAccount, useDeleteTemplate, useEmailAccount, useEmailAccounts, useSend, useSends, useSetEmailAccountAccess, useSetEmailReplyTo, useTemplate, useTemplates, useUpdateTemplate, } from "./hooks.js";

package/dist/mock.js

@@ -13,7 +13,10 @@
 // account send to `"self"` logs `recipients: []`, one to `"owner"` logs a
 // stand-in owner address — the fake has no real account emails. 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
+// template answer the uniform bare 404. Accounts carry `reply_to`, set on
+// create and by `set_reply_to` (key required, a string or `null`); the fake
+// checks only its type, not the address rules or refused domains. Reached
+// only from the
 // `isMockMode()` branch in index.ts, so a production build carries none of
 // it.
 const MARKER = "pilely-mock-fake:simple-email";
@@ -48,6 +51,8 @@ function accountPayload(account) {
         send_group: account.send_group,
         // State persisted before account_senders existed reads the default.
         account_senders: account.account_senders ?? "send_group",
+        // State persisted before reply_to existed reads none.
+        reply_to: account.reply_to ?? null,
         created_time_stamp: account.created_time_stamp,
     };
 }
@@ -64,6 +69,16 @@ function parseAccountSenders(body) {
     const value = body.account_senders;
     return ACCOUNT_SENDERS.includes(value) ? value : null;
 }
+/** `undefined` when the key is absent; the address, or `null` (none). A value
+ *  of any other type is the server's 400, answered as `false`. */
+function parseReplyTo(body) {
+    if (!("reply_to" in body))
+        return undefined;
+    const value = body.reply_to;
+    if (value === null || typeof value === "string")
+        return value;
+    return false;
+}
 /** The service's "same body": the caller, the mode, `to` as a
  *  case-insensitive set, `to_account`, the template and its variables, and
  *  inline content. */
@@ -128,13 +143,14 @@ export const createSimpleEmailFake = (ctx) => {
     function findAccount(appId) {
         return state.accounts.find((a) => a.app_id === appId);
     }
-    function createAccount(appId, sendGroup, accountSenders) {
+    function createAccount(appId, sendGroup, accountSenders, replyTo) {
         const account = {
             app_id: appId,
             address: `${appId}@${SENDING_DOMAIN}`,
             display_name: null,
             send_group: sendGroup,
             account_senders: accountSenders,
+            reply_to: replyTo,
             created_time_stamp: ctx.now(),
             templates: [],
         };
@@ -177,7 +193,7 @@ export const createSimpleEmailFake = (ctx) => {
         if (key !== undefined && (typeof key !== "string" || !IDEMPOTENCY_KEY.test(key))) {
             return ctx.refuse(400, "bad_request", "idempotency_key must be 1..=128 characters of [A-Za-z0-9._:-]");
         }
-        const account = findAccount(body.app_id) ?? createAccount(body.app_id, null, "send_group");
+        const account = findAccount(body.app_id) ?? createAccount(body.app_id, null, "send_group", null);
         const user = ctx.user();
         const caller = user?.id ?? "mock-user";
         const print = fingerprint(caller, body, to);
@@ -272,8 +288,12 @@ export const createSimpleEmailFake = (ctx) => {
             if (accountSenders === null) {
                 return ctx.refuse(400, "bad_request", 'account_senders must be "send_group" or "app_users"');
             }
+            const replyTo = parseReplyTo(body);
+            if (replyTo === false) {
+                return ctx.refuse(400, "bad_request", "reply_to must be an email address or null");
+            }
             const sendGroup = typeof body.send_group === "string" ? body.send_group : null;
-            const account = createAccount(body.app_id, sendGroup, accountSenders ?? "send_group");
+            const account = createAccount(body.app_id, sendGroup, accountSenders ?? "send_group", replyTo ?? null);
             save();
             return ctx.ok({ ok: true, account: accountPayload(account) });
         }
@@ -328,6 +348,20 @@ export const createSimpleEmailFake = (ctx) => {
             save();
             return ctx.ok({ ok: true, account: accountPayload(account) });
         }
+        if (route === "set_reply_to") {
+            if (!signedIn || !account)
+                return ctx.notFound();
+            const replyTo = parseReplyTo(body);
+            if (replyTo === undefined) {
+                return ctx.refuse(400, "bad_request", "reply_to is required (an email address, or null to clear it)");
+            }
+            if (replyTo === false) {
+                return ctx.refuse(400, "bad_request", "reply_to must be an email address or null");
+            }
+            account.reply_to = replyTo;
+            save();
+            return ctx.ok({ ok: true, account: accountPayload(account) });
+        }
         if (route === "templates/create") {
             if (!signedIn || !account)
                 return ctx.notFound();

package/dist/types.d.ts

@@ -39,6 +39,9 @@ export interface Account {
      *  `read_group`/`write_group`, where `null` means everyone. */
     send_group: string | null;
     account_senders: AccountSenders;
+    /** The address recipients' replies go to: every send from the account
+     *  carries it as its `Reply-To`. `null` means none — replies go nowhere. */
+    reply_to: string | null;
     created_time_stamp: number;
 }
 /** `daily_cap`'s three siblings are nullable and sit BESIDE `account`, not

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilely/simple-email",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "React hooks for the simple_email service.",
   "license": "MIT",
   "type": "module",