cf-send-email 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 binochoi
+
+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

@@ -1,3 +1,93 @@
-# Temporary Holding Version
+# cf-send-email
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Send **transactional emails from Cloudflare Workers** with the `send_email` binding (Cloudflare Email Service / Email Sending), and render **email-client-safe HTML + plain-text** bodies with inline styles and table layout. Covers the common auth mails (password reset, OTP / verification code, email verification, magic link, invites) in a tiny, zero-dependency TypeScript package that works with plain Workers or Hono.
+
+## Why
+
+Sending mail from a Cloudflare Worker means passing a structured `{ to, from, subject, html, text }` object to the `send_email` binding. Email clients can't be trusted with `<style>` tags, external CSS, or modern layout, so the body has to be inline styles and simple tables. That "binding wrapper + HTML shell" skeleton is the same in every project, so it lives here.
+
+- **`sendEmail`** builds the `From` address from env and sends through the binding. Failures are logged and re-thrown, so an auth flow never reports "email sent" when nothing was delivered.
+- **`renderEmail`** turns a structured `EmailBody` (heading, paragraphs, code, button, footnote) into `{ subject, html, text }`. All values are HTML-escaped.
+- No dependency on the types generated by `wrangler types`: the package defines the minimal binding interface itself.
+
+Copy (subject, wording, language) stays in your own templates. This package only renders and sends.
+
+## Use cases
+
+- Password reset emails with a button and a fallback URL
+- Sign-up / sign-in OTP and verification code emails (the code is shown in a large box)
+- Email address verification, team invites, and system notifications
+- Auth callbacks (e.g. better-auth) in a Cloudflare Workers + Hono API
+
+## Install
+
+```sh
+npm install cf-send-email
+```
+
+## Usage
+
+Add the binding to `wrangler.jsonc`:
+
+```jsonc
+{
+  "vars": {
+    "EMAIL_FROM": "no-reply@mail.example.com",
+    "EMAIL_FROM_NAME": "My App"
+  },
+  "send_email": [
+    { "name": "EMAIL", "allowed_sender_addresses": ["no-reply@mail.example.com"] }
+  ]
+}
+```
+
+Render and send:
+
+```ts
+import { renderEmail, sendEmail, type EmailBody, type EmailEnv } from "cf-send-email";
+
+const body: EmailBody = {
+  subject: "Reset your password",
+  heading: "Reset your password",
+  paragraphs: ["We received a request to reset your password."],
+  action: { label: "Reset", url },
+  actionFallbackNote: "If the button doesn't work, open this link:",
+  footnote: "If you didn't request this, ignore this email.",
+};
+
+// With brandName, a top label and a text signature are rendered (omitted otherwise).
+const rendered = renderEmail(body, "My App");
+
+// env must provide the { EMAIL, EMAIL_FROM, EMAIL_FROM_NAME } binding and vars.
+await sendEmail(env, { to: "user@example.com", ...rendered });
+```
+
+For an OTP email, pass `code` instead of (or along with) `action`:
+
+```ts
+renderEmail({
+  subject: "Your verification code",
+  heading: "Verify your email",
+  paragraphs: ["Enter this code to finish signing up."],
+  code: "482913",
+  footnote: "This code expires in 10 minutes.",
+});
+```
+
+## API
+
+| Symbol | Description |
+| --- | --- |
+| `renderEmail(body, brandName?)` | `EmailBody` → `{ subject, html, text }`. `brandName` is optional |
+| `sendEmail(env, { to, ...rendered })` | Sends through the `send_email` binding. Logs and re-throws on failure |
+| `EmailBody` | Structured body (`subject` / `heading` / `paragraphs` / `code` / `action` / `actionFallbackNote` / `footnote`) |
+| `EmailEnv` | `{ EMAIL, EMAIL_FROM, EMAIL_FROM_NAME }` |
+| `EmailSender` / `EmailSendMessage` / `EmailAddress` / `RenderedEmail` | Binding and message types |
+
+## Build
+
+Built with `obuild`. `prepare` runs `obuild --stub`, which writes a stub `dist` that points at the source, so workspace consumers can use it without a build step. Run `pnpm build:dist` for a real build before publishing.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,62 @@
+/** From/To 에 쓰는 이메일 주소. Email Sending 바인딩은 from 에 { email, name } 을 받는다. */
+export interface EmailAddress {
+  email: string;
+  name?: string;
+}
+/** Email Sending 바인딩 `.send()` 가 받는 구조화 메시지. */
+export interface EmailSendMessage {
+  to: string;
+  from: EmailAddress;
+  subject: string;
+  html: string;
+  text: string;
+}
+/** `send_email` 바인딩 런타임 타입(필요한 부분만). */
+export interface EmailSender {
+  send(message: EmailSendMessage): Promise<unknown>;
+}
+/** sendEmail 이 발신 정보를 조립하는 데 필요한 env 조각. */
+export interface EmailEnv {
+  EMAIL: EmailSender;
+  /** 발신 주소(예: no-reply@mail.example.com). allowed_sender_addresses 와 일치해야 한다. */
+  EMAIL_FROM: string;
+  /** 발신 표시명. */
+  EMAIL_FROM_NAME: string;
+}
+/** 렌더된 이메일 한 통(수신자 제외). 템플릿 함수들이 반환한다. */
+export interface RenderedEmail {
+  subject: string;
+  html: string;
+  text: string;
+}
+/**
+ * 트랜잭션 메일 한 통을 보낸다. From 은 env 에서 조립한다.
+ * 실패는 로깅 후 다시 던진다 — 인증 콜백(비밀번호 재설정 등)이 조용히 성공한 것처럼
+ * 보이지 않도록(사용자는 메일을 못 받는데 UI 는 "메일 보냈어요" 를 띄우는 상황 방지).
+ */
+export declare function sendEmail(env: EmailEnv, message: {
+  to: string;
+} & RenderedEmail): Promise<void>;
+/** 한 통의 본문 구조. 호출자가 언어별 문자열을 채워 만든다. */
+export interface EmailBody {
+  /** 브라우저 제목이자 메일 제목(subject). */
+  subject: string;
+  /** 본문 상단 큰 제목 줄. */
+  heading: string;
+  /** 버튼 위 문단들. */
+  paragraphs: string[];
+  /** 크게 보여줄 인증 코드(있으면). 문단 아래, 버튼 위에 박스로 렌더한다. */
+  code?: string;
+  /** 주요 행동 버튼(있으면). */
+  action?: {
+    label: string;
+    url: string;
+  };
+  /** 버튼이 안 눌릴 때 붙이는 안내 문구(뒤에 URL 을 그대로 덧붙인다). */
+  actionFallbackNote?: string;
+  /** 맨 아래 회색 안내(예: 본인이 요청하지 않았다면 무시하세요). */
+  footnote: string;
+}
+/** EmailBody → 발송 가능한 { subject, html, text }. `brandName` 을 주면 상단 라벨과
+ * 텍스트 서명("— brand")으로 렌더하고, 없으면 브랜드 표기를 생략한다. */
+export declare function renderEmail(body: EmailBody, brandName?: string): RenderedEmail;

