@pylonsync/functions 0.3.26 → 0.3.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.3.26",
+  "version": "0.3.27",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/runtime.ts

@@ -18,6 +18,7 @@
 import type {
   DbReader,
   DbWriter,
+  EmailSender,
   Stream,
   Scheduler,
   QueryCtx,
@@ -441,11 +442,33 @@ function buildScheduler(callId: string): Scheduler {
   };
 }
 
+/**
+ * Build the email sender that round-trips through the host runtime.
+ *
+ * Each `send` emits a `send_email` protocol message; the runtime
+ * forwards to whatever transport PYLON_EMAIL_PROVIDER points at and
+ * replies success or error. Errors arrive as thrown exceptions on
+ * the action's await, just like every other RPC. No silent failures.
+ */
+function buildEmail(callId: string): EmailSender {
+  return {
+    async send(to, subject, body) {
+      await rpc(callId, {
+        type: "send_email",
+        to,
+        subject,
+        body,
+      });
+    },
+  };
+}
+
 function buildActionCtx(
   callId: string,
   auth: AuthInfo,
   stream: Stream,
   scheduler: Scheduler,
+  email: EmailSender,
   request?: unknown
 ): ActionCtx {
   // The host sends `request` as snake_case JSON (`raw_body`); normalize it
@@ -465,6 +488,7 @@ function buildActionCtx(
     auth,
     stream,
     scheduler,
+    email,
     env: process.env as Record<string, string>,
     async runQuery(fnName, args) {
       return rpc(callId, {
@@ -544,6 +568,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
 
   const stream = buildStream(msg.call_id);
   const scheduler = buildScheduler(msg.call_id);
+  const email = buildEmail(msg.call_id);
 
   // Normalize the Rust-side auth envelope (snake_case) to the camelCase
   // shape that AuthInfo documents. Handlers read `ctx.auth.userId`; the
@@ -597,6 +622,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
         auth,
         stream,
         scheduler,
+        email,
         (msg as unknown as { request?: unknown }).request,
       );
       break;

package/src/types.ts

@@ -171,6 +171,27 @@ export interface Scheduler {
   cancel(scheduleId: string): Promise<void>;
 }
 
+/**
+ * Transactional email transport.
+ *
+ * Sends through whatever provider the runtime is configured for
+ * (PYLON_EMAIL_PROVIDER env var → SendGrid / Resend / Stack0 / SMTP /
+ * webhook). Available on action ctx only — sending email is external
+ * I/O, not allowed in mutation transactions.
+ *
+ * The runtime owns provider config + credentials; functions only
+ * supply the (to, subject, body) tuple. Failures are surfaced as
+ * thrown errors; on success the return is void.
+ *
+ * Use cases: invite emails, password-reset hand-offs, notifications,
+ * digest reports. NOT for marketing email — those should go through
+ * a dedicated bulk transport, not the transactional path.
+ */
+export interface EmailSender {
+  /** Send a plain-text email. `to` is a single address. */
+  send(to: string, subject: string, body: string): Promise<void>;
+}
+
 // ---------------------------------------------------------------------------
 // Context objects — what handlers receive
 // ---------------------------------------------------------------------------
@@ -200,6 +221,8 @@ export interface ActionCtx {
   auth: AuthInfo;
   stream: Stream;
   scheduler: Scheduler;
+  /** Send transactional email via the runtime's configured provider. */
+  email: EmailSender;
   /** Environment variables / secrets. */
   env: Record<string, string>;
   /** Run a registered query within its own read transaction. */