@pylonsync/functions 0.4.0 → 0.4.1

package/dist/runtime.d.ts

@@ -16,14 +16,6 @@
  */
 import type { DbReader, DbWriter, Llm, Rooms } from "./types";
 export declare function buildDbReader(callId: string, ssrRead?: boolean): DbReader;
-/**
- * Query-function caller for SSR `serverData.fn(name, args)`. Sends the same
- * `run_fn` frame `ctx.runQuery` uses, on the render's call_id — the host's
- * render loop executes the query with the PAGE's auth context (anonymous on
- * public pages) and rejects anything that isn't a query. Legacy rpc() (no
- * op_id) is correct here: concurrent calls queue settle-chained on the one
- * call_id, matching how ctx.runQuery behaves inside a function.
- */
 export declare function buildSsrFnCaller(callId: string): (name: string, args?: Record<string, unknown>) => Promise<unknown>;
 export declare function buildDbWriter(callId: string): DbWriter;
 /**

package/dist/types.d.ts

@@ -550,6 +550,38 @@ export type MemberRow = Record<string, unknown> & {
  * with the caller's identity.
  */
 export type RequireMember = (orgId: string, opts?: RequireMemberOptions) => Promise<MemberRow>;
+/**
+ * Signed file-download URLs. `GET /api/files/<id>` only serves a file to its
+ * owner (or an unscoped admin) — `signedUrl` is the supported way to
+ * authorize a cross-user read: the host mints a short-lived HMAC-signed
+ * path (`/api/files/<id>?sig=...&exp=...`) that the GET handler honors as
+ * an alternative to the owner check, anonymously fetchable (works in
+ * `<img src>` and download links).
+ *
+ * WHO gets a URL is the calling function's responsibility — wrap the mint
+ * in a membership-gated function so authorization stays app-policy-driven:
+ *
+ * ```ts
+ * export default query({
+ *   args: { eventId: v.id("Event"), fileId: v.string() },
+ *   async handler(ctx, args) {
+ *     const event = await ctx.db.get("Event", args.eventId);
+ *     await ctx.requireMember(event.orgId, { role: "organizer" });
+ *     return { url: await ctx.files.signedUrl(args.fileId) };
+ *   },
+ * });
+ * ```
+ */
+export interface Files {
+    /**
+     * Mint a signed download path for a file id. `ttlSecs` defaults to 300
+     * and is capped by the host (24h) — a signed URL is a bearer capability,
+     * so keep lifetimes short.
+     */
+    signedUrl(fileId: string, opts?: {
+        ttlSecs?: number;
+    }): Promise<string>;
+}
 /** Context for query handlers (read-only).
  *
  * NOTE: `ctx.llm` is NOT exposed here. Queries are reactive: a
@@ -573,6 +605,8 @@ export interface QueryCtx<R extends AuthRequirement = "optional"> {
     error(code: string, message: string): Error;
     /** Assert org membership (optionally a role) — see {@link RequireMember}. */
     requireMember: RequireMember;