package/dist/index.mjs

@@ -0,0 +1,78 @@
+async function sendEmail(env, message) {
+	try {
+		await env.EMAIL.send({
+			to: message.to,
+			from: {
+				email: env.EMAIL_FROM,
+				name: env.EMAIL_FROM_NAME
+			},
+			subject: message.subject,
+			html: message.html,
+			text: message.text
+		});
+	} catch (error) {
+		console.error("[email] send failed", error);
+		throw error;
+	}
+}
+const escapeHtml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+const escapeAttr = (value) => value.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+function renderHtml(body, brandName) {
+	const paragraphsHtml = body.paragraphs.map((line) => `<p style="margin:0 0 16px;font-size:14px;line-height:1.6;color:#1f2937;">${escapeHtml(line)}</p>`).join("");
+	const brandHtml = brandName ? `<p style="margin:0 0 24px;font-size:16px;font-weight:700;color:#111827;">${escapeHtml(brandName)}</p>` : "";
+	const codeHtml = body.code ? `<p style="margin:24px 0;padding:16px;border-radius:8px;background:#f3f4f6;text-align:center;font-family:'SFMono-Regular',Consolas,'Liberation Mono',Menlo,monospace;font-size:28px;font-weight:700;letter-spacing:8px;color:#111827;">${escapeHtml(body.code)}</p>` : "";
+	const actionHtml = body.action ? `<p style="margin:24px 0;">
+         <a href="${escapeAttr(body.action.url)}"
+            style="display:inline-block;padding:10px 20px;border-radius:8px;background:#111827;color:#ffffff;font-size:14px;font-weight:600;text-decoration:none;">
+           ${escapeHtml(body.action.label)}
+         </a>
+       </p>` : "";
+	const fallbackHtml = body.actionFallbackNote && body.action ? `<p style="margin:0 0 16px;font-size:12px;line-height:1.6;color:#6b7280;word-break:break-all;">${escapeHtml(body.actionFallbackNote)}<br/><a href="${escapeAttr(body.action.url)}" style="color:#2563eb;">${escapeHtml(body.action.url)}</a></p>` : "";
+	return `<!doctype html>
+<html>
+  <body style="margin:0;padding:0;background:#f3f4f6;">
+    <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="background:#f3f4f6;padding:24px 0;">
+      <tr>
+        <td align="center">
+          <table role="presentation" width="100%" cellpadding="0" cellspacing="0" style="max-width:440px;background:#ffffff;border-radius:12px;padding:32px;">
+            <tr>
+              <td>
+                ${brandHtml}
+                <h1 style="margin:0 0 16px;font-size:18px;font-weight:600;color:#111827;">${escapeHtml(body.heading)}</h1>
+                ${paragraphsHtml}
+                ${codeHtml}
+                ${actionHtml}
+                ${fallbackHtml}
+                <p style="margin:24px 0 0;font-size:12px;line-height:1.6;color:#9ca3af;">${escapeHtml(body.footnote)}</p>
+              </td>
+            </tr>
+          </table>
+        </td>
+      </tr>
+    </table>
+  </body>
+</html>`;
+}
+function renderText(body, brandName) {
+	const actionLines = body.action ? ["", `${body.action.label}: ${body.action.url}`] : [];
+	const codeLines = body.code ? ["", body.code] : [];
+	const brandLines = brandName ? ["", `— ${brandName}`] : [];
+	return [
+		body.heading,
+		"",
+		...body.paragraphs,
+		...codeLines,
+		...actionLines,
+		"",
+		body.footnote,
+		...brandLines
+	].join("\n");
+}
+function renderEmail(body, brandName) {
+	return {
+		subject: body.subject,
+		html: renderHtml(body, brandName),
+		text: renderText(body, brandName)
+	};
+}
+export { renderEmail, sendEmail };

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "cf-send-email",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Send transactional emails from Cloudflare Workers via the send_email binding (Cloudflare Email Service), with a zero-dependency renderer for email-client-safe inline-styled HTML and plain-text bodies (password reset, OTP, verification, invites).",
+  "type": "module",
+  "license": "MIT",
+  "author": "binochoi",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/binochoi/cf-send-email.git"
+  },
+  "homepage": "https://github.com/binochoi/cf-send-email#readme",
+  "bugs": {
+    "url": "https://github.com/binochoi/cf-send-email/issues"
+  },
+  "keywords": [
+    "cf-send-email",
+    "cloudflare",
+    "cloudflare-workers",
+    "cloudflare-email",
+    "cloudflare-email-service",
+    "email-sending",
+    "send-email",
+    "send_email",
+    "workers",
+    "wrangler",
+    "edge",
+    "serverless",
+    "email",
+    "transactional-email",
+    "html-email",
+    "email-template",
+    "inline-css",
+    "plain-text-email",
+    "password-reset",
+    "otp",
+    "verification-code",
+    "email-verification",
+    "magic-link",
+    "hono",
+    "typescript",
+    "zero-dependency"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "obuild": "^0.4.38",
+    "oxlint": "^1.67.0",
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "build:dist": "obuild",
+    "release": "pnpm build:dist && pnpm publish --ignore-scripts",
+    "clean": "rm -rf dist node_modules .turbo",
+    "lint": "oxlint ./src && tsc --noEmit"
+  }
 }