@pilely/simple-email 0.1.0 → 0.2.1

package/README.md

@@ -34,3 +34,41 @@ all reach it that way.
 
 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.
+
+## Error codes
+
+Refusals arrive as `PilelyError` with a `code` drawn from
+`SimpleEmailErrorCode`. Here matching on the code is not optional:
+
+**`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.
+
+`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).
+
+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.
+
+## Limits worth knowing before you call `send`
+
+- 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.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { Account, AccountCursor, AccountInfoEnvelope, SendCursor, SendRow, Template, TemplateCursor, TemplateMeta } from "./types.js";
-export type { Account, AccountCursor, AccountInfoEnvelope, SendCursor, SendRow, Template, TemplateCursor, TemplateMeta, } from "./types.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;
@@ -72,8 +72,12 @@ export declare function deleteAccount(): Promise<void>;
  *  means owner-only. */
 export declare function setAccountAccess(sendGroup: string | null): Promise<Account>;
 /** Returns metadata only — no `html`. Use `templateInfo` to read the body
- *  back. */
-export declare function createTemplate(name: string, subject: string, html: string): Promise<TemplateMeta>;
+ *  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<{

package/dist/index.js

@@ -2,6 +2,19 @@
 // POST routes. See README.md for where app_id lives on each route: this is
 // the one service where it moves between the body and the path.
 import { appId, call, collectPages } from "@pilely/core";
+/**
+ * Every route on this service needs an app id on the wire (body or path).
+ * `@pilely/core`'s `appId()` can return `null` (no tag, `ready()` not yet
+ * resolved) — this service cannot send that: a `null` in a path template
+ * would silently become the literal string `"null"`. Fail loudly instead.
+ */
+function requireAppId() {
+    const id = appId();
+    if (!id) {
+        throw new Error('pilely client not loaded, <meta name="pilely-app"> missing, and no token pile_id claim available yet — call after ready()');
+    }
+    return id;
+}
 // ── Sending ──────────────────────────────────────────────────────────────
 /**
  * `app_id` is added from core's `appId()` — it is not a caller parameter.
@@ -12,8 +25,8 @@ import { appId, call, collectPages } from "@pilely/core";
  */
 export async function send(input) {
     const body = "template_id" in input
-        ? { app_id: appId(), to: input.to, template_id: input.template_id, variables: input.variables }
-        : { app_id: appId(), to: input.to, subject: input.subject, html: input.html };
+        ? { 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",
@@ -27,7 +40,7 @@ export async function listSends(options = {}) {
         service: "simple-email",
         path: "/sends/list",
         body: {
-            app_id: appId(),
+            app_id: requireAppId(),
             limit: options.limit,
             after_created_time_stamp: options.after_created_time_stamp,
             after_send_id: options.after_send_id,
@@ -46,7 +59,7 @@ export async function listAllSends() {
  *  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: appId() };
+    const body = { app_id: requireAppId() };
     if (sendGroup !== undefined) {
         body.send_group = sendGroup;
     }
@@ -83,7 +96,7 @@ export async function listAllAccounts() {
 export async function accountInfo() {
     const json = await call({
         service: "simple-email",
-        path: `/accounts/${appId()}/info`,
+        path: `/accounts/${requireAppId()}/info`,
     });
     return {
         account: json.account,
@@ -94,7 +107,7 @@ export async function accountInfo() {
     };
 }
 export async function deleteAccount() {
-    await call({ service: "simple-email", path: `/accounts/${appId()}/delete` });
+    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`
@@ -102,18 +115,22 @@ export async function deleteAccount() {
 export async function setAccountAccess(sendGroup) {
     const json = await call({
         service: "simple-email",
-        path: `/accounts/${appId()}/access/set`,
+        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. */
+ *  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/${appId()}/templates/create`,
+        path: `/accounts/${requireAppId()}/templates/create`,
         body: { name, subject, html },
     });
     return json.template;
@@ -123,7 +140,7 @@ export async function createTemplate(name, subject, html) {
 export async function listTemplates(options = {}) {
     const json = await call({
         service: "simple-email",
-        path: `/accounts/${appId()}/templates/list`,
+        path: `/accounts/${requireAppId()}/templates/list`,
         body: {
             limit: options.limit,
             after_created_time_stamp: options.after_created_time_stamp,
@@ -142,7 +159,7 @@ export async function listAllTemplates() {
 export async function templateInfo(templateNanoid) {
     const json = await call({
         service: "simple-email",
-        path: `/accounts/${appId()}/templates/${templateNanoid}/info`,
+        path: `/accounts/${requireAppId()}/templates/${templateNanoid}/info`,
     });
     return json.template;
 }
@@ -154,7 +171,7 @@ export async function templateInfo(templateNanoid) {
 export async function updateTemplate(templateNanoid, body) {
     const json = await call({
         service: "simple-email",
-        path: `/accounts/${appId()}/templates/${templateNanoid}/update`,
+        path: `/accounts/${requireAppId()}/templates/${templateNanoid}/update`,
         body,
     });
     return json.template;
@@ -162,6 +179,6 @@ export async function updateTemplate(templateNanoid, body) {
 export async function deleteTemplate(templateNanoid) {
     await call({
         service: "simple-email",
-        path: `/accounts/${appId()}/templates/${templateNanoid}/delete`,
+        path: `/accounts/${requireAppId()}/templates/${templateNanoid}/delete`,
     });
 }

package/dist/types.d.ts

@@ -1,3 +1,14 @@
+/** Every `code` the simple_email service can put in a `{ok:false, code, reason}`
+ *  refusal. Exhaustive as of the 2026-09 review, checked against the service's
+ *  `response_json.rs` and `render.rs`.
+ *
+ *  This is the union that most earns its keep: `daily_cap_exceeded` and
+ *  `rate_limited` BOTH answer 429, so a consumer cannot tell a burst limit
+ *  (retry shortly) from the per-app daily send cap (retry tomorrow) 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"
+/** 429, same status as `rate_limited` — the per-app UTC-day send cap. */
+ | "daily_cap_exceeded" | "phone_verification_required" | "phone_verification_unavailable" | "out_of_traffic_credits" | "rate_limited" | "internal";
 /** `address` is derived at read time, never stored, and `null` when the
  *  app it names is gone. */
 export interface Account {
@@ -21,15 +32,23 @@ export interface AccountInfoEnvelope {
 /** What `templates/create` and `templates/update` answer with — no `html`. */
 export interface TemplateMeta {
     template_id: string;
-    /** Not updatable through `updateTemplate` — only `subject` and `html` are. */
-    name: 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`. */
+    name: string | null;
     subject: string;
     created_time_stamp: number;
     updated_time_stamp: number;
 }
-/** What `templates/{t}/info` answers with — `TemplateMeta` plus the body. */
+/** What `templates/{t}/info` answers with — `TemplateMeta` plus the body.
+ *
+ *  `html` is OPTIONAL, not nullable: when the R2 object behind the template is
+ *  missing (the compensated-create residue the service keeps visible so an
+ *  owner can spot it) or its body is not valid UTF-8, the service omits the key
+ *  entirely rather than sending `null`. Test with `"html" in template` or a
+ *  plain falsy check — never assume the body is there. */
 export interface Template extends TemplateMeta {
-    html: string;
+    html?: string;
 }
 export interface SendRow {
     send_id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilely/simple-email",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "A typed client for the simple_email service.",
   "license": "MIT",
   "type": "module",
@@ -21,11 +21,11 @@
     "directory": "npm/simple-email"
   },
   "peerDependencies": {
-    "@pilely/core": "^0.1.0"
+    "@pilely/core": "^0.2.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
     "test": "vitest run"
   }
 }