@peers-app/peers-sdk 0.29.2 → 0.30.0

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/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/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/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.2",
+  "version": "0.30.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/peers-app/peers-sdk.git"