@peers-app/peers-sdk 0.29.0 → 0.29.2

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/system/packages-contract.d.ts

@@ -8,7 +8,10 @@ export declare const PACKAGES_CONTRACT_VERSION = 1;
 export interface IPackagesHostCapabilities {
     /** The host can read package folders: import, create, clone, and reload from disk. */
     fileSystem: boolean;
-    /** The host can create and link a remote repository (`linkRemoteRepo`). */
+    /**
+     * The host can create and link a remote repository (`linkRemoteRepo` without a URL). Recording
+     * a given URL needs no host tooling.
+     */
     linkRemote: boolean;
     /** The host can install the default packages into a context (`installDefaultPackages`). */
     installDefaults: boolean;
@@ -172,6 +175,14 @@ export declare function packageVersionPromotionTargets(versionTag: string | unde
  * @param target - Input as typed.
  */
 export declare function isPackageRepositoryUrl(target: string): boolean;
+/**
+ * Whether a URL may be recorded as a package's source (`Packages.remoteRepo`) by
+ * `linkRemoteRepo`: an `https://` or `http://` URL, a `git@host:` remote, or a Git package
+ * remote, `peers://<groupId>/<repoId>`. No whitespace; at most 2,048 characters.
+ *
+ * @param url - The URL to record.
+ */
+export declare function isPackageSourceUrl(url: string): boolean;
 /** Typed consumer proxy for System Packages v1. */
 export interface IPackagesConsumer extends IContractConsumerBase {
     tools: {
@@ -223,9 +234,14 @@ export interface IPackagesConsumer extends IContractConsumerBase {
         }): Promise<IPackageOperationResult>;
         /** Re-read every package folder on this device and reload packages whose bundles changed. */
         reloadAllPackages(): Promise<IReloadAllPackagesResult>;
-        /** Create and link a remote repository for a local package. */
+        /**
+         * Record a package's source repository. With `remoteRepo` (see {@link isPackageSourceUrl}),
+         * record that URL; otherwise create a remote repository with the host's tooling and link it.
+         * A package that already has a source keeps it and the result carries a warning.
+         */
         linkRemoteRepo(input: {
             packageId: string;
+            remoteRepo?: string;
         }): Promise<IPackageOperationResult>;
         /** Remove a package from the group and unload it here. */
         uninstallPackage(input: {

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

@@ -4,6 +4,7 @@ exports.PACKAGES_CONTRACT_VERSION = void 0;
 exports.packageGroupVersionWarning = packageGroupVersionWarning;
 exports.packageVersionPromotionTargets = packageVersionPromotionTargets;
 exports.isPackageRepositoryUrl = isPackageRepositoryUrl;
+exports.isPackageSourceUrl = isPackageSourceUrl;
 exports.getPackagesContractDefinition = getPackagesContractDefinition;
 const system_ids_1 = require("../../system-ids");
 const field_type_1 = require("../../types/field-type");
@@ -43,6 +44,29 @@ function packageVersionPromotionTargets(versionTag) {
 function isPackageRepositoryUrl(target) {
     return /^(https?:\/\/|git@[^:/\s]+:)/.test(target.trim());
 }
+/**
+ * Whether a URL may be recorded as a package's source (`Packages.remoteRepo`) by
+ * `linkRemoteRepo`: an `https://` or `http://` URL, a `git@host:` remote, or a Git package
+ * remote, `peers://<groupId>/<repoId>`. No whitespace; at most 2,048 characters.
+ *
+ * @param url - The URL to record.
+ */
+function isPackageSourceUrl(url) {
+    if (url.length > 2048 || /\s|\p{Cc}/u.test(url))
+        return false;
+    if (/^peers:\/\/[A-Za-z0-9]{25}\/[A-Za-z0-9]{25}$/.test(url))
+        return true;
+    if (/^git@[^:/\\]+:.+$/.test(url))
+        return true;
+    if (!/^https?:\/\//.test(url) || url.includes("\\"))
+        return false;
+    try {
+        return !!new URL(url).hostname;
+    }
+    catch {
+        return false;
+    }
+}
 const field = (name, type, description, opts = {}) => ({ name, type, description, ...opts });
 const packageIdField = field("packageId", field_type_1.FieldType.id, "Package id.");
 const operationResultFields = [
@@ -162,8 +186,11 @@ function getPackagesContractDefinition() {
             },
             {
                 name: "linkRemoteRepo",
-                usageDescription: "Create a remote repository for a local package and link it.",
-                inputFields: [packageIdField],
+                usageDescription: "Record a package's source repository: the given URL, or one created with the host's tooling. A package that already has a source keeps it.",
+                inputFields: [
+                    packageIdField,
+                    field("remoteRepo", field_type_1.FieldType.string, "Record this URL (https://, git@host:, or a Git package peers:// URL) instead of creating a repository.", { optional: true }),
+                ],
                 outputFields: operationResultFields,
             },
             {

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/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/device/binary-peer-connection-v2.js

@@ -330,11 +330,9 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
     }
     // ─── Drain / Backpressure ────────────────────────────────────────
     // Single persistent drain handler to avoid leaking listeners
-    let drainResolve = null;
+    const drainWaiters = new Set();
     peer.on("drain", () => {
-        if (drainResolve) {
-            const resolve = drainResolve;
-            drainResolve = null;
+        for (const resolve of drainWaiters) {
             resolve();
         }
     });
@@ -351,15 +349,18 @@ function createBinaryPeerSocket(connectionId, peer, protocol = "binary", receive
         // Backpressure: wait for buffer to drain before sending more
         while ((peer.getBufferedAmount?.() ?? 0) > config.highWaterMark) {
             await new Promise((resolve) => {
-                drainResolve = resolve;
+                const resume = () => {
+                    clearInterval(timer);
+                    drainWaiters.delete(resume);
+                    resolve();
+                };
                 // Also poll as fallback (drain event might not fire on all transports)
                 const timer = setInterval(() => {
                     if ((peer.getBufferedAmount?.() ?? 0) <= config.lowWaterMark) {
-                        clearInterval(timer);
-                        drainResolve = null;
-                        resolve();
+                        resume();
                     }
                 }, 5);
+                drainWaiters.add(resume);
             });
         }
         // A retired cipher must not fall back to a clear frame; the peer would close

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/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/package.json

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