@pylonsync/functions 0.22.6 → 0.22.8

package/dist/index.d.ts

@@ -27,4 +27,4 @@ export type { WorkflowDefinition, WorkflowRun, WorkflowRunRequest, WorkflowRunne
 export { resetDb, installTestIsolation } from "./testing";
 export { slugifyName, availableSlug } from "./slugify";
 export type { SsrResponse, SsrCookieOptions, SsrMetadata, Sitemap, SitemapEntry, Robots, RobotsRule, } from "./ssr-runtime";
-export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, Shards, ShardsReader, ShardsWriter, ShardInfo, ShardTransfer, MemberRow, Workflows, WorkflowRunSummary, WorkflowRunStatus, Audit, AuditLog, AuditEntry, Agents, AgentRunOptions, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainRecord, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, } from "./types";
+export type { QueryCtx, MutationCtx, ActionCtx, DbReader, DbWriter, Stream, Scheduler, AuthInfo, AuthMode, AuthRequirement, FnDefinition, Validator, AnyValidator, ValidatorSchema, InferValidator, InferArgs, RequireMember, RequireMemberOptions, Shards, ShardsReader, ShardsWriter, ShardInfo, ShardTransfer, MemberRow, Workflows, WorkflowRunSummary, WorkflowRunStatus, Audit, AuditLog, AuditEntry, Agents, AgentRunOptions, VectorSearchQuery, VectorSearchResult, SearchResult, PaginationResult, Llm, LlmMessage, LlmContentBlock, LlmTool, LlmCompleteRequest, LlmCompleteResponse, LlmStreamEvent, Rooms, Domains, TenantDomainResult, TenantDomainRecord, TenantDomainDns, DomainAvailability, DomainContact, RegisterDomainOptions, RegisteredDomainResult, Files, ActionFiles, StoreFileOptions, StoredFile, } from "./types";

package/dist/types.d.ts

@@ -890,6 +890,44 @@ export interface Files {
         ttlSecs?: number;
     }): Promise<string>;
 }
+/** Options for {@link ActionFiles.store}. */
+export interface StoreFileOptions {
+    /** File name, 1-255 characters, no path separators. */
+    name: string;
+    /** Defaults to `application/octet-stream`. */
+    contentType?: string;
+    /** Readable by anyone, signed in or not. Defaults to false. */
+    public?: boolean;
+}
+/** A file written by {@link ActionFiles.store}. */
+export interface StoredFile {
+    id: string;
+    /** Where the file is served: `/api/files/<id>` or the storage CDN URL. */
+    url: string;
+    size: number;
+}
+/**
+ * `ctx.files` in an action: the read-side {@link Files} plus writes to the
+ * app's file storage (the backend `/api/files` uses). Writes run only in
+ * actions: a stored or deleted file cannot roll back with a query or
+ * mutation.
+ *
+ * A stored file is owned by the calling user and tenant, as if that user
+ * had uploaded it. With no user (a scheduled job, a public webhook) the
+ * file is system-owned: readable through {@link Files.signedUrl}, by an
+ * unscoped admin, or by anyone when `public` is set.
+ */
+export interface ActionFiles extends Files {
+    /**
+     * Store bytes as a new file. At most 25 MiB, or `PYLON_MAX_UPLOAD_BYTES`
+     * when that is lower.
+     */
+    store(data: Uint8Array | ArrayBuffer | string, opts: StoreFileOptions): Promise<StoredFile>;
+    /** Delete a stored file. `deleted` is false when it did not exist. */
+    delete(fileId: string): Promise<{
+        deleted: boolean;
+    }>;
+}
 /**
  * Shard tickets: short-lived, signed permission to join one realtime shard,
  * with claims the shard's authorization hooks read without a database
@@ -1312,7 +1350,7 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
     /** Environment variables / secrets. */
     env: Record<string, string>;
     /** Signed file-download URLs — see {@link Files}. */
-    files: Files;
+    files: ActionFiles;
     /** Shard tickets, reads, and start/stop — see {@link Shards}. */
     shards: Shards;
     /** Run a registered query within its own read transaction. */

package/package.json

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

package/src/index.ts

@@ -114,4 +114,9 @@ export type {
   DomainContact,
   RegisterDomainOptions,
   RegisteredDomainResult,
+  // File storage from functions.
+  Files,
+  ActionFiles,
+  StoreFileOptions,
+  StoredFile,
 } from "./types";

package/src/runtime.ts

@@ -22,6 +22,8 @@ import type {
   EmailOptions,
   EmailSender,
   Files,
+  ActionFiles,
+  StoredFile,
   Shards,
   ShardInfo,
   ShardTransfer,
@@ -640,6 +642,56 @@ function buildFiles(callId: string): Files {
   };
 }
 
