@pilely/simple-email 0.4.3 → 0.5.0

package/dist/send.js

@@ -0,0 +1,94 @@
+// `send` — the freestyle send, `POST /accounts/{app_id}/send`, for an app's
+// BACKEND only. The service admits exactly one caller on that route: the
+// account's app's own backend, calling with its backend token (`app:<A>` on
+// app A). A page, a signed-in user, the owner and every other app get the
+// uniform 404, so this function has no browser half: no `window.pilely`, no
+// `client.js`, no React. It takes the backend token and the app id
+// explicitly and makes one plain `fetch` with the token as bearer.
+//
+// This module imports nothing at runtime — not `@pilely/core`, not React —
+// so a server imports it from the `@pilely/simple-email/send` subpath
+// without any of the package's peers loaded. It is also re-exported from the
+// main entry. Mock mode does not reach it: it calls the global `fetch`
+// directly.
+/** Where the service answers. A testing-tier lane passes its own origin. */
+export const SIMPLE_EMAIL_ORIGIN = "https://simple-email.pilely.app";
+/** A refused `send`. `code` is `null` for a bodiless answer — an oversize
+ *  body refused before any handler runs, an unknown path — and on a missing
+ *  `appId` or `backendToken` (`status` 0, nothing was sent). Never carries
+ *  the token. */
+export class SendError extends Error {
+    status;
+    code;
+    reason;
+    name = "SendError";
+    constructor(status, code, reason) {
+        super(reason);
+        this.status = status;
+        this.code = code;
+        this.reason = reason;
+    }
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Sends one message from the app's account to every address in `to`:
+ * `POST <origin>/accounts/<appId>/send` with the backend token as bearer.
+ * Resolves to the service's answer; throws `SendError` on any refusal — a
+ * caller that is not this app's backend, an unknown account or template, or
+ * the owner out of balance (all one 404), a bad body (400), an
+ * `idempotency_key` conflict (409), the app's 500-recipient UTC-day
+ * freestyle cap (`429 daily_cap_exceeded`).
+ *
+ * ```ts
+ * import { send } from "@pilely/simple-email/send";
+ *
+ * await send(
+ *   { to: [row.email], template_id: WELCOME, variables: { name: row.name }, idempotency_key: `welcome:${row.id}` },
+ *   { appId: process.env.APP_ID!, backendToken: process.env.PILELY_BACKEND_TOKEN! },
+ * );
+ * ```
+ */
+export async function send(input, options) {
+    const { appId, backendToken } = options;
+    if (!appId)
+        throw new SendError(0, null, "send needs an appId (the account's app uuid)");
+    if (!backendToken)
+        throw new SendError(0, null, "send needs a backendToken (PILELY_BACKEND_TOKEN is not set)");
+    const origin = (options.origin ?? SIMPLE_EMAIL_ORIGIN).replace(/\/+$/, "");
+    const { to, idempotency_key } = input;
+    const body = "template_id" in input
+        ? { to, template_id: input.template_id, variables: input.variables, idempotency_key }
+        : { to, subject: input.subject, html: input.html, idempotency_key };
+    const res = await fetch(`${origin}/accounts/${encodeURIComponent(appId)}/send`, {
+        method: "POST",
+        headers: {
+            authorization: `Bearer ${backendToken}`,
+            accept: "application/json",
+            "content-type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    let json = null;
+    try {
+        json = await res.json();
+    }
+    catch {
+        // a bare answer has no body
+    }
+    const envelope = isObject(json) ? json : {};
+    if (res.status !== 200 || envelope.ok === false) {
+        const code = typeof envelope.code === "string" ? envelope.code : null;
+        const reason = typeof envelope.reason === "string" ? envelope.reason : `simple-email answered ${res.status}`;
+        throw new SendError(res.status, code, reason);
+    }
+    if (typeof envelope.send_id !== "string") {
+        throw new SendError(res.status, null, "simple-email answered 200 without a send_id");
+    }
+    return {
+        send_id: envelope.send_id,
+        recipient_count: Number(envelope.recipient_count),
+        replayed: envelope.replayed === true,
+    };
+}

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;
@@ -14,31 +14,27 @@ export type SimpleEmailErrorCode = "unauthenticated" | "bad_forwarded_identity"
 /** 409 — an earlier request with this `idempotency_key` is still being
  *  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"
+/** 429 — a per-app UTC-day cap: the daily send cap on a template send,
+ *  the 500-recipient freestyle cap on `send()`. */
+ | "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";
-/** 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
- *  account's own app send a template to their own or the owner's account
- *  email. It never opens raw sends (`to`). */
-export type AccountSenders = "send_group" | "app_users";
-/** The recipient of an account send, resolved by the service: the caller's
- *  own Pilely account email (`"self"`) or the account owner's (`"owner"`).
- *  The caller never supplies or sees the address. */
-export type ToAccount = "self" | "owner";
+ *  app's template sends; root answers it with a `Retry-After` header. */
+ | "rate_limited"
+/** 403 — root's challenge check: a challenge policy the app's owner set
+ *  on this route (for example the template send,
+ *  `POST /accounts/{app_id}/templates/{template_id}/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";
 /** `address` is derived at read time, never stored, and `null` when the
  *  app it names is gone. */
 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. */
-    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;
@@ -51,16 +47,25 @@ 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`. */
+/** What `templates/create`, `templates/update` and `templates/list` answer
+ *  with — no `html`. */
 export interface TemplateMeta {
     template_id: string;
-    /** Not updatable through `updateTemplate` — only `subject` and `html` are.
-     *  `null` when the template was created without one: the service accepts a
-     *  nameless template and returns the name back as `null`. */
+    /** Not updatable through `updateTemplate`. `null` when the template was
+     *  created without one: the service accepts a nameless template and
+     *  returns the name back as `null`. */
     name: string | null;
     subject: string;
+    /** The ONE address every template send of this template goes to. The
+     *  owner reads it here; no template-send answer ever carries it. */
+    recipient: string;
+    /** Who may make a template send of it: an owner group or one of the two
+     *  platform-wide groups. `null` is empty — nobody may. */
+    send_group: string | null;
+    /** An owner group whose members are refused whatever `send_group` says.
+     *  `null` is empty — nobody is refused. */
+    deny_group: string | null;
     created_time_stamp: number;
     updated_time_stamp: number;
 }
@@ -74,31 +79,6 @@ export interface TemplateMeta {
 export interface Template extends TemplateMeta {
     html?: string;
 }
-/** One send-log row. An account send's row carries its `to_account`: for
- *  `"self"`, `recipients` is `[]` and `recipient_count` is `1` — the owner
- *  never sees a user's account email through this service; for `"owner"`,
- *  `recipients` holds the owner's own address. */
-export interface SendRow {
-    send_id: string;
-    requester_user_id: string;
-    via_app: boolean;
-    kind: string;
-    template_id: string | null;
-    subject: string;
-    recipients: unknown;
-    recipient_count: number;
-    outcome: string;
-    outcome_reason: string | null;
-    /** `null` for a raw send. */
-    to_account: ToAccount | null;
-    /** The caller's `idempotency_key`, or `null` when the send had none. */
-    idempotency_key: string | null;
-    fired_at: number;
-}
-export interface SendCursor {
-    after_created_time_stamp: number;
-    after_send_id: string;
-}
 export interface AccountCursor {
     after_created_time_stamp: number;
     after_app_id: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pilely/simple-email",
-  "version": "0.4.3",
-  "description": "React hooks for the simple_email service.",
+  "version": "0.5.0",
+  "description": "React hooks and the template send for the simple_email service, and send() for an app's backend.",
   "license": "MIT",
   "type": "module",
   "main": "./dist/index.js",
@@ -10,6 +10,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./send": {
+      "types": "./dist/send.d.ts",
+      "default": "./dist/send.js"
     }
   },
   "sideEffects": false,
@@ -21,7 +25,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"
   },