+    /** Signed file-download URLs — see {@link Files}. */
+    files: Files;
 }
 /** Context for mutation handlers (read + write, transactional). */
 export interface MutationCtx<R extends AuthRequirement = "optional"> {
@@ -588,6 +622,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
     rooms: Rooms;
     /** Per-user OAuth connection registry. */
     connections: Connections;
+    /** Signed file-download URLs — see {@link Files}. */
+    files: Files;
     /** Create a typed error that triggers rollback. */
     error(code: string, message: string): Error;
     /** Assert org membership (optionally a role) — see {@link RequireMember}. */
@@ -608,6 +644,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     connections: Connections;
     /** Environment variables / secrets. */
     env: Record<string, string>;
+    /** Signed file-download URLs — see {@link Files}. */
+    files: Files;
     /** Run a registered query within its own read transaction. */
     runQuery<T = unknown>(fnName: string, args: Record<string, unknown>): Promise<T>;
     /** Run a registered mutation within its own write transaction. */

package/package.json

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

package/src/runtime.ts

@@ -21,6 +21,7 @@ import type {
   EmailAttachment,
   EmailOptions,
   EmailSender,
+  Files,
   Stream,
   Scheduler,
   Llm,
@@ -518,6 +519,19 @@ export function buildDbReader(callId: string, ssrRead = false): DbReader {
  * op_id) is correct here: concurrent calls queue settle-chained on the one
  * call_id, matching how ctx.runQuery behaves inside a function.
  */
+/** `ctx.files` — signed download URLs, minted host-side. */
+function buildFiles(callId: string): Files {
+  return {
+    async signedUrl(fileId, opts) {
+      return rpc(callId, {
+        type: "sign_file_url",
+        file_id: fileId,
+        ttl_secs: opts?.ttlSecs,
+      }) as Promise<string>;
+    },
+  };
+}
+
 export function buildSsrFnCaller(
   callId: string,
 ): (name: string, args?: Record<string, unknown>) => Promise<unknown> {
@@ -991,6 +1005,7 @@ function buildActionCtx(
       (err as any).code = code;
       return err;
     },
+    files: buildFiles(callId),
     // Actions have no ctx.db; read membership via the built-in internal query.
     requireMember: makeRequireMember(auth.userId, (entity, filter) =>
       rpc(callId, {
@@ -1133,6 +1148,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
         requireMember: makeRequireMember(auth.userId, (entity, filter) =>
           reader.query(entity, { ...filter, $limit: 1 }),
         ),
+        files: buildFiles(msg.call_id),
       };
       break;
     }
@@ -1155,6 +1171,7 @@ async function handleCall(msg: CallMessage): Promise<void> {
         requireMember: makeRequireMember(auth.userId, (entity, filter) =>
           writer.query(entity, { ...filter, $limit: 1 }),
         ),
+        files: buildFiles(msg.call_id),
       };
       break;
     }

package/src/types.ts

@@ -644,6 +644,37 @@ export type RequireMember = (
   opts?: RequireMemberOptions,
 ) => Promise<MemberRow>;
 
+/**
+ * Signed file-download URLs. `GET /api/files/<id>` only serves a file to its
+ * owner (or an unscoped admin) — `signedUrl` is the supported way to
+ * authorize a cross-user read: the host mints a short-lived HMAC-signed
+ * path (`/api/files/<id>?sig=...&exp=...`) that the GET handler honors as
+ * an alternative to the owner check, anonymously fetchable (works in
+ * `<img src>` and download links).
+ *
+ * WHO gets a URL is the calling function's responsibility — wrap the mint
+ * in a membership-gated function so authorization stays app-policy-driven:
+ *
+ * ```ts
+ * export default query({
+ *   args: { eventId: v.id("Event"), fileId: v.string() },
+ *   async handler(ctx, args) {
+ *     const event = await ctx.db.get("Event", args.eventId);
+ *     await ctx.requireMember(event.orgId, { role: "organizer" });
+ *     return { url: await ctx.files.signedUrl(args.fileId) };
+ *   },
+ * });
+ * ```
+ */
+export interface Files {
+  /**
+   * Mint a signed download path for a file id. `ttlSecs` defaults to 300
+   * and is capped by the host (24h) — a signed URL is a bearer capability,
+   * so keep lifetimes short.
+   */
+  signedUrl(fileId: string, opts?: { ttlSecs?: number }): Promise<string>;
+}
+
 /** Context for query handlers (read-only).
  *
  * NOTE: `ctx.llm` is NOT exposed here. Queries are reactive: a
@@ -667,6 +698,8 @@ export interface QueryCtx<R extends AuthRequirement = "optional"> {
   error(code: string, message: string): Error;
   /** Assert org membership (optionally a role) — see {@link RequireMember}. */
   requireMember: RequireMember;
+  /** Signed file-download URLs — see {@link Files}. */
+  files: Files;
 }
 
 /** Context for mutation handlers (read + write, transactional). */
@@ -683,6 +716,8 @@ export interface MutationCtx<R extends AuthRequirement = "optional"> {
   rooms: Rooms;
   /** Per-user OAuth connection registry. */
   connections: Connections;
+  /** Signed file-download URLs — see {@link Files}. */
+  files: Files;
   /** Create a typed error that triggers rollback. */
   error(code: string, message: string): Error;
   /** Assert org membership (optionally a role) — see {@link RequireMember}. */
@@ -704,6 +739,8 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   connections: Connections;
   /** Environment variables / secrets. */
   env: Record<string, string>;
+  /** Signed file-download URLs — see {@link Files}. */
+  files: Files;
   /** Run a registered query within its own read transaction. */
   runQuery<T = unknown>(
     fnName: string,