+/** `ctx.files` in an action: {@link buildFiles} plus store and delete. */
+function buildActionFiles(callId: string): ActionFiles {
+  return {
+    ...buildFiles(callId),
+    async store(data, opts) {
+      const size =
+        typeof data === "string" ? new TextEncoder().encode(data).byteLength : data.byteLength;
+      // Refused here, before encoding: a larger message would exceed the
+      // runner's frame limit and never reach the host's check.
+      if (size > FILES_STORE_MAX_BYTES) {
+        const err = new Error(
+          `ctx.files.store accepts at most ${FILES_STORE_MAX_BYTES} bytes (got ${size})`,
+        );
+        (err as { code?: string }).code = "FILE_TOO_LARGE";
+        throw err;
+      }
+      return rpc(callId, {
+        type: "files_op",
+        op: "store",
+        name: opts.name,
+        content_type: opts.contentType ?? null,
+        public: opts.public ?? false,
+        data_base64: toBase64(data),
+      }) as Promise<StoredFile>;
+    },
+    async delete(fileId) {
+      return rpc(callId, {
+        type: "files_op",
+        op: "delete",
+        file_id: fileId,
+      }) as Promise<{ deleted: boolean }>;
+    },
+  };
+}
+
+/** Largest `ctx.files.store` payload. Mirrors the host's
+ *  FILES_STORE_MAX_BYTES; `PYLON_MAX_UPLOAD_BYTES` can lower the host's. */
+const FILES_STORE_MAX_BYTES = 25 * 1024 * 1024;
+
+/** Base64 of bytes, or of a string's UTF-8 encoding. */
+function toBase64(data: Uint8Array | ArrayBuffer | string): string {
+  const bytes =
+    typeof data === "string"
+      ? new TextEncoder().encode(data)
+      : data instanceof ArrayBuffer
+        ? new Uint8Array(data)
+        : data;
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
+}
+
 export function buildSsrFnCaller(
   callId: string,
 ): (name: string, args?: Record<string, unknown>) => Promise<unknown> {
@@ -1340,7 +1392,7 @@ function buildActionCtx(
       (err as any).code = code;
       return err;
     },
-    files: buildFiles(callId),
+    files: buildActionFiles(callId),
     shards: buildShards(callId),
     // Actions have no ctx.db; read membership via the built-in internal query.
     requireMember: makeRequireMember(auth.userId, (entity, filter) =>
@@ -1532,7 +1584,10 @@ async function handleCall(msg: CallMessage): Promise<void> {
         requireMember: makeRequireMember(auth.userId, (entity, filter) =>
           reader.query(entity, { ...filter, $limit: 1 }),
         ),
-        files: buildFiles(msg.call_id),
+        // Typed as read-only `Files`; `store`/`delete` still exist at runtime
+        // so a call from a query or mutation gets the host's
+        // FILES_WRITE_NOT_ALLOWED instead of a TypeError.
+        files: buildActionFiles(msg.call_id),
         shards: buildShards(msg.call_id),
       };
       break;
@@ -1558,7 +1613,10 @@ async function handleCall(msg: CallMessage): Promise<void> {
         requireMember: makeRequireMember(auth.userId, (entity, filter) =>
           writer.query(entity, { ...filter, $limit: 1 }),
         ),
-        files: buildFiles(msg.call_id),
+        // Typed as read-only `Files`; `store`/`delete` still exist at runtime
+        // so a call from a query or mutation gets the host's
+        // FILES_WRITE_NOT_ALLOWED instead of a TypeError.
+        files: buildActionFiles(msg.call_id),
         shards: buildShards(msg.call_id),
       };
       break;

package/src/types.ts

@@ -992,6 +992,48 @@ export interface Files {
   signedUrl(fileId: string, opts?: { ttlSecs?: number }): Promise<string>;
 }
 
+/** Options for {@link ActionFiles.store}. */
+export interface StoreFileOptions {
+  /** File name, 1-255 characters, no path separators. */
+  name: string;
+  /** Defaults to `application/octet-stream`. */
+  contentType?: string;
+  /** Readable by anyone, signed in or not. Defaults to false. */
+  public?: boolean;
+}
+
+/** A file written by {@link ActionFiles.store}. */
+export interface StoredFile {
+  id: string;
+  /** Where the file is served: `/api/files/<id>` or the storage CDN URL. */
+  url: string;
+  size: number;
+}
+
+/**
+ * `ctx.files` in an action: the read-side {@link Files} plus writes to the
+ * app's file storage (the backend `/api/files` uses). Writes run only in
+ * actions: a stored or deleted file cannot roll back with a query or
+ * mutation.
+ *
+ * A stored file is owned by the calling user and tenant, as if that user
+ * had uploaded it. With no user (a scheduled job, a public webhook) the
+ * file is system-owned: readable through {@link Files.signedUrl}, by an
+ * unscoped admin, or by anyone when `public` is set.
+ */
+export interface ActionFiles extends Files {
+  /**
+   * Store bytes as a new file. At most 25 MiB, or `PYLON_MAX_UPLOAD_BYTES`
+   * when that is lower.
+   */
+  store(
+    data: Uint8Array | ArrayBuffer | string,
+    opts: StoreFileOptions,
+  ): Promise<StoredFile>;
+  /** Delete a stored file. `deleted` is false when it did not exist. */
+  delete(fileId: string): Promise<{ deleted: boolean }>;
+}
+
 /**
  * Shard tickets: short-lived, signed permission to join one realtime shard,
  * with claims the shard's authorization hooks read without a database
@@ -1436,7 +1478,7 @@ export interface ActionCtx<R extends AuthRequirement = "optional"> {
   /** Environment variables / secrets. */
   env: Record<string, string>;
   /** Signed file-download URLs — see {@link Files}. */
-  files: Files;
+  files: ActionFiles;
   /** Shard tickets, reads, and start/stop — see {@link Shards}. */
   shards: Shards;
   /** Run a registered query within its own read transaction. */