@pylonsync/functions 0.3.26 → 0.3.28

package/package.json

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

package/src/define.ts

@@ -15,16 +15,32 @@ import type {
 interface QueryDef<TArgs, TReturn> {
   args?: Record<string, Validator>;
   handler: (ctx: QueryCtx, args: TArgs) => Promise<TReturn>;
+  /**
+   * When true, the function is callable only via `ctx.runQuery()`
+   * from another function — never via the public `/api/fn/<name>`
+   * HTTP endpoint. The router refuses external calls with
+   * `404 FN_NOT_FOUND` so probing can't even confirm the name exists.
+   *
+   * Use for queries that are meant as helpers for trusted action /
+   * mutation flows but would be unsafe if any caller could invoke
+   * them directly (e.g. they trust args without re-checking caller
+   * authority).
+   */
+  internal?: boolean;
 }
 
 interface MutationDef<TArgs, TReturn> {
   args?: Record<string, Validator>;
   handler: (ctx: MutationCtx, args: TArgs) => Promise<TReturn>;
+  /** See QueryDef.internal — applies the same way to mutations. */
+  internal?: boolean;
 }
 
 interface ActionDef<TArgs, TReturn> {
   args?: Record<string, Validator>;
   handler: (ctx: ActionCtx, args: TArgs) => Promise<TReturn>;
+  /** See QueryDef.internal — applies the same way to actions. */
+  internal?: boolean;
 }
 
 /**
@@ -49,7 +65,12 @@ interface ActionDef<TArgs, TReturn> {
 export function query<TArgs = Record<string, unknown>, TReturn = unknown>(
   def: QueryDef<TArgs, TReturn>
 ): FnDefinition<TArgs, TReturn> {
-  return { type: "query", args: def.args, handler: def.handler };
+  return {
+    type: "query",
+    args: def.args,
+    handler: def.handler,
+    internal: def.internal,
+  };
 }
 
 /**
@@ -78,7 +99,12 @@ export function query<TArgs = Record<string, unknown>, TReturn = unknown>(
 export function mutation<TArgs = Record<string, unknown>, TReturn = unknown>(
   def: MutationDef<TArgs, TReturn>
 ): FnDefinition<TArgs, TReturn> {
-  return { type: "mutation", args: def.args, handler: def.handler };
+  return {
+    type: "mutation",
+    args: def.args,
+    handler: def.handler,
+    internal: def.internal,
+  };
 }
 
 /**
@@ -105,5 +131,10 @@ export function mutation<TArgs = Record<string, unknown>, TReturn = unknown>(
 export function action<TArgs = Record<string, unknown>, TReturn = unknown>(
   def: ActionDef<TArgs, TReturn>
 ): FnDefinition<TArgs, TReturn> {
-  return { type: "action", args: def.args, handler: def.handler };
+  return {
+    type: "action",
+    args: def.args,
+    handler: def.handler,
+    internal: def.internal,
+  };
 }

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;
@@ -689,6 +715,11 @@ async function main() {
     name,
     fn_type: def.type,
     args_schema: def.args || null,
+    // Whether the function is callable only via runQuery/runMutation/
+    // runAction from another function. The Rust router refuses /api/fn
+    // requests for internal fns; the Bun runtime here doesn't gate
+    // (nested calls go through the same dispatcher).
+    internal: def.internal === true,
   }));
   send({ type: "ready", functions });
 

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. */
@@ -254,6 +277,14 @@ export interface FnDefinition<TArgs = unknown, TReturn = unknown> {
   type: FnType;
   args?: Record<string, Validator>;
   handler: (ctx: any, args: TArgs) => Promise<TReturn>;
+  /**
+   * When true, this function is reachable only via `ctx.runQuery()` /
+   * `ctx.runMutation()` / `ctx.runAction()` from another function —
+   * the public `/api/fn/<name>` endpoint refuses external calls.
+   * The router enforces this; the runtime treats internal == external
+   * for execution.
+   */
+  internal?: boolean;
 }
 
 // ---------------------------------------------------------------------------