@pilely/simple-email 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pilely
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# `@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
+```
+
+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.
+
+## Where the app id lives
+
+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
+
+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.
+
+## Status
+
+This is a pre-1.0 package and moves with the platform. Nothing here is
+published to the registry yet. Zero runtime dependencies.

package/dist/index.d.ts

@@ -0,0 +1,92 @@
+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";
+/** `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. */
+export declare function createTemplate(name: string, 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

@@ -0,0 +1,167 @@
+// @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 } from "@pilely/core";
+// ── 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: appId(), to: input.to, template_id: input.template_id, variables: input.variables }
+        : { app_id: appId(), 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: appId(),
+            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: appId() };
+    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/${appId()}/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/${appId()}/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/${appId()}/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. */
+export async function createTemplate(name, subject, html) {
+    const json = await call({
+        service: "simple-email",
+        path: `/accounts/${appId()}/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/${appId()}/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/${appId()}/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/${appId()}/templates/${templateNanoid}/update`,
+        body,
+    });
+    return json.template;
+}
+export async function deleteTemplate(templateNanoid) {
+    await call({
+        service: "simple-email",
+        path: `/accounts/${appId()}/templates/${templateNanoid}/delete`,
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+/** `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;
+    created_time_stamp: number;
+}
+/** `daily_cap`'s three siblings are nullable and sit BESIDE `account`, not
+ *  inside it — the whole reason an app calls `accountInfo`. */
+export interface AccountInfoEnvelope {
+    account: Account;
+    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 {
+    template_id: string;
+    /** Not updatable through `updateTemplate` — only `subject` and `html` are. */
+    name: string;
+    subject: string;
+    created_time_stamp: number;
+    updated_time_stamp: number;
+}
+/** What `templates/{t}/info` answers with — `TemplateMeta` plus the body. */
+export interface Template extends TemplateMeta {
+    html: string;
+}
+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;
+    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;
+}
+export interface TemplateCursor {
+    after_created_time_stamp: number;
+    after_template_id: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@pilely/simple-email",
+  "version": "0.1.0",
+  "description": "A typed client for the simple_email service.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": ["dist", "README.md", "LICENSE"],
+  "publishConfig": { "access": "public" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pile-ly/reference-code.git",
+    "directory": "npm/simple-email"
+  },
+  "peerDependencies": {
+    "@pilely/core": "^0.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}