@peers-app/peers-sdk 0.29.1 → 0.30.0

package/dist/contracts/contract-resolvers.js

@@ -211,6 +211,7 @@ async function isSelfTrustedContractCaller(userContext, remoteIdentity) {
 }
 const permissionDenied = (call, reason) => new Error(`Permission denied: ${call.member} '${call.name}'.${call.operation} on contract ${call.contractId}${reason ? ` (${reason})` : ""}`);
 const localOnlyContractIds = new Set([
+    system_ids_1.filesContractId,
     system_ids_1.groupMembersContractId,
     system_ids_1.hostToolsContractId,
     system_ids_1.desktopToolsContractId,

package/dist/contracts/index.d.ts

@@ -19,6 +19,7 @@ export * from "./system/app-updates-contract";
 export { CONTRACT_CATALOG_VERSION, contractCatalogProviderPackageId, getContractCatalogDefinition, type IContractCatalogConsumer, type IContractDefinitionWithPolicy, type IContractProviderInfo, type IContractToolPolicy, type IExposedContractInfo, type IExposedToolInfo, type IGetContractDefinitionInput, type IListContractProvidersInput, } from "./system/contract-catalog-contract";
 export * from "./system/desktop-tools-contract";
 export { DEVICE_OPERATIONS_CONTRACT_VERSION, DEVICE_OPERATIONS_MAX_QUERY_LENGTH, DEVICE_OPERATIONS_MAX_RESULT_BYTES, DEVICE_OPERATIONS_MAX_ROWS, DEVICE_OPERATIONS_MAX_TOOLS, type DeviceOperationCapability, deviceOperationsProviderPackageId, deviceOperationsToolIds, getDeviceOperationsContractDefinition, type IDeviceDatabaseQueryInput, type IDeviceDatabaseQueryResult, type IDeviceOperationStatus, type IDeviceToolListInput, type IDeviceToolLookupInput, type IDeviceToolLookupResult, type IDeviceToolRunInput, } from "./system/device-operations-contract";
+export * from "./system/files-contract";
 export * from "./system/group-members-contract";
 export * from "./system/host-shell-contract";
 export * from "./system/host-tools-contract";

package/dist/contracts/index.js

@@ -105,6 +105,7 @@ Object.defineProperty(exports, "DEVICE_OPERATIONS_MAX_TOOLS", { enumerable: true
 Object.defineProperty(exports, "deviceOperationsProviderPackageId", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsProviderPackageId; } });
 Object.defineProperty(exports, "deviceOperationsToolIds", { enumerable: true, get: function () { return device_operations_contract_1.deviceOperationsToolIds; } });
 Object.defineProperty(exports, "getDeviceOperationsContractDefinition", { enumerable: true, get: function () { return device_operations_contract_1.getDeviceOperationsContractDefinition; } });
+__exportStar(require("./system/files-contract"), exports);
 __exportStar(require("./system/group-members-contract"), exports);
 __exportStar(require("./system/host-shell-contract"), exports);
 __exportStar(require("./system/host-tools-contract"), exports);

package/dist/contracts/system/files-contract.d.ts

@@ -0,0 +1,6 @@
+import type { IContractDefinition } from "../types";
+export * from "./files-shared";
+/** Version of the local-only System Files contract. */
+export declare const FILES_CONTRACT_VERSION = 1;
+/** Return the System Files v1 declaration. Tool identities are derived by the catalog. */
+export declare function getFilesContractDefinition(): IContractDefinition;

package/dist/contracts/system/files-contract.js

@@ -0,0 +1,85 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILES_CONTRACT_VERSION = void 0;
+exports.getFilesContractDefinition = getFilesContractDefinition;
+const system_ids_1 = require("../../system-ids");
+const field_type_1 = require("../../types/field-type");
+const system_contracts_1 = require("../system-contracts");
+const files_shared_1 = require("./files-shared");
+__exportStar(require("./files-shared"), exports);
+/** Version of the local-only System Files contract. */
+exports.FILES_CONTRACT_VERSION = 1;
+const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
+/** Return the System Files v1 declaration. Tool identities are derived by the catalog. */
+function getFilesContractDefinition() {
+    const size = `${files_shared_1.FILES_MAX_CALL_BYTES / (1024 * 1024)} MiB`;
+    return {
+        contractId: system_ids_1.filesContractId,
+        version: exports.FILES_CONTRACT_VERSION,
+        devTag: "dev",
+        name: "System Files",
+        description: "Save and read files in the caller's own data context.",
+        tables: [],
+        observables: [],
+        events: [],
+        tools: [
+            {
+                name: "save",
+                usageDescription: `Save a new file of up to ${size} in this context and return its id.`,
+                inputFields: [
+                    field("name", field_type_1.FieldType.string, "File name, such as avatar.jpg."),
+                    field("mimeType", field_type_1.FieldType.string, "MIME type, such as image/jpeg.", {
+                        optional: true,
+                    }),
+                    field("bytes", field_type_1.FieldType.blob, `The whole file, at most ${size}.`),
+                ],
+                outputFields: [
+                    field("fileId", field_type_1.FieldType.id, "Id to read the file with."),
+                    field("name", field_type_1.FieldType.string, "File name."),
+                    field("fileSize", field_type_1.FieldType.number, "Size in bytes."),
+                    field("fileHash", field_type_1.FieldType.string, "Hash of the file's chunk hashes."),
+                    field("mimeType", field_type_1.FieldType.string, "MIME type.", { optional: true }),
+                ],
+            },
+            {
+                name: "read",
+                usageDescription: `Read up to ${size} of a file in this context, from an offset.`,
+                inputFields: [
+                    field("fileId", field_type_1.FieldType.id, "File to read."),
+                    field("offset", field_type_1.FieldType.number, "First byte to return. Defaults to 0.", {
+                        optional: true,
+                    }),
+                    field("length", field_type_1.FieldType.number, `Most bytes to return. Defaults to the rest, up to ${size}.`, {
+                        optional: true,
+                    }),
+                ],
+                outputFields: [
+                    field("bytes", field_type_1.FieldType.blob, "The bytes read."),
+                    field("fileSize", field_type_1.FieldType.number, "Size of the whole file."),
+                    field("name", field_type_1.FieldType.string, "File name."),
+                    field("mimeType", field_type_1.FieldType.string, "MIME type.", { optional: true }),
+                ],
+            },
+        ],
+    };
+}
+(0, system_contracts_1.registerSystemContract)({
+    providerPackageId: system_ids_1.peersSystemPackageId,
+    contractId: system_ids_1.filesContractId,
+    version: exports.FILES_CONTRACT_VERSION,
+    getDefinition: getFilesContractDefinition,
+});

package/dist/contracts/system/files-shared.d.ts

@@ -0,0 +1,59 @@
+import type { IContractConsumerBase } from "../contract-proxy";
+/** Largest file `save` accepts, and the most bytes one `read` returns. */
+export declare const FILES_MAX_CALL_BYTES: number;
+/** Input for {@link IFilesConsumer tools.save}. */
+export interface IFilesSaveInput {
+    /** File name, such as `avatar.jpg`. Shown to people; not a path. */
+    name: string;
+    /** MIME type, such as `image/jpeg`, returned by later reads. */
+    mimeType?: string;
+    /** The whole file, at most {@link FILES_MAX_CALL_BYTES}. */
+    bytes: Uint8Array;
+}
+/** A saved file's description. Keep `fileId` to read it again. */
+export interface IFilesSaveResult {
+    fileId: string;
+    name: string;
+    fileSize: number;
+    /** Hash of the file's chunk hashes; equal bytes give an equal hash. */
+    fileHash: string;
+    mimeType?: string;
+}
+/** Input for {@link IFilesConsumer tools.read}. */
+export interface IFilesReadInput {
+    fileId: string;
+    /** First byte to return. Defaults to 0. */
+    offset?: number;
+    /**
+     * Most bytes to return: the rest of the file, up to {@link FILES_MAX_CALL_BYTES}, when
+     * omitted. A larger `length` is refused; read a larger file in ranges, or with
+     * {@link readWholeFile}.
+     */
+    length?: number;
+}
+/** Bytes read from a file, with its description. */
+export interface IFilesReadResult {
+    bytes: Uint8Array;
+    /** Size of the whole file, so a caller knows how many ranges to read. */
+    fileSize: number;
+    name: string;
+    mimeType?: string;
+}
+/**
+ * Consumer shape for System Files: save and read files in the caller's own data context.
+ * Files sync to the context's other devices, as every file does.
+ */
+export interface IFilesConsumer extends IContractConsumerBase {
+    tools: {
+        save(input: IFilesSaveInput): Promise<IFilesSaveResult>;
+        read(input: IFilesReadInput): Promise<IFilesReadResult>;
+    };
+}
+/**
+ * Read a whole file through System Files, in ranges of {@link FILES_MAX_CALL_BYTES}.
+ *
+ * @param read - The consumer's `read` tool, from a package, a screen or the host.
+ * @param fileId - File to read.
+ * @returns The file's bytes, name and MIME type.
+ */
+export declare function readWholeFile(read: IFilesConsumer["tools"]["read"], fileId: string): Promise<IFilesReadResult>;

package/dist/contracts/system/files-shared.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILES_MAX_CALL_BYTES = void 0;
+exports.readWholeFile = readWholeFile;
+// System Files' limits, shapes and read helper, without the contract's registration, so package
+// code can import them from `@peers-app/peers-sdk/define`.
+/** Largest file `save` accepts, and the most bytes one `read` returns. */
+exports.FILES_MAX_CALL_BYTES = 8 * 1024 * 1024;
+/**
+ * Read a whole file through System Files, in ranges of {@link FILES_MAX_CALL_BYTES}.
+ *
+ * @param read - The consumer's `read` tool, from a package, a screen or the host.
+ * @param fileId - File to read.
+ * @returns The file's bytes, name and MIME type.
+ */
+async function readWholeFile(read, fileId) {
+    const first = await read({ fileId, length: exports.FILES_MAX_CALL_BYTES });
+    if (first.bytes.length >= first.fileSize)
+        return first;
+    const bytes = new Uint8Array(first.fileSize);
+    bytes.set(first.bytes);
+    let offset = first.bytes.length;
+    while (offset < first.fileSize) {
+        const part = await read({ fileId, offset, length: exports.FILES_MAX_CALL_BYTES });
+        if (part.bytes.length === 0)
+            throw new Error(`File ${fileId} ended early at ${offset} bytes`);
+        bytes.set(part.bytes, offset);
+        offset += part.bytes.length;
+    }
+    return { ...first, bytes };
+}

package/dist/contracts/validate.d.ts

@@ -3,6 +3,7 @@ import type { IAlsoImplementsDeclaration, IContractDefinition, IValidationResult
  * Validate that an implementation contract satisfies a target contract shape.
  * The implementation must be a superset: all contract tables, tools,
  * observables, and events must be present with compatible shapes.
+ * A table field that keeps files in the target must keep them in the implementation too.
  */
 export declare function validateProviderSatisfiesContract(impl: IContractDefinition, contract: IContractDefinition): IValidationResult;
 /**

package/dist/contracts/validate.js

@@ -5,6 +5,7 @@ exports.contractShapeChanges = contractShapeChanges;
 exports.validateImmutability = validateImmutability;
 exports.validateAlsoImplements = validateAlsoImplements;
 const lodash_1 = require("lodash");
+const field_type_1 = require("../types/field-type");
 const types_1 = require("./types");
 function ok() {
     return { valid: true, errors: [] };
@@ -56,7 +57,10 @@ function validateTableFields(contractTable, implTable) {
             }
             continue;
         }
-        const compat = isFieldCompatible(contractField, implField, "both");
+        const compat = isFieldCompatible(contractField, implField, "both") ??
+            ((0, field_type_1.isFileReferenceField)(contractField) && !(0, field_type_1.isFileReferenceField)(implField)
+                ? "contract requires a file reference, implementation does not declare one"
+                : null);
         if (compat) {
             errors.push({
                 kind: "field",
@@ -150,6 +154,7 @@ function validateEventFields(contractEvent, implEvent) {
  * Validate that an implementation contract satisfies a target contract shape.
  * The implementation must be a superset: all contract tables, tools,
  * observables, and events must be present with compatible shapes.
+ * A table field that keeps files in the target must keep them in the implementation too.
  */
 function validateProviderSatisfiesContract(impl, contract) {
     const errors = [];

package/dist/data/files/files.d.ts

@@ -3,6 +3,11 @@ import { Table } from "../orm";
 import { type IFile, type IFileInput } from "./file.types";
 import { FileReadStream } from "./file-read-stream";
 import { FileWriteStream } from "./file-write-stream";
+/**
+ * The chunked, content-hashed file store of one data context. Rows describe files; the bytes
+ * live in chunks on disk, shared by hash, and a device fetches a missing chunk from a connected
+ * device when it reads. Write through {@link FilesTable.saveFile}, never the table methods.
+ */
 export declare class FilesTable extends Table<IFile> {
     /** @deprecated Direct inserts forbidden; use saveFile() or saveFileRecord() */
     insert(..._args: Parameters<Table<any>["insert"]>): never;
@@ -12,6 +17,11 @@ export declare class FilesTable extends Table<IFile> {
     delete(..._args: Parameters<Table<any>["delete"]>): never;
     /** @deprecated Direct save forbidden; use saveFile() or saveFileRecord() */
     save(..._args: Parameters<Table<any>["save"]>): never;
+    /**
+     * Start writing a file in chunks; `finalize()` saves its row.
+     *
+     * @param metadata - The new file's id, name, size and MIME type.
+     */
     createWriteStream(metadata: IFileInput): Promise<FileWriteStream>;
     /**
      * Note: Use `saveFile` to write a file to disk. This method is for managing
@@ -20,13 +30,58 @@ export declare class FilesTable extends Table<IFile> {
      * @returns The inserted file record
      */
     saveFileRecord(fileRecord: IFile): Promise<IFile>;
+    /**
+     * Open a file for chunked reads.
+     *
+     * @param fileId - File to read.
+     * @param preloadChunksCount - Chunks to fetch ahead of the reader.
+     * @param skipVerification - Skip checking chunk hashes (only for trusted local data).
+     * @returns The stream, or null when no such file row exists.
+     */
     openReadStream(fileId: string, preloadChunksCount?: number, skipVerification?: boolean): Promise<FileReadStream | null>;
+    /**
+     * Save a whole file: chunk it, store the chunks and write its row.
+     *
+     * @param metaData - The file's id, name and MIME type. `fileSize` is taken from `data`.
+     * @param data - The bytes, or a string saved as UTF-8.
+     * @returns The saved row.
+     */
     saveFile(metaData: IFileInput, data: Uint8Array | string): Promise<IFile>;
+    /**
+     * Read a whole file, fetching missing chunks from connected devices.
+     *
+     * @param fileId - File to read.
+     * @param opts.skipVerification - Skip checking chunk hashes (only for trusted local data).
+     * @returns The bytes, or null when no such file row exists.
+     */
     getFileContents(fileId: string, opts?: {
         skipVerification?: boolean;
     }): Promise<Uint8Array | null>;
+    /**
+     * Delete a file's row, and its index file's. Chunks stay on disk: other files may share them.
+     *
+     * @param fileId - File to delete. A missing file is not an error.
+     */
     deleteFile(fileId: string): Promise<void>;
+    /**
+     * Save a large file's chunk hashes as an index file, itself chunked when large.
+     *
+     * @param chunkHashes - The large file's chunk hashes, in order.
+     * @returns The index file's id.
+     */
     createIndexFileRecursively(chunkHashes: string[]): Promise<string>;
+    /**
+     * Read a large file's chunk hashes back from its index file.
+     *
+     * @param indexFileId - The index file's id.
+     * @returns The chunk hashes, in order.
+     */
     loadChunkHashesRecursively(indexFileId: string): Promise<string[]>;
 }
+/**
+ * The Files table of a data context.
+ *
+ * @param dataContext - The context; defaults to the user context's default (the active group,
+ *   or the personal context). Pass it explicitly in host code.
+ */
 export declare function Files(dataContext?: DataContext): FilesTable;

package/dist/data/files/files.js

@@ -10,6 +10,11 @@ const table_definitions_system_1 = require("../orm/table-definitions.system");
 const file_types_1 = require("./file.types");
 const file_read_stream_1 = require("./file-read-stream");
 const file_write_stream_1 = require("./file-write-stream");
+/**
+ * The chunked, content-hashed file store of one data context. Rows describe files; the bytes
+ * live in chunks on disk, shared by hash, and a device fetches a missing chunk from a connected
+ * device when it reads. Write through {@link FilesTable.saveFile}, never the table methods.
+ */
 class FilesTable extends orm_1.Table {
     /** @deprecated Direct inserts forbidden; use saveFile() or saveFileRecord() */
     insert(..._args) {
@@ -27,6 +32,11 @@ class FilesTable extends orm_1.Table {
     save(..._args) {
         throw new Error("Direct saves forbidden; use saveFile() or saveFileRecord()");
     }
+    /**
+     * Start writing a file in chunks; `finalize()` saves its row.
+     *
+     * @param metadata - The new file's id, name, size and MIME type.
+     */
     async createWriteStream(metadata) {
         return new file_write_stream_1.FileWriteStream(metadata, this);
     }
@@ -39,6 +49,14 @@ class FilesTable extends orm_1.Table {
     async saveFileRecord(fileRecord) {
         return await super.save(fileRecord);
     }
+    /**
+     * Open a file for chunked reads.
+     *
+     * @param fileId - File to read.
+     * @param preloadChunksCount - Chunks to fetch ahead of the reader.
+     * @param skipVerification - Skip checking chunk hashes (only for trusted local data).
+     * @returns The stream, or null when no such file row exists.
+     */
     async openReadStream(fileId, preloadChunksCount, skipVerification) {
         const fileRecord = await this.get(fileId);
         if (!fileRecord) {
@@ -46,6 +64,13 @@ class FilesTable extends orm_1.Table {
         }
         return new file_read_stream_1.FileReadStream(fileRecord, this, preloadChunksCount, skipVerification);
     }
+    /**
+     * Save a whole file: chunk it, store the chunks and write its row.
+     *
+     * @param metaData - The file's id, name and MIME type. `fileSize` is taken from `data`.
+     * @param data - The bytes, or a string saved as UTF-8.
+     * @returns The saved row.
+     */
     async saveFile(metaData, data) {
         // Use FileWriteStream internally to ensure consistent chunking logic
         const writeStream = await this.createWriteStream({
@@ -60,6 +85,13 @@ class FilesTable extends orm_1.Table {
         // Finalize and return the result
         return await writeStream.finalize();
     }
+    /**
+     * Read a whole file, fetching missing chunks from connected devices.
+     *
+     * @param fileId - File to read.
+     * @param opts.skipVerification - Skip checking chunk hashes (only for trusted local data).
+     * @returns The bytes, or null when no such file row exists.
+     */
     async getFileContents(fileId, opts) {
         // Use FileReadStream internally to ensure consistent chunk reading logic
         const readStream = await this.openReadStream(fileId, undefined, opts?.skipVerification);
@@ -69,6 +101,11 @@ class FilesTable extends orm_1.Table {
         // Read the entire file using the streaming implementation
         return await readStream.readAll();
     }
+    /**
+     * Delete a file's row, and its index file's. Chunks stay on disk: other files may share them.
+     *
+     * @param fileId - File to delete. A missing file is not an error.
+     */
     async deleteFile(fileId) {
         // Get file metadata from database
         const fileRecord = await super.get(fileId);
@@ -85,7 +122,12 @@ class FilesTable extends orm_1.Table {
         // Delete file record from database
         await super.delete(fileId);
     }
-    // Create an index file recursively for large files
+    /**
+     * Save a large file's chunk hashes as an index file, itself chunked when large.
+     *
+     * @param chunkHashes - The large file's chunk hashes, in order.
+     * @returns The index file's id.
+     */
     async createIndexFileRecursively(chunkHashes) {
         // Create JSON content with chunk hashes
         const indexContent = JSON.stringify(chunkHashes);
@@ -104,7 +146,12 @@ class FilesTable extends orm_1.Table {
         await this.saveFile(indexMetadata, indexBuffer);
         return indexFileId;
     }
-    // Load chunk hashes recursively from an index file
+    /**
+     * Read a large file's chunk hashes back from its index file.
+     *
+     * @param indexFileId - The index file's id.
+     * @returns The chunk hashes, in order.
+     */
     async loadChunkHashesRecursively(indexFileId) {
         // Recursively load the index file
         const indexBuffer = await this.getFileContents(indexFileId);
@@ -118,18 +165,17 @@ class FilesTable extends orm_1.Table {
 }
 exports.FilesTable = FilesTable;
 (0, table_definitions_system_1.registerSystemTableDefinition)(file_types_1.filesMetaData, file_types_1.fileSchema, FilesTable);
+/**
+ * The Files table of a data context.
+ *
+ * @param dataContext - The context; defaults to the user context's default (the active group,
+ *   or the personal context). Pass it explicitly in host code.
+ */
 function Files(dataContext) {
     return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(file_types_1.filesMetaData, file_types_1.fileSchema);
 }
-// TODO implement permissions check for file access
-rpc_types_1.rpcServerCalls.getFileContents = async (fileId, encoding = "utf8") => {
-    const data = await Files().getFileContents(fileId);
-    if (data === null) {
-        throw new Error(`File not found: ${fileId}`);
-    }
-    return Buffer.from(data).toString(encoding);
-};
-// Get file contents as base64 - useful for binary data like images
+// Deprecated RPCs, kept only for Family Hub 0.3.x until its port is Home's version. New code
+// uses System Files, which is bound to the caller's own data context.
 rpc_types_1.rpcServerCalls.getFileContentsBase64 = async (fileId) => {
     const data = await Files().getFileContents(fileId);
     if (data === null) {
@@ -137,7 +183,6 @@ rpc_types_1.rpcServerCalls.getFileContentsBase64 = async (fileId) => {
     }
     return Buffer.from(data).toString("base64");
 };
-// Save a file from the UI - data should be base64 encoded for binary files
 rpc_types_1.rpcServerCalls.saveFile = async (input) => {
     const fileId = input.fileId || (0, utils_1.newid)();
     const encoding = input.encoding || "utf8";

package/dist/data/messages.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { DataContext } from "../context/data-context";
+/** A chat entry in a channel or thread, by a user or an assistant acting for them. */
 export declare const messageSchema: z.ZodObject<{
     messageId: z.ZodEffects<z.ZodString, string, string>;
     channelId: z.ZodEffects<z.ZodString, string, string>;
@@ -34,7 +35,13 @@ export declare const messageSchema: z.ZodObject<{
     fileIds?: string[] | undefined;
     vars?: z.objectInputType<{}, z.ZodAny, "strip"> | undefined;
 }>;
+/** One row of the Messages table. */
 export type IMessage = z.infer<typeof messageSchema>;
+/**
+ * The Messages table in a data context.
+ *
+ * @param dataContext - The context to read; defaults to the active one.
+ */
 export declare function Messages(dataContext?: DataContext): import("..").Table<{
     message: string;
     userId: string;
@@ -52,6 +59,20 @@ interface ISendMessageArgs {
     assistantId?: string;
     messageContent: string;
 }
+/**
+ * Post a message as the current user. The target is a message (a reply goes in its thread), a
+ * workflow run (a reply to the message that started it), a channel, a group (its default
+ * channel), or a user.
+ *
+ * @param args - The target, the content, and the assistant posting it, if any.
+ * @returns The stored message.
+ */
 export declare function sendMessage(args: ISendMessageArgs): Promise<IMessage>;
+/**
+ * The variables set on a message and on the message that started its thread, merged in the order
+ * they were created: a later message's value replaces an earlier one's.
+ *
+ * @param message - A message in the thread.
+ */
 export declare function getThreadVars(message: IMessage): Promise<Record<string, any>>;
 export {};

package/dist/data/messages.js

@@ -14,6 +14,7 @@ const table_definitions_system_1 = require("./orm/table-definitions.system");
 const types_1 = require("./orm/types");
 const users_1 = require("./users");
 const workflow_runs_1 = require("./workflow-runs");
+/** A chat entry in a channel or thread, by a user or an assistant acting for them. */
 exports.messageSchema = zod_1.z.object({
     messageId: zod_types_1.zodPeerId,
     channelId: zod_types_1.zodPeerId.describe("The id of the channel this message entry belongs to"),
@@ -30,7 +31,7 @@ exports.messageSchema = zod_1.z.object({
         .date()
         .optional()
         .describe("The time this message entry was last edited, if it was edited"),
-    fileIds: zod_types_1.zodPeerId.array().optional().describe("The ids of files attached to this message entry"),
+    fileIds: zod_types_1.zodFileId.array().optional().describe("The ids of files attached to this message entry"),
     vars: zod_types_1.zodAnyObject
         .optional()
         .describe("The variables that are associated with this message entry"),
@@ -56,9 +57,22 @@ const metaData = {
     ],
 };
 (0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.messageSchema);
+/**
+ * The Messages table in a data context.
+ *
+ * @param dataContext - The context to read; defaults to the active one.
+ */
 function Messages(dataContext) {
     return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(metaData, exports.messageSchema);
 }
+/**
+ * Post a message as the current user. The target is a message (a reply goes in its thread), a
+ * workflow run (a reply to the message that started it), a channel, a group (its default
+ * channel), or a user.
+ *
+ * @param args - The target, the content, and the assistant posting it, if any.
+ * @returns The stored message.
+ */
 async function sendMessage(args) {
     const { channelOrThreadIdOrWorkflowRunId, assistantId, messageContent } = args;
     let channelId = channelOrThreadIdOrWorkflowRunId;
@@ -98,6 +112,12 @@ async function sendMessage(args) {
     });
     return message;
 }
+/**
+ * The variables set on a message and on the message that started its thread, merged in the order
+ * they were created: a later message's value replaces an earlier one's.
+ *
+ * @param message - A message in the thread.
+ */
 async function getThreadVars(message) {
     const $or = [{ messageId: message.messageId }];
     if (message.messageParentId) {

package/dist/data/orm/sql.data-source.d.ts

@@ -19,7 +19,8 @@ export declare class SQLDataSource<T extends {
     private buildTableSql;
     private ensureTableAndIndexesExist;
     private ensureTableIsNewest;
-    private tableBuild;
+    /** Shared initialization, reset by a subclass that atomically drops its table and derived data. */
+    protected tableBuild: Promise<boolean> | undefined;
     /** Share schema initialization; a failed attempt is evicted so later calls can retry. */
     initTable(force?: boolean): Promise<boolean>;
     get(id: string): Promise<T | undefined>;

package/dist/data/orm/sql.data-source.js

@@ -172,6 +172,7 @@ class SQLDataSource {
         await this.ensureTableAndIndexesExist();
         return false;
     }
+    /** Shared initialization, reset by a subclass that atomically drops its table and derived data. */
     tableBuild;
     /** Share schema initialization; a failed attempt is evicted so later calls can retry. */
     async initTable(force = false) {

package/dist/data/orm/types.js

@@ -65,6 +65,10 @@ function fieldValueSchema(field, mode, open) {
         case "id": {
             const id = zod_1.z.string().refine((value) => (0, utils_1.isid)(value), { message: "Invalid id" });
             id._def._fieldType = field_type_1.FieldType.id;
+            // Keep a file reference a reference when a schema is rebuilt from stored fields.
+            if (field.subType) {
+                id._def._subType = field.subType;
+            }
             return id;
         }
         case "string":
@@ -261,6 +265,7 @@ function schemaToFields(schema) {
         let _def = field._def;
         let isArray;
         let brandedFieldType;
+        let brandedSubType;
         while (true) {
             if (_def.typeName === "ZodArray") {
                 if (isArray)
@@ -272,6 +277,9 @@ function schemaToFields(schema) {
             if (_def._fieldType) {
                 brandedFieldType = _def._fieldType;
             }
+            if (_def._subType) {
+                brandedSubType = _def._subType;
+            }
             if (_def.typeName === "ZodNullable") {
                 nullable = true;
             }
@@ -320,11 +328,15 @@ function schemaToFields(schema) {
         // optional/defaulted elements and nested arrays: enumValues describes each immediate element.
         const values = nullable || !enumElements ? undefined : zodEnumValues(valueSchema);
         const enumValues = values?.length ? [...new Set(values)] : undefined;
+        // A subtype (`zodFileId`'s "file") describes the branded type, so it goes only where that
+        // type was kept.
+        const subType = brandedFieldType && type === brandedFieldType ? brandedSubType : undefined;
         const newField = {
             name,
             type,
             isArray,
             optional,
+            subType,
             description,
             defaultValue,
             enumValues,

package/dist/data/package-versions.js

@@ -58,11 +58,11 @@ const schema = zod_1.z.object({
     version: zod_1.z.string().describe('Semantic version string (e.g., "1.0.0")'),
     versionTag: zod_1.z.string().optional().describe('Version tag (e.g., "stable", "beta")'),
     packageVersionHash: zod_1.z.string().describe("Hash of the combined bundle file hashes"),
-    packageBundleFileId: zod_types_1.zodPeerId.describe("File ID of the package bundle"),
+    packageBundleFileId: zod_types_1.zodFileId.describe("File ID of the package bundle"),
     packageBundleFileHash: zod_1.z.string().describe("Hash of the package bundle file"),
-    routesBundleFileId: zod_types_1.zodPeerId.optional().describe("File ID of the routes bundle"),
+    routesBundleFileId: zod_types_1.zodFileId.optional().describe("File ID of the routes bundle"),
     routesBundleFileHash: zod_1.z.string().optional().describe("Hash of the routes bundle"),
-    uiBundleFileId: zod_types_1.zodPeerId.optional().describe("File ID of the UI bundle"),
+    uiBundleFileId: zod_types_1.zodFileId.optional().describe("File ID of the UI bundle"),
     uiBundleFileHash: zod_1.z.string().optional().describe("Hash of the UI bundle"),
     appNavs: app_nav_1.appNavSchema
         .array()

package/dist/define/index.d.ts

@@ -14,7 +14,7 @@ export { type Observable, observable, type Subscription } from "../observable";
 export type { IPackageSaveOptions } from "../package-loader/isolated-runtime";
 export { idFromKey, isid, newid } from "../peer-id";
 export { FieldType, type IField } from "../types/field-type";
-export { zodPeerId } from "../types/zod-types";
+export { zodFileId, zodPeerId } from "../types/zod-types";
 export * from "./context";
 export * from "./contract-ref";
 export * from "./declare-contract";

package/dist/define/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.writePackageVar = exports.userVar = exports.readPackageVar = exports.groupVar = exports.groupUserVar = exports.groupDeviceVar = exports.deviceVar = exports.isImplementedObservable = exports.defineObservable = exports.declareObservable = exports.generatedField = exports.defineEvent = exports.zodPeerId = exports.FieldType = exports.newid = exports.isid = exports.idFromKey = exports.observable = exports.AccessLevel = exports.z = void 0;
+exports.writePackageVar = exports.userVar = exports.readPackageVar = exports.groupVar = exports.groupUserVar = exports.groupDeviceVar = exports.deviceVar = exports.isImplementedObservable = exports.defineObservable = exports.declareObservable = exports.generatedField = exports.defineEvent = exports.zodPeerId = exports.zodFileId = exports.FieldType = exports.newid = exports.isid = exports.idFromKey = exports.observable = exports.AccessLevel = exports.z = void 0;
 /**
  * `@peers-app/peers-sdk/define`: declare an isolated package.
  *
@@ -36,6 +36,7 @@ Object.defineProperty(exports, "newid", { enumerable: true, get: function () { r
 var field_type_1 = require("../types/field-type");
 Object.defineProperty(exports, "FieldType", { enumerable: true, get: function () { return field_type_1.FieldType; } });
 var zod_types_1 = require("../types/zod-types");
+Object.defineProperty(exports, "zodFileId", { enumerable: true, get: function () { return zod_types_1.zodFileId; } });
 Object.defineProperty(exports, "zodPeerId", { enumerable: true, get: function () { return zod_types_1.zodPeerId; } });
 __exportStar(require("./context"), exports);
 __exportStar(require("./contract-ref"), exports);

package/dist/define/system-contracts.d.ts

@@ -138,3 +138,12 @@ export declare const SystemContractCatalog: import("./contract-ref").IContractRe
     }>;
     getContractDefinition(input: import("../contracts/system/contract-catalog-contract").IGetContractDefinitionInput): Promise<import("../contracts/system/contract-catalog-contract").IContractDefinitionWithPolicy>;
 }>;
+/**
+ * System Files v1: save a file and read it back, in the package's own data context. Files sync
+ * to the context's other devices. Declare it with `pkg.consumes(SystemFiles)`.
+ */
+export declare const SystemFiles: import("./contract-ref").IContractRef<{
+    save(input: import("../contracts/system/files-shared").IFilesSaveInput): Promise<import("../contracts/system/files-shared").IFilesSaveResult>;
+    read(input: import("../contracts/system/files-shared").IFilesReadInput): Promise<import("../contracts/system/files-shared").IFilesReadResult>;
+}>;
+export { FILES_MAX_CALL_BYTES, type IFilesReadInput, type IFilesReadResult, type IFilesSaveInput, type IFilesSaveResult, readWholeFile, } from "../contracts/system/files-shared";

package/dist/define/system-contracts.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SystemContractCatalog = exports.SystemScheduler = exports.SystemGroupMembers = exports.SystemIdentity = exports.SystemHttp = void 0;
+exports.readWholeFile = exports.FILES_MAX_CALL_BYTES = exports.SystemFiles = exports.SystemContractCatalog = exports.SystemScheduler = exports.SystemGroupMembers = exports.SystemIdentity = exports.SystemHttp = void 0;
 const system_ids_1 = require("../system-ids");
 const contract_ref_1 = require("./contract-ref");
 /**
@@ -23,3 +23,11 @@ exports.SystemScheduler = (0, contract_ref_1.contractRef)(system_ids_1.scheduler
  * `pkg.consumes(SystemContractCatalog)`.
  */
 exports.SystemContractCatalog = (0, contract_ref_1.contractRef)(system_ids_1.contractCatalogContractId, 1);
+/**
+ * System Files v1: save a file and read it back, in the package's own data context. Files sync
+ * to the context's other devices. Declare it with `pkg.consumes(SystemFiles)`.
+ */
+exports.SystemFiles = (0, contract_ref_1.contractRef)(system_ids_1.filesContractId, 1);
+var files_shared_1 = require("../contracts/system/files-shared");
+Object.defineProperty(exports, "FILES_MAX_CALL_BYTES", { enumerable: true, get: function () { return files_shared_1.FILES_MAX_CALL_BYTES; } });
+Object.defineProperty(exports, "readWholeFile", { enumerable: true, get: function () { return files_shared_1.readWholeFile; } });

package/dist/index.d.ts

@@ -8,6 +8,8 @@ export { getLogger, type IWorkflowLog, WorkflowLogs, workflowLogSchema, } from "
 export { type AnyContractTools, type ContractClientTool, type ContractClientTools, type ContractEventPayloadsOf, type ContractIdOf, type ContractObservableValuesOf, type ContractObservableWritabilityOf, type ContractTableInputsOf, type ContractTableRowsOf, type ContractToolsOf, type ContractVersionOf, contractRef, type IContractClient, type IContractRef, } from "./define/contract-ref";
 export type { IPackageContract, IPackageDefinition, } from "./define/define-package";
 export { buildPackageManifest } from "./define/manifest";
+/** System Files, for package screens as well as providers: `hostContract(SystemFiles)`. */
+export { SystemFiles } from "./define/system-contracts";
 export * from "./device/binary-peer-connection-v2";
 export * from "./device/connection";
 export * from "./device/device";

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildPackageManifest = exports.contractRef = exports.workflowLogSchema = exports.WorkflowLogs = exports.getLogger = exports.orm = exports.data = void 0;
+exports.SystemFiles = exports.buildPackageManifest = exports.contractRef = exports.workflowLogSchema = exports.WorkflowLogs = exports.getLogger = exports.orm = exports.data = void 0;
 __exportStar(require("./context"), exports);
 __exportStar(require("./contracts"), exports);
 __exportStar(require("./data"), exports);
@@ -30,6 +30,9 @@ var contract_ref_1 = require("./define/contract-ref");
 Object.defineProperty(exports, "contractRef", { enumerable: true, get: function () { return contract_ref_1.contractRef; } });
 var manifest_1 = require("./define/manifest");
 Object.defineProperty(exports, "buildPackageManifest", { enumerable: true, get: function () { return manifest_1.buildPackageManifest; } });
+/** System Files, for package screens as well as providers: `hostContract(SystemFiles)`. */
+var system_contracts_1 = require("./define/system-contracts");
+Object.defineProperty(exports, "SystemFiles", { enumerable: true, get: function () { return system_contracts_1.SystemFiles; } });
 __exportStar(require("./device/binary-peer-connection-v2"), exports);
 __exportStar(require("./device/connection"), exports);
 __exportStar(require("./device/device"), exports);

package/dist/package-build/build-package.d.ts

@@ -15,6 +15,8 @@ export interface IPackageBuildResult {
     artifactPath: string;
     /** Size of the bundled provider source, in characters. */
     providerChars: number;
+    /** Things the build accepted but the author likely didn't mean ({@link fileFieldWarnings}). */
+    warnings: string[];
 }
 /** A running package watcher. Dispose it to stop watching and release esbuild. */
 export interface IPackageWatcher {
@@ -28,6 +30,15 @@ export interface IPackageWatcher {
  * @param entry - The module's path.
  */
 export declare function loadPackageModule(root: string, entry: string): Promise<unknown>;
+/**
+ * Warnings about table fields that look like file references but aren't: a top-level field
+ * named like a file id that isn't declared with `zodFileId`, and a `zodFileId` nested in an
+ * object field. Neither keeps its files, so Peers may free them. Internal to the build.
+ *
+ * @internal
+ * @param manifest - The package's manifest.
+ */
+export declare function fileFieldWarnings(manifest: IIsolatedPackageManifest): string[];
 /**
  * The generate-manifest step: write `dist/manifest.json` from the package's declarations.
  *
@@ -36,6 +47,7 @@ export declare function loadPackageModule(root: string, entry: string): Promise<
 export declare function generatePackageManifest(buildOptions?: IPackageBuildOptions): Promise<{
     manifest: IIsolatedPackageManifest;
     manifestPath: string;
+    warnings: string[];
 }>;
 /**
  * Build the package's manifest from its declarations, validated, without writing it or checking

package/dist/package-build/build-package.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadPackageModule = loadPackageModule;
+exports.fileFieldWarnings = fileFieldWarnings;
 exports.generatePackageManifest = generatePackageManifest;
 exports.packageManifest = packageManifest;
 exports.buildPackage = buildPackage;
@@ -18,6 +19,7 @@ const node_module_1 = require("node:module");
 const path = require("node:path");
 const manifest_1 = require("../define/manifest");
 const isolated_artifact_1 = require("../package-loader/isolated-artifact");
+const field_type_1 = require("../types/field-type");
 const freeze_contracts_1 = require("./freeze-contracts");
 /** Source text SES rejects before running it, with what to tell the author. */
 const SES_REJECTED_PATTERNS = [
@@ -129,7 +131,38 @@ async function loadModule(options, entry) {
 function validateManifest(manifest, providerSource = "void 0;") {
     (0, isolated_artifact_1.validateIsolatedPackageArtifact)({ manifest: structuredClone(manifest), providerSource }, { strict: true });
 }
-/** The package's definition and manifest, validated together. */
+/** A field name that reads as a file id: `fileId`, `imageFileId`, `fileIds` (not `profileId`). */
+const FILE_ID_NAME = /(?:^file|File)Ids?$/;
+/**
+ * Warnings about table fields that look like file references but aren't: a top-level field
+ * named like a file id that isn't declared with `zodFileId`, and a `zodFileId` nested in an
+ * object field. Neither keeps its files, so Peers may free them. Internal to the build.
+ *
+ * @internal
+ * @param manifest - The package's manifest.
+ */
+function fileFieldWarnings(manifest) {
+    const warnings = [];
+    const nested = (table, fields, parent) => {
+        for (const field of fields ?? []) {
+            const path = `${parent}.${field.name}`;
+            if ((0, field_type_1.isFileReferenceField)(field)) {
+                warnings.push(`Table ${table}: "${path}" is a zodFileId inside an object field, which doesn't keep its files. Only a table's top-level fields do: move it up, or use a table of attachments.`);
+            }
+            nested(table, field.fields, path);
+        }
+    };
+    for (const table of manifest.tables ?? []) {
+        for (const field of table.fields) {
+            if (FILE_ID_NAME.test(field.name) && !(0, field_type_1.isFileReferenceField)(field)) {
+                warnings.push(`Table ${table.name}: "${field.name}" looks like a file id but isn't declared with zodFileId, so it doesn't keep its files. Declare it with zodFileId and raise the table's versionNumber.`);
+            }
+            nested(table.name, field.fields, field.name);
+        }
+    }
+    return warnings;
+}
+/** The package's definition and manifest, validated together, and the build's warnings. */
 async function validPackage(options) {
     // frozen-contracts.json gives the shapes of older versions a contract also implements.
     const definition = await loadDefinition(options);
@@ -137,7 +170,7 @@ async function validPackage(options) {
         frozen: await (0, freeze_contracts_1.readFrozenContracts)(options.root),
     });
     validateManifest(manifest);
-    return { definition, manifest };
+    return { definition, manifest, warnings: fileFieldWarnings(manifest) };
 }
 /** The package's manifest, validated and checked against the contracts it froze. */
 async function checkedPackage(options) {
@@ -146,8 +179,8 @@ async function checkedPackage(options) {
     return result;
 }
 async function writeManifest(options) {
-    const { manifest } = await checkedPackage(options);
-    return saveManifest(options, manifest);
+    const { manifest, warnings } = await checkedPackage(options);
+    return { ...(await saveManifest(options, manifest)), warnings };
 }
 async function saveManifest(options, manifest) {
     const manifestPath = path.join(options.outDir, "manifest.json");
@@ -241,7 +274,7 @@ async function packageManifest(buildOptions = {}) {
  */
 async function buildPackage(buildOptions = {}) {
     const options = resolveOptions(buildOptions);
-    const { definition, manifest } = await checkedPackage(options);
+    const { definition, manifest, warnings } = await checkedPackage(options);
     const hasProvider = definition.provides.length > 0 ||
         definition.tables.length > 0 ||
         definition.startHooks.length > 0 ||
@@ -252,7 +285,13 @@ async function buildPackage(buildOptions = {}) {
     const providerSource = output?.outputFiles?.[0]?.text ?? "";
     const artifactPath = await writeArtifact(options, manifest, providerSource);
     const { manifestPath } = await saveManifest(options, manifest);
-    return { manifest, manifestPath, artifactPath, providerChars: providerSource.length };
+    return {
+        manifest,
+        manifestPath,
+        artifactPath,
+        providerChars: providerSource.length,
+        warnings,
+    };
 }
 /**
  * Build once, then rebuild whenever a source file changes. Resolves once watching starts.

package/dist/package-build/cli.js

@@ -64,6 +64,11 @@ function summarize(result) {
     const tools = manifest.provides.reduce((count, contract) => count + contract.tools.length, 0);
     return `${manifest.provides.length} contract(s), ${tools} tool(s), ${manifest.tables?.length ?? 0} table(s)`;
 }
+/** Print the build's warnings, one per line. */
+function printWarnings(result) {
+    for (const warning of result.warnings)
+        console.warn(`Warning: ${warning}`);
+}
 function relative(file) {
     return path.relative(process.cwd(), file) || file;
 }
@@ -88,6 +93,7 @@ async function main(argv) {
             throw new Error("--watch applies to build");
         }
         const result = await (0, build_package_1.generatePackageManifest)(options);
+        printWarnings(result);
         console.log(`Manifest: ${summarize(result)} -> ${relative(result.manifestPath)}`);
         return 0;
     }
@@ -97,12 +103,14 @@ async function main(argv) {
                 console.error(`Build failed: ${result.message}`);
                 return;
             }
+            printWarnings(result);
             console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; SDK ${sdk_version_1.SDK_VERSION}; provider ${Math.round(result.providerChars / 1024)} KB)`);
         });
         console.log("Watching for changes");
         return new Promise(() => undefined);
     }
     const result = await (0, build_package_1.buildPackage)(options);
+    printWarnings(result);
     console.log(`Built ${relative(result.artifactPath)} (${summarize(result)}; SDK ${sdk_version_1.SDK_VERSION}; provider ${Math.round(result.providerChars / 1024)} KB)`);
     return 0;
 }

package/dist/package-build/contract-source.js

@@ -316,7 +316,7 @@ class Code {
             (field.enumValues !== undefined &&
                 new Set(field.enumValues).size !== field.enumValues.length) ||
             field.defaultValue !== undefined ||
-            field.subType !== undefined ||
+            (field.subType !== undefined && !(0, field_type_1.isFileReferenceField)(field)) ||
             field.optional === false ||
             field.isArray === false ||
             field.description === "") {
@@ -367,11 +367,13 @@ class Code {
                 return values?.length && new Set(values).size === 1
                     ? `z.literal(${JSON.stringify(values[0])})`
                     : "z.boolean()";
-            case field_type_1.FieldType.id:
-                this.imports.add("zodPeerId");
+            case field_type_1.FieldType.id: {
+                const idSchema = (0, field_type_1.isFileReferenceField)(field) ? "zodFileId" : "zodPeerId";
+                this.imports.add(idSchema);
                 return values?.length
-                    ? `zodPeerId.refine((value) => ${JSON.stringify(values)}.includes(value))`
-                    : "zodPeerId";
+                    ? `${idSchema}.refine((value) => ${JSON.stringify(values)}.includes(value))`
+                    : idSchema;
+            }
             case field_type_1.FieldType.Date:
                 return "z.date()";
             case field_type_1.FieldType.blob:

package/dist/rpc-types.d.ts

@@ -29,8 +29,15 @@ export interface IRemoteLogsQueryInput {
 export declare const rpcServerCalls: {
     encryptData: (value: string, groupId?: string) => Promise<string>;
     tableMethodCall: (dataContextId: string, tableName: string, methodName: string, ...args: any[]) => Promise<any>;
-    getFileContents: (fileId: string, encoding?: BufferEncoding) => Promise<string>;
+    /**
+     * @deprecated Use System Files (`SystemFiles`, `readWholeFile`). Kept only for Family Hub
+     * 0.3.x; deleted once its port is Home's version.
+     */
     getFileContentsBase64: (fileId: string) => Promise<string>;
+    /**
+     * @deprecated Use System Files (`SystemFiles`). Kept only for Family Hub 0.3.x; deleted once
+     * its port is Home's version.
+     */
     saveFile: (input: {
         name: string;
         mimeType?: string;

package/dist/rpc-types.js

@@ -14,11 +14,15 @@ function rpcStub(rpcName) {
 exports.rpcServerCalls = {
     encryptData: rpcStub("encryptData"),
     tableMethodCall: rpcStub("tableMethodCall"),
-    // TODO lock this down so not all code can get any file contents
-    getFileContents: rpcStub("getFileContents"),
-    // Get file contents as base64 - useful for binary data like images
+    /**
+     * @deprecated Use System Files (`SystemFiles`, `readWholeFile`). Kept only for Family Hub
+     * 0.3.x; deleted once its port is Home's version.
+     */
     getFileContentsBase64: rpcStub("getFileContentsBase64"),
-    // Save a file from the UI - data should be base64 encoded for binary files
+    /**
+     * @deprecated Use System Files (`SystemFiles`). Kept only for Family Hub 0.3.x; deleted once
+     * its port is Home's version.
+     */
     saveFile: rpcStub("saveFile"),
     deleteLocalDatabase: rpcStub("deleteLocalDatabase"),
     /** Returns info about the pre-migration data directory, or `null` if already cleaned up. */

package/dist/system-ids.d.ts

@@ -215,3 +215,5 @@ export declare const packagesContractId = "00mvdhk66tdqrj3hy0bacmj32";
 export declare const hostShellContractId = "00mveexhw7ezjfghxomlo011g";
 /** Local-only System Group Members v1; allocated once with newid(). */
 export declare const groupMembersContractId = "00mvzfzkuf4djwjrsxq9cnaxt";
+/** Local-only System Files v1: save and read files in the caller's own context; allocated once with newid(). */
+export declare const filesContractId = "00mw1pvs1eupopu6sttetmki0";

package/dist/system-ids.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.groupMembersContractId = exports.hostShellContractId = exports.packagesContractId = exports.desktopToolsContractId = exports.hostToolsContractId = exports.toolCatalogContractId = exports.schedulerToolIds = exports.schedulerContractId = exports.contractCatalogToolIds = exports.contractCatalogContractId = exports.httpToolIds = exports.httpContractId = exports.localFoldersToolIds = exports.localFoldersContractId = exports.identityToolIds = exports.identityContractId = exports.invitesToolIds = exports.invitesContractId = exports.toolAccessControlToolIds = exports.toolAccessControlContractId = exports.syncCheckContractId = exports.appUpdatesContractId = exports.networkControlContractId = exports.networkDiagnosticsContractId = exports.deviceOperationsContractId = exports.logsContractId = exports.peersSystemPackageId = exports.peersCoreRevokedPublishPublicKeys = exports.peersCorePublishPublicKey = exports.peersCorePackageRepoUrl = exports.peersCorePackageId = exports.createGroupToolId = exports.queryDatabaseToolId = exports.runWorkflowToolId = exports.defaultSendMessageToolId = exports.defaultAssistantRunnerToolId = exports.adminAssistantId = exports.openCodeAssistantId = exports.defaultAssistantId = exports.peersRootUserId = void 0;
+exports.filesContractId = exports.groupMembersContractId = exports.hostShellContractId = exports.packagesContractId = exports.desktopToolsContractId = exports.hostToolsContractId = exports.toolCatalogContractId = exports.schedulerToolIds = exports.schedulerContractId = exports.contractCatalogToolIds = exports.contractCatalogContractId = exports.httpToolIds = exports.httpContractId = exports.localFoldersToolIds = exports.localFoldersContractId = exports.identityToolIds = exports.identityContractId = exports.invitesToolIds = exports.invitesContractId = exports.toolAccessControlToolIds = exports.toolAccessControlContractId = exports.syncCheckContractId = exports.appUpdatesContractId = exports.networkControlContractId = exports.networkDiagnosticsContractId = exports.deviceOperationsContractId = exports.logsContractId = exports.peersSystemPackageId = exports.peersCoreRevokedPublishPublicKeys = exports.peersCorePublishPublicKey = exports.peersCorePackageRepoUrl = exports.peersCorePackageId = exports.createGroupToolId = exports.queryDatabaseToolId = exports.runWorkflowToolId = exports.defaultSendMessageToolId = exports.defaultAssistantRunnerToolId = exports.adminAssistantId = exports.openCodeAssistantId = exports.defaultAssistantId = exports.peersRootUserId = void 0;
 /** Stable user ID that owns built-in Peers system records. */
 exports.peersRootUserId = "000peers0user000000000001";
 /** Default assistant used when no user-selected assistant is available. */
@@ -222,3 +222,5 @@ exports.packagesContractId = "00mvdhk66tdqrj3hy0bacmj32";
 exports.hostShellContractId = "00mveexhw7ezjfghxomlo011g";
 /** Local-only System Group Members v1; allocated once with newid(). */
 exports.groupMembersContractId = "00mvzfzkuf4djwjrsxq9cnaxt";
+/** Local-only System Files v1: save and read files in the caller's own context; allocated once with newid(). */
+exports.filesContractId = "00mw1pvs1eupopu6sttetmki0";

package/dist/types/field-type.d.ts

@@ -32,6 +32,10 @@ export interface IField {
     optional?: boolean;
     /** The value is an array of `type`; `fields`, `enumValues` describe each element. */
     isArray?: boolean;
+    /**
+     * What the value means beyond its type. {@link FILE_SUBTYPE} on an `id` field makes it a file
+     * reference ({@link isFileReferenceField}); `"markdown"` on a string asks UIs to render it.
+     */
     subType?: string;
     /** An object's own fields. Absent: any object. Only on `object`; other keys may be present. */
     fields?: IField[];
@@ -52,3 +56,13 @@ export declare const fieldSchema: z.ZodObject<{
     fields: z.ZodOptional<z.ZodLazy<z.ZodArray<z.ZodType<IField>>>>;
     enumValues: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
 }, "strip", z.ZodTypeAny, IField, IField>;
+/** The {@link IField.subType} of an `id` field that names a file: what `zodFileId` declares. */
+export declare const FILE_SUBTYPE = "file";
+/**
+ * True when a table field references files: an `id` field, or an array of them, with
+ * {@link FILE_SUBTYPE}. Only a table's top-level fields count; a file id nested in an object
+ * field isn't a reference.
+ *
+ * @param field - One of a table definition's top-level fields.
+ */
+export declare function isFileReferenceField(field: Pick<IField, "type" | "subType">): boolean;

package/dist/types/field-type.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.fieldSchema = exports.FieldType = void 0;
+exports.FILE_SUBTYPE = exports.fieldSchema = exports.FieldType = void 0;
+exports.isFileReferenceField = isFileReferenceField;
 const zod_1 = require("zod");
 //export type FieldType = 'id' | 'string' | 'number' | 'boolean' | 'Date' | 'object' | 'blob' | 'any';
 /** The value types a Peers IR field can have. */
@@ -27,3 +28,15 @@ exports.fieldSchema = zod_1.z.object({
     fields: zod_1.z.lazy(() => zod_1.z.array(exports.fieldSchema)).optional(),
     enumValues: zod_1.z.array(zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean()])).optional(),
 });
+/** The {@link IField.subType} of an `id` field that names a file: what `zodFileId` declares. */
+exports.FILE_SUBTYPE = "file";
+/**
+ * True when a table field references files: an `id` field, or an array of them, with
+ * {@link FILE_SUBTYPE}. Only a table's top-level fields count; a file id nested in an object
+ * field isn't a reference.
+ *
+ * @param field - One of a table definition's top-level fields.
+ */
+function isFileReferenceField(field) {
+    return field.type === FieldType.id && field.subType === exports.FILE_SUBTYPE;
+}

package/dist/types/zod-types.d.ts

@@ -9,6 +9,16 @@ export declare const zodAnyObjectOrArray: z.ZodUnion<[z.ZodObject<{}, "strip", z
  * records the field as an id.
  */
 export declare const zodPeerId: z.ZodEffects<z.ZodString, string, string>;
+/**
+ * A file's id, as `SystemFiles.save` returns it: a {@link zodPeerId} marked as a file reference
+ * (`subType: "file"`). A synced table's top-level field declared with it, or with an array of it,
+ * keeps the files it names: Peers frees a file's bytes only some time after no such field names
+ * it. Local-only tables, package variables, plain string fields, and nested object fields
+ * don't declare references.
+ *
+ * Changing a field to `zodFileId` changes the table's definition, so raise its `versionNumber`.
+ */
+export declare const zodFileId: z.ZodEffects<z.ZodString, string, string>;
 /** Any zod object schema. */
 export type ZodObjectType = z.ZodObject<any>;
 /** Any zod array schema. */

package/dist/types/zod-types.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.zodPeerId = exports.zodAnyObjectOrArray = exports.zodAnyObject = exports.z = void 0;
+exports.zodFileId = exports.zodPeerId = exports.zodAnyObjectOrArray = exports.zodAnyObject = exports.z = void 0;
 const zod_1 = require("zod");
 const peer_id_1 = require("../peer-id");
 const field_type_1 = require("./field-type");
@@ -14,13 +14,31 @@ Object.defineProperty(exports, "z", { enumerable: true, get: function () { retur
 exports.zodAnyObject = zod_1.z.object({}).catchall(zod_1.z.any());
 /** Any plain object or any array. */
 exports.zodAnyObjectOrArray = zod_1.z.union([exports.zodAnyObject, zod_1.z.array(zod_1.z.any())]);
+/** A new peer-id schema, marked as {@link FieldType.id} and, given one, a subtype. */
+function peerIdSchema(subType) {
+    const schema = zod_1.z.string().refine((value) => {
+        return (0, peer_id_1.isid)(value);
+    }, {
+        message: "Invalid peer id, it must be a 25 character alphanumeric string",
+    });
+    schema._def._fieldType = field_type_1.FieldType.id;
+    if (subType) {
+        schema._def._subType = subType;
+    }
+    return schema;
+}
 /**
  * A 25-character peer id from `newid()`. Marked as {@link FieldType.id}, so `schemaToFields`
  * records the field as an id.
  */
-exports.zodPeerId = zod_1.z.string().refine((value) => {
-    return (0, peer_id_1.isid)(value);
-}, {
-    message: "Invalid peer id, it must be a 25 character alphanumeric string",
-});
-exports.zodPeerId._def._fieldType = field_type_1.FieldType.id;
+exports.zodPeerId = peerIdSchema();
+/**
+ * A file's id, as `SystemFiles.save` returns it: a {@link zodPeerId} marked as a file reference
+ * (`subType: "file"`). A synced table's top-level field declared with it, or with an array of it,
+ * keeps the files it names: Peers frees a file's bytes only some time after no such field names
+ * it. Local-only tables, package variables, plain string fields, and nested object fields
+ * don't declare references.
+ *
+ * Changing a field to `zodFileId` changes the table's definition, so raise its `versionNumber`.
+ */
+exports.zodFileId = peerIdSchema(field_type_1.FILE_SUBTYPE);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peers-app/peers-sdk",
-  "version": "0.29.1",
+  "version": "0.30.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"