@peers-app/peers-sdk 0.15.4 → 0.16.0

package/dist/data/index.d.ts

@@ -1,7 +1,6 @@
 export * from "./assistants";
 export * from "./change-tracking";
 export * from "./channels";
-export * from "./data-locks";
 export * from "./device-sync-info";
 export * from "./devices";
 export * from "./embeddings";

package/dist/data/index.js

@@ -17,7 +17,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./assistants"), exports);
 __exportStar(require("./change-tracking"), exports);
 __exportStar(require("./channels"), exports);
-__exportStar(require("./data-locks"), exports);
 __exportStar(require("./device-sync-info"), exports);
 __exportStar(require("./devices"), exports);
 __exportStar(require("./embeddings"), exports);

package/dist/data/orm/table-container.d.ts

@@ -1,4 +1,5 @@
 import type { z } from "zod";
+import type { ITableDefinitionRecord } from "../table-definitions-table";
 import { Table } from "./table";
 import type { ITableDefinition, TableConstructor, TableFactory } from "./table-definitions.type";
 import { type ITableMetaData } from "./types";
@@ -52,6 +53,27 @@ export declare class TableContainer {
      * Returns the table instance if found, or null if no definition exists.
      */
     getFallbackTable(tableName: string): Promise<Table<any> | null>;
+    /**
+     * Return the names of all tables whose TableDefinitions record has `deleted` set.
+     * Used by sync to exclude change records for deleted tables.
+     *
+     * @returns Array of table names (as stored in the `name` column of TableDefinitions).
+     */
+    getDeletedTableNames(): Promise<string[]>;
+    /**
+     * Return all TableDefinitions records that have been marked as deleted.
+     * Used by the Data Explorer UI to display deleted tables.
+     *
+     * @returns Full {@link ITableDefinitionRecord} objects with populated `deleted` timestamps.
+     */
+    getDeletedTableDefinitions(): Promise<ITableDefinitionRecord[]>;
+    /**
+     * Return the names of all tables whose metadata marks them as local-only.
+     * Used by sync to exclude local-only change records from remote exchange.
+     *
+     * @returns Array of full table names for local-only table definitions.
+     */
+    getLocalOnlyTableNames(): string[];
     /**
      * Register a table definition from a synced TableDefinitions record.
      * These go into the fallback tier (no custom constructor) so they never

package/dist/data/orm/table-container.js

@@ -158,6 +158,15 @@ class TableContainer {
                 .get(metaData.tableId)
                 .then((existing) => {
                 if (existing) {
+                    // Code-registration is authoritative: if the table was marked deleted,
+                    // clear the flag and force an update so sync propagates the revival.
+                    if (existing.deleted) {
+                        record.deleted = undefined;
+                        return tableDefsTable.save(record, {
+                            restoreIfDeleted: true,
+                            saveAsSnapshot: true,
+                        });
+                    }
                     const result = checkVersionedUpdate(existing.versionNumber, record.versionNumber, existing.metaData, record.metaData);
                     if (result === "skip") {
                         return;
@@ -225,7 +234,7 @@ class TableContainer {
         if (!this.fallbackSubscribed) {
             this.fallbackSubscribed = true;
             tableDefsTable.dataChanged.subscribe((event) => {
-                if (event.op === "delete") {
+                if (event.op === "delete" || event.dataObject?.deleted) {
                     const md = event.dataObject?.metaData;
                     if (md) {
                         const name = (0, utils_1.getFullTableName)(md);
@@ -239,12 +248,63 @@ class TableContainer {
         }
         // Query for this specific table definition
         const record = await tableDefsTable.findOne({ name: tableName });
-        if (!record)
+        if (!record || record.deleted)
             return null;
         this.registerFromTableDefinitionRecord(record);
         // Now instantiate via getTableByName which checks fallbackDefinitions
         return this.getTableByName(tableName);
     }
+    /**
+     * Return the names of all tables whose TableDefinitions record has `deleted` set.
+     * Used by sync to exclude change records for deleted tables.
+     *
+     * @returns Array of table names (as stored in the `name` column of TableDefinitions).
+     */
+    async getDeletedTableNames() {
+        const tableDefsTable = this.tableInstances.TableDefinitions;
+        if (!tableDefsTable)
+            return [];
+        const deletedRecords = await tableDefsTable.list({
+            deleted: { $exists: true },
+        });
+        return deletedRecords.map((r) => r.name);
+    }
+    /**
+     * Return all TableDefinitions records that have been marked as deleted.
+     * Used by the Data Explorer UI to display deleted tables.
+     *
+     * @returns Full {@link ITableDefinitionRecord} objects with populated `deleted` timestamps.
+     */
+    async getDeletedTableDefinitions() {
+        const tableDefsTable = this.tableInstances.TableDefinitions;
+        if (!tableDefsTable)
+            return [];
+        return tableDefsTable.list({ deleted: { $exists: true } });
+    }
+    /**
+     * Return the names of all tables whose metadata marks them as local-only.
+     * Used by sync to exclude local-only change records from remote exchange.
+     *
+     * @returns Array of full table names for local-only table definitions.
+     */
+    getLocalOnlyTableNames() {
+        const names = [];
+        const fullDefinitions = [
+            ...Object.values(table_definitions_system_1.systemTableDefinitions),
+            ...Object.values(this.tableDefinitions),
+        ];
+        for (const tableDefinition of fullDefinitions) {
+            if (tableDefinition.metaData.localOnly) {
+                names.push((0, utils_1.getFullTableName)(tableDefinition.metaData));
+            }
+        }
+        for (const [tableName, fallbackDefinition] of Object.entries(this.fallbackDefinitions)) {
+            if (fallbackDefinition.metaData.localOnly && !names.includes(tableName)) {
+                names.push(tableName);
+            }
+        }
+        return names;
+    }
     /**
      * Register a table definition from a synced TableDefinitions record.
      * These go into the fallback tier (no custom constructor) so they never
@@ -260,6 +320,12 @@ class TableContainer {
             return;
         }
         const tableName = (0, utils_1.getFullTableName)(metaData);
+        // Deleted tables should not be registered as fallbacks
+        if (record.deleted) {
+            delete this.fallbackDefinitions[tableName];
+            delete this.fallbackInstances[tableName];
+            return;
+        }
         // Don't overwrite a full (code-registered) definition -- that always takes precedence
         const fullDef = this.tableDefinitions[tableName] || table_definitions_system_1.systemTableDefinitions[tableName];
         if (fullDef) {

package/dist/data/orm/table-container.test.js

@@ -67,7 +67,7 @@ function createTestHarness() {
         .fn()
         .mockImplementation((metaData, schema, TableClass) => {
         const deps = {
-            dataSource: new client_proxy_data_source_1.ClientProxyDataSource(metaData, schema, "test-context"),
+            dataSource: new client_proxy_data_source_1.ClientProxyDataSource(metaData, schema ?? zod_1.z.object({}), "test-context"),
             eventRegistry,
         };
         return new (TableClass || table_1.Table)(metaData, deps);
@@ -134,7 +134,7 @@ describe("Tiered table instances", () => {
         expect(table).not.toBeInstanceOf(CustomTestTable);
     });
     it("getAllTables should prefer full instances over fallback instances", () => {
-        const { container, testMetaData, testSchema, defRecord, tableFactory } = createTestHarness();
+        const { container, testMetaData, testSchema, defRecord } = createTestHarness();
         // Create a second table that will only have a fallback definition
         const tableId2 = (0, utils_1.newid)();
         const metaData2 = {
@@ -172,3 +172,58 @@ describe("Tiered table instances", () => {
         expect(secondTable).not.toBeInstanceOf(CustomTestTable);
     });
 });
+describe("getLocalOnlyTableNames", () => {
+    it("returns localOnly code-registered table names and excludes non-local tables", () => {
+        const { container, testSchema } = createTestHarness();
+        const localOnlyMetaData = {
+            tableId: (0, utils_1.newid)(),
+            name: "LocalOnlyTable",
+            description: "A local-only table",
+            primaryKeyName: "id",
+            fields: [
+                { name: "id", type: field_type_1.FieldType.id },
+                { name: "title", type: field_type_1.FieldType.string },
+            ],
+            localOnly: true,
+        };
+        const syncedMetaData = {
+            tableId: (0, utils_1.newid)(),
+            name: "SyncedTable",
+            description: "A synced table",
+            primaryKeyName: "id",
+            fields: [
+                { name: "id", type: field_type_1.FieldType.id },
+                { name: "title", type: field_type_1.FieldType.string },
+            ],
+        };
+        container.registerTableDefinition({
+            metaData: localOnlyMetaData,
+            schema: testSchema,
+        });
+        container.registerTableDefinition({
+            metaData: syncedMetaData,
+            schema: testSchema,
+        });
+        const localOnlyNames = container.getLocalOnlyTableNames();
+        expect(localOnlyNames).toContain((0, utils_1.getFullTableName)(localOnlyMetaData));
+        expect(localOnlyNames).not.toContain((0, utils_1.getFullTableName)(syncedMetaData));
+    });
+    it("returns localOnly fallback table names without duplicates", () => {
+        const { container, testMetaData, testSchema, defRecord } = createTestHarness();
+        const localOnlyMetaData = {
+            ...testMetaData,
+            localOnly: true,
+        };
+        const localOnlyDefRecord = {
+            ...defRecord,
+            metaData: localOnlyMetaData,
+        };
+        container.registerFromTableDefinitionRecord(localOnlyDefRecord);
+        container.registerTableDefinition({
+            metaData: localOnlyMetaData,
+            schema: testSchema,
+        });
+        const localOnlyNames = container.getLocalOnlyTableNames();
+        expect(localOnlyNames.filter((name) => name === defRecord.name)).toHaveLength(1);
+    });
+});

package/dist/data/table-definitions-table.d.ts

@@ -1,10 +1,12 @@
 import { z } from "zod";
 import type { DataContext } from "../context/data-context";
+/** Zod schema for rows in the {@link TableDefinitions} system table. */
 export declare const tableDefinitionRecordSchema: z.ZodObject<{
     tableId: z.ZodString;
     name: z.ZodString;
     metaData: z.ZodObject<{}, "strip", z.ZodAny, z.objectOutputType<{}, z.ZodAny, "strip">, z.objectInputType<{}, z.ZodAny, "strip">>;
     versionNumber: z.ZodDefault<z.ZodNumber>;
+    deleted: z.ZodOptional<z.ZodDate>;
 }, "strip", z.ZodTypeAny, {
     name: string;
     metaData: {} & {
@@ -12,15 +14,26 @@ export declare const tableDefinitionRecordSchema: z.ZodObject<{
     };
     tableId: string;
     versionNumber: number;
+    deleted?: Date | undefined;
 }, {
     name: string;
     metaData: {} & {
         [k: string]: any;
     };
     tableId: string;
+    deleted?: Date | undefined;
     versionNumber?: number | undefined;
 }>;
+/** A single row in the {@link TableDefinitions} system table. */
 export type ITableDefinitionRecord = z.infer<typeof tableDefinitionRecordSchema>;
+/**
+ * Accessor for the TableDefinitions system table.
+ *
+ * This table stores table schemas as tracked, synced data so that peers can
+ * learn about table definitions without needing the originating package installed.
+ *
+ * @param dataContext - Optional data context; when omitted the singleton context is used.
+ */
 export declare function TableDefinitions(dataContext?: DataContext): import("./orm").Table<{
     name: string;
     metaData: {} & {
@@ -28,4 +41,5 @@ export declare function TableDefinitions(dataContext?: DataContext): import("./o
     };
     tableId: string;
     versionNumber: number;
+    deleted?: Date | undefined;
 }>;

package/dist/data/table-definitions-table.js

@@ -7,6 +7,7 @@ const user_context_singleton_1 = require("../context/user-context-singleton");
 const zod_types_1 = require("../types/zod-types");
 const table_definitions_system_1 = require("./orm/table-definitions.system");
 const types_1 = require("./orm/types");
+/** Zod schema for rows in the {@link TableDefinitions} system table. */
 exports.tableDefinitionRecordSchema = zod_1.z.object({
     tableId: zod_1.z.string().describe("Primary key - same as ITableMetaData.tableId"),
     name: zod_1.z.string().describe("Table name"),
@@ -15,6 +16,10 @@ exports.tableDefinitionRecordSchema = zod_1.z.object({
         .number()
         .default(0)
         .describe("Version number set by the developer in the table definition; higher value wins during sync"),
+    deleted: zod_1.z
+        .date()
+        .optional()
+        .describe("When set, the table was deleted at this time. Changes for this table should be ignored during sync."),
 });
 const metaData = {
     name: "TableDefinitions",
@@ -24,6 +29,14 @@ const metaData = {
     indexes: [{ fields: ["name"] }],
 };
 (0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.tableDefinitionRecordSchema);
+/**
+ * Accessor for the TableDefinitions system table.
+ *
+ * This table stores table schemas as tracked, synced data so that peers can
+ * learn about table definitions without needing the originating package installed.
+ *
+ * @param dataContext - Optional data context; when omitted the singleton context is used.
+ */
 function TableDefinitions(dataContext) {
     return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(metaData, exports.tableDefinitionRecordSchema);
 }

package/dist/data/workflow-logs.js

@@ -36,6 +36,7 @@ const metaData = {
     description: "The log entries for workflow runs.",
     primaryKeyName: "workflowLogId",
     fields: (0, types_1.schemaToFields)(exports.workflowLogSchema),
+    localOnly: true,
 };
 (0, table_definitions_system_1.registerSystemTableDefinition)(metaData, exports.workflowLogSchema);
 function WorkflowLogs(dataContext) {

package/dist/data/workflow-runs.d.ts

@@ -1,6 +1,5 @@
 import { z } from "zod";
 import type { DataContext } from "../context/data-context";
-import { type IDataLock } from "./data-locks";
 import { Table } from "./orm/table";
 export declare const workflowRunSchema: z.ZodObject<{
     workflowRunId: z.ZodEffects<z.ZodString, string, string>;
@@ -77,19 +76,9 @@ export declare const workflowRunSchema: z.ZodObject<{
 }>;
 export type IWorkflowRun = z.infer<typeof workflowRunSchema>;
 declare class WorkflowRunTable extends Table<IWorkflowRun> {
-    /** @deprecated Direct calls to save forbidden; use insert or saveWithLock */
-    save(..._args: Parameters<Table<any>["insert"]>): never;
-    /** @deprecated Direct calls to update forbidden; use saveWithLock() */
-    update(..._args: Parameters<Table<any>["update"]>): never;
-    saveWithLock(workflowRun: IWorkflowRun, lock?: IDataLock): Promise<IWorkflowRun>;
-    acquireLock(workflowRunId: string, timeoutMs?: number, lockTimeMs?: number): Promise<IDataLock | undefined>;
-    saveAndRelease(workflowRun: IWorkflowRun, lock: IDataLock): Promise<void>;
     haltRun(workflowRunId: string): Promise<void>;
-    /**
-     * Removes the error state from a workflow run and locks it so
-     * additional editing can be done before it is re-run.
-     */
-    clearErrorState(workflowRunId: string): Promise<IDataLock | false>;
+    /** Removes the error state from a workflow run so it can be re-run. */
+    clearErrorState(workflowRunId: string): Promise<boolean>;
 }
 export declare function WorkflowRuns(dataContext?: DataContext): WorkflowRunTable;
 export interface IRunWorkflowOptions {

package/dist/data/workflow-runs.js

@@ -47,7 +47,6 @@ const zod_types_1 = require("../types/zod-types");
 const utils_1 = require("../utils");
 const assistants_1 = require("./assistants");
 const channels_1 = require("./channels");
-const data_locks_1 = require("./data-locks");
 const groups_1 = require("./groups");
 const messages_1 = require("./messages");
 const orm_1 = require("./orm");
@@ -104,6 +103,7 @@ const metaData = {
     description: "workflows instances that have been run manually, from messages, or from events",
     primaryKeyName: "workflowRunId",
     fields: (0, types_1.schemaToFields)(exports.workflowRunSchema),
+    localOnly: true,
     indexes: [
         { fields: ["workflowId"] },
         { fields: ["parentMessageId"] },
@@ -123,83 +123,6 @@ let WorkflowRunTable = (() => {
             __esDecorate(this, null, _haltRun_decorators, { kind: "method", name: "haltRun", static: false, private: false, access: { has: obj => "haltRun" in obj, get: obj => obj.haltRun }, metadata: _metadata }, null, _instanceExtraInitializers);
             if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
         }
-        /** @deprecated Direct calls to save forbidden; use insert or saveWithLock */
-        save(..._args) {
-            throw new Error("Direct inserts forbidden; use insert() or saveWithLock()");
-        }
-        /** @deprecated Direct calls to update forbidden; use saveWithLock() */
-        update(..._args) {
-            throw new Error("Direct updates forbidden; use saveWithLock()");
-        }
-        async saveWithLock(workflowRun, lock) {
-            if (!workflowRun.workflowRunId) {
-                workflowRun.workflowRunId = (0, utils_1.newid)();
-                return super.insert(workflowRun);
-            }
-            let lockedForThisSave = false;
-            if (!lock) {
-                lock = await (0, data_locks_1.DataLocks)().acquireLock(workflowRun.workflowRunId);
-                lockedForThisSave = true;
-            }
-            else {
-                const currentLock = await (0, data_locks_1.DataLocks)().getCurrentLock(workflowRun.workflowRunId);
-                if (currentLock?.dataLockId !== lock.dataLockId) {
-                    throw new Error(`Provided lock is not the current lock for workflowRunId ${workflowRun.workflowRunId} - aborting save`);
-                }
-            }
-            if (!lock) {
-                throw new Error(`Could not acquire lock for workflow run ${workflowRun.workflowRunId}`);
-            }
-            if (lock.recordId !== workflowRun.workflowRunId) {
-                throw new Error(`Provided lock recordId ${lock?.recordId} does not match workflowRunId ${workflowRun.workflowRunId}`);
-            }
-            let dbData = await this.get(workflowRun.workflowRunId);
-            if (dbData && !lock) {
-                const currentLock = await (0, data_locks_1.DataLocks)().getCurrentLock(workflowRun.workflowRunId);
-                if (currentLock) {
-                    throw new Error(`Workflow run ${workflowRun.workflowRunId} is locked by ${currentLock.dataLockId} - the lock will timeout at ${new Date(currentLock.lockedUntil)}`);
-                }
-            }
-            if (dbData?.inErrorState) {
-                throw new Error(`Workflow run ${workflowRun.workflowRunId} is in an error state - use clearErrorState to continue the run`);
-            }
-            if (dbData) {
-                dbData = await super.update(workflowRun);
-            }
-            else {
-                dbData = await super.insert(workflowRun);
-            }
-            if (lockedForThisSave) {
-                await (0, data_locks_1.DataLocks)().releaseLock(lock);
-            }
-            return dbData;
-        }
-        async acquireLock(workflowRunId, timeoutMs, lockTimeMs) {
-            const workflowDbData = await this.get(workflowRunId);
-            if (!workflowDbData)
-                return undefined;
-            if (workflowDbData.inErrorState) {
-                console.warn(`Workflow run ${workflowRunId} is in an error state - not acquiring lock`);
-                return undefined;
-            }
-            return await (0, data_locks_1.DataLocks)().acquireLock(workflowRunId, timeoutMs, lockTimeMs);
-        }
-        async saveAndRelease(workflowRun, lock) {
-            const workflowDbData = await this.get(workflowRun.workflowRunId);
-            if (!workflowDbData)
-                return;
-            const currentLock = await (0, data_locks_1.DataLocks)().getCurrentLock(workflowRun.workflowRunId);
-            if (!currentLock || currentLock.dataLockId !== lock.dataLockId) {
-                console.warn(`Workflow run ${workflowRun.workflowRunId} is not locked by ${lock.dataLockId} - aborting save`);
-                return;
-            }
-            if (workflowDbData.inErrorState) {
-                console.warn(`Workflow run ${workflowRun.workflowRunId} is in an error state - aborting save`);
-                return;
-            }
-            await super.update(workflowRun);
-            await (0, data_locks_1.DataLocks)().releaseLock(lock);
-        }
         async haltRun(workflowRunId) {
             const run = await super.get(workflowRunId);
             if (!run) {
@@ -212,16 +135,6 @@ let WorkflowRunTable = (() => {
             if (!run.completedAt) {
                 run.inErrorState = true;
                 await super.update(run);
-                // Release any existing lock
-                while (true) {
-                    const currentLock = await (0, data_locks_1.DataLocks)().getCurrentLock(workflowRunId);
-                    if (currentLock) {
-                        await (0, data_locks_1.DataLocks)().releaseLock(currentLock);
-                    }
-                    else {
-                        break; // No lock to release
-                    }
-                }
                 // also halt any child runs
                 this.list({ parentWorkflowRunId: workflowRunId })
                     .then(async (childRuns) => {
@@ -241,10 +154,7 @@ let WorkflowRunTable = (() => {
                 logger(runHaltMessage);
             }
         }
-        /**
-         * Removes the error state from a workflow run and locks it so
-         * additional editing can be done before it is re-run.
-         */
+        /** Removes the error state from a workflow run so it can be re-run. */
         async clearErrorState(workflowRunId) {
             const run = await super.get(workflowRunId);
             if (!run) {
@@ -254,14 +164,9 @@ let WorkflowRunTable = (() => {
                 console.warn(`Workflow run ${workflowRunId} is not in an error state - not clearing`);
                 return false;
             }
-            const lock = await (0, data_locks_1.DataLocks)().acquireLock(workflowRunId);
-            if (!lock) {
-                console.warn(`Could not acquire lock for workflow run ${workflowRunId}`);
-                return false;
-            }
             run.inErrorState = false;
             await super.update(run);
-            return lock;
+            return true;
         }
         constructor() {
             super(...arguments);

package/dist/data/workflows.js

@@ -11,6 +11,7 @@ const metaData = {
     primaryKeyName: "workflowId",
     fields: (0, types_1.schemaToFields)(workflow_1.workflowSchema),
     iconClassName: "bi bi-database-fill-gear",
+    localOnly: true,
     indexes: [{ fields: ["name"] }],
 };
 (0, table_definitions_system_1.registerSystemTableDefinition)(metaData, workflow_1.workflowSchema);

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 export * from "./context";
 export * from "./data";
-export { WorkflowLogs, getLogger, workflowLogSchema, type IWorkflowLog, } from "./data/workflow-logs";
 export * as data from "./data";
 export * from "./data/orm";
 export * as orm from "./data/orm";
+export { getLogger, type IWorkflowLog, WorkflowLogs, workflowLogSchema, } from "./data/workflow-logs";
 export * from "./device/binary-peer-connection-v2";
 export * from "./device/connection";
 export * from "./device/device";

package/dist/index.js

@@ -14,17 +14,17 @@ 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.tools = exports.orm = exports.data = exports.workflowLogSchema = exports.getLogger = exports.WorkflowLogs = void 0;
+exports.tools = exports.workflowLogSchema = exports.WorkflowLogs = exports.getLogger = exports.orm = exports.data = void 0;
 __exportStar(require("./context"), exports);
 __exportStar(require("./data"), exports);
+exports.data = require("./data");
+__exportStar(require("./data/orm"), exports);
+exports.orm = require("./data/orm");
 // Root `.d.ts` lists these explicitly so IDEs see them (not only via `export *`).
 var workflow_logs_1 = require("./data/workflow-logs");
-Object.defineProperty(exports, "WorkflowLogs", { enumerable: true, get: function () { return workflow_logs_1.WorkflowLogs; } });
 Object.defineProperty(exports, "getLogger", { enumerable: true, get: function () { return workflow_logs_1.getLogger; } });
+Object.defineProperty(exports, "WorkflowLogs", { enumerable: true, get: function () { return workflow_logs_1.WorkflowLogs; } });
 Object.defineProperty(exports, "workflowLogSchema", { enumerable: true, get: function () { return workflow_logs_1.workflowLogSchema; } });
-exports.data = require("./data");
-__exportStar(require("./data/orm"), exports);
-exports.orm = require("./data/orm");
 __exportStar(require("./device/binary-peer-connection-v2"), exports);
 __exportStar(require("./device/connection"), exports);
 __exportStar(require("./device/device"), exports);

package/dist/keys.d.ts

@@ -1,52 +1,103 @@
+/** Replaces tweetnacl’s default PRNG (required on some runtimes, e.g. tests or constrained environments). */
 export declare function setPRNG(fn: (x: Uint8Array, n: number) => void): void;
+/** SHA-256 of UTF-8 `str`, returned as base64url (no padding). */
 export declare function hashValue(str: string): string;
+/** SHA-256 of raw bytes, returned as base64url (no padding). */
 export declare function hashBytes(buffer: Uint8Array): string;
+/** Deterministic JSON string via `fast-json-stable-stringify` (key order stable). */
 export declare function stableStringify(obj: any): string;
+/** {@link hashValue} of the stable JSON for `obj` (for content-addressing object payloads). */
 export declare function hashObject(obj: {
     [key: string]: any;
 }): string;
+/** Base64 with URL-safe alphabet and no `=` padding (used throughout keys and wire formats). */
 export declare function encodeBase64(data: Uint8Array): string;
+/**
+ * Inverse of {@link encodeBase64}; accepts standard or URL-safe base64 and repads as needed.
+ * @throws TypeError if `data` is not a string
+ */
 export declare function decodeBase64(data: string): Uint8Array;
+/** Random token as base64url string (`size` raw bytes, default 32). */
 export declare function newToken(size?: number): string;
+/** Ed25519 signing key and derived X25519 box public key, both base64url. */
 export interface IPublicKeys {
     publicKey: string;
     publicBoxKey: string;
 }
+/** {@link IPublicKeys} plus Ed25519 secret key material (64-byte encoding as stored by this module). */
 export interface IPublicPrivateKeys extends IPublicKeys {
     secretKey: string;
 }
+/** Detached Ed25519 signature over JSON-serialized `contents` with signer’s public key. */
 export interface ISignedObject<T> {
     contents: T;
     signature: string;
     publicKey: string;
 }
+/** NaCl box ciphertext + nonce + sender box public key (all base64url). */
 export interface IDataBox {
     contents: string;
     nonce: string;
     fromPublicKey: string;
 }
+/** Generates a new Ed25519 keypair and derived X25519 box keys; all keys are base64url. */
 export declare function newKeys(): IPublicPrivateKeys;
+/** Re-derives public and box keys from an Ed25519 `secretKey` (same encoding as {@link newKeys}). */
 export declare function hydrateKeys(secretKey: string): IPublicPrivateKeys;
+/** Signs a UTF-8 message with Ed25519; returns base64url signed message (NaCl `sign` combined format). */
 export declare function signMessageWithSecretKey(msg: string, secretKey: string): string;
+/**
+ * Verifies and strips an Ed25519 signed message; returns the original UTF-8 string.
+ * @throws If verification fails
+ */
 export declare function openMessageWithPublicKey(msg: string, publicKey: string): string;
+/**
+ * Detached sign over stable JSON: `undefined` / `null` are encoded with sentinel fields for round-trip.
+ * @returns Payload with original `contents`, `signature`, and signer's Ed25519 public key (32-byte slice, base64url)
+ */
 export declare function signObjectWithSecretKey<T>(obj: T, secretKey: string): ISignedObject<T>;
+/**
+ * Verifies a detached signature and returns `contents` after undoing the undefined/null sentinels.
+ * @throws If the signature is invalid
+ */
 export declare function openSignedObject<T>(signedObj: ISignedObject<T>): T;
+/**
+ * X25519 box encrypts `data` (msgpack via {@link txEncode}) to `toPublicBoxKey` from keys derived from `mySecretKey`.
+ * @param toPublicBoxKey Recipient’s X25519 public key (base64url)
+ */
 export declare function boxDataWithKeys(data: any, toPublicBoxKey: string, mySecretKey: string): IDataBox;
+/** Narrowing guard: value looks like an {@link IDataBox} envelope. */
 export declare function isBoxedData(data: any): boolean;
+/**
+ * Decrypts a box from {@link boxDataWithKeys} using the recipient’s Ed25519 secret (same format as {@link newKeys}).
+ * @throws If decryption or authentication fails
+ */
 export declare function openBoxWithSecretKey(box: IDataBox, mySecretKey: string): any;
+/** JSON-serializes `data` then NaCl `secretbox` with a random nonce; returns base64 payload `~` base64 nonce. */
 export declare function encryptData<T>(data: T, secretKey: string): string;
+/** Inverse of {@link encryptData}. Returns `null` if secretbox open fails. */
 export declare function decryptData<T>(encryptedData: string, secretKey: string): T | null;
+/** Object plus a `signature` field in the `publicKey:detachedSig` form produced by this module. */
 export type IObjectWithSignature<T> = T & {
     signature: string;
 };
 type IMaybeSignature = {
     signature?: string;
 };
+/**
+ * Strips any existing `signature`, signs a shallow copy of `obj`, and sets `signature` to `publicKey:detachedSig`.
+ * @returns Same shape as `obj` with string `signature` suitable for {@link verifyObjectSignature}
+ */
 export declare function addSignatureToObject<T extends Record<string, any>>(obj: T, secretKey: string): IObjectWithSignature<T>;
 /**
- * Will throw if the signature is invalid
+ * Ensures `signature` matches the rest of the object via {@link openSignedObject}.
+ * @throws If there is no signature or verification fails
  */
 export declare function verifyObjectSignature<T extends IMaybeSignature>(objectWithSignature: T): void;
+/** True if {@link verifyObjectSignature} would succeed. */
 export declare function isObjectSignatureValid<T extends IMaybeSignature>(objectWithSignature: T): boolean;
+/**
+ * Parses the Ed25519 public key prefix from a `publicKey:signature` field, or `undefined` if malformed.
+ */
 export declare function getPublicKeyFromObjectSignature<T extends IMaybeSignature>(objectWithSignature: T): string | undefined;
 export {};