@pya-platform/email 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @pya/email
+
+## 0.1.0
+
+### Minor Changes
+
+- a9ca6bf: Initial release of the Pya platform packages. Extracted from `pyaeats-app`, consumed by `pyaeats-app` (food delivery) and `pyaserv` (services classifieds).
+
+  Each package exposes a Hono router factory (auth/cms/reviews/comments) or a typed helper (email/audit/cf) parameterised over Cloudflare D1 + KV bindings. UI primitives ship as Lit web components on top of `@pya/tokens` (CSS custom properties). See `ROADMAP.md` and `docs/phase-6-rollout.md` for the consumer cutover plan.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@pya-platform/email",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/undeadliner/pya-platform.git"
+  },
+  "type": "module",
+  "description": "Resend wrapper — single sendEmail entry, audit-log on failure, never throws.",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "echo '@pya/email has no tests yet'"
+  },
+  "peerDependencies": {
+    "@cloudflare/workers-types": "^4.20240909.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,87 @@
+// @pya-platform/email — Resend wrapper.
+//
+// Single entry: `sendEmail()`. Never throws — notification failure
+// must not block whatever caller transition already succeeded.
+// Logs to the `audit` stream on failure so it's still observable.
+
+export interface PyaEmailBindings {
+  readonly RESEND_API_KEY?: string
+  readonly EMAIL_DOMAIN?: string
+}
+
+export interface SendEmailParams {
+  readonly env: PyaEmailBindings
+  readonly to: string
+  readonly subject: string
+  readonly text: string
+  readonly html?: string
+  /** Brand name shown in the `From:` header. Defaults to "Pya". */
+  readonly brandName?: string
+  /** Mailbox local-part. Defaults to "noreply". */
+  readonly fromLocal?: string
+}
+
+const senderAddress = (env: PyaEmailBindings, brand: string, local: string): string => {
+  if (env.EMAIL_DOMAIN !== undefined && env.EMAIL_DOMAIN !== '') {
+    return `${brand} <${local}@${env.EMAIL_DOMAIN}>`
+  }
+  // Resend's free sandbox sender — usable until the domain is verified.
+  return `${brand} <onboarding@resend.dev>`
+}
+
+export const sendEmail = async (params: SendEmailParams): Promise<{ readonly ok: boolean }> => {
+  const { env, to, subject, text, html, brandName = 'Pya', fromLocal = 'noreply' } = params
+  const apiKey = env.RESEND_API_KEY ?? ''
+  if (apiKey === '') {
+    console.error(
+      JSON.stringify({
+        stream: 'audit',
+        event: 'email.send_skipped',
+        reason: 'RESEND_API_KEY unset',
+        to,
+        subject,
+      }),
+    )
+    return { ok: false }
+  }
+  const res = await fetch('https://api.resend.com/emails', {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${apiKey}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      from: senderAddress(env, brandName, fromLocal),
+      to,
+      subject,
+      text,
+      ...(html !== undefined ? { html } : {}),
+    }),
+  })
+  if (!res.ok) {
+    const body = await res.text().catch(() => '')
+    console.error(
+      JSON.stringify({
+        stream: 'audit',
+        event: 'email.send_failed',
+        provider: 'resend',
+        status: res.status,
+        to,
+        subject,
+        body: body.slice(0, 500),
+      }),
+    )
+    return { ok: false }
+  }
+  return { ok: true }
+}
+
+/** Minimal HTML escape for embedding user-supplied text in templates.
+ *  Use ONLY where the consumer is the email client, not the browser DOM. */
+export const escapeHtml = (s: string): string =>
+  s
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;')

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "dist",
+    "noEmit": true,
+    "types": ["@cloudflare/workers-types"]
+  },
+  "include": ["src/**/*.ts"]
+}