@peers-app/peers-sdk 0.15.3 → 0.15.5

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 {};

package/dist/keys.js

@@ -33,9 +33,11 @@ const tx_encoding_1 = require("./device/tx-encoding");
 const serial_json_1 = require("./serial-json");
 globalThis.Buffer = buffer_1.Buffer; // shim for browsers/RN
 const _stableStringify = require("fast-json-stable-stringify");
+/** Replaces tweetnacl’s default PRNG (required on some runtimes, e.g. tests or constrained environments). */
 function setPRNG(fn) {
     nacl.setPRNG(fn);
 }
+/** SHA-256 of UTF-8 `str`, returned as base64url (no padding). */
 function hashValue(str) {
     // const full = nacl.hash(decodeUTF8(str));
     // const half = full.slice(0, 32);
@@ -43,23 +45,31 @@ function hashValue(str) {
     const hash = (0, sha2_1.sha256)(new TextEncoder().encode(str));
     return encodeBase64(hash);
 }
+/** SHA-256 of raw bytes, returned as base64url (no padding). */
 function hashBytes(buffer) {
     const hash = (0, sha2_1.sha256)(buffer);
     return encodeBase64(hash);
 }
+/** Deterministic JSON string via `fast-json-stable-stringify` (key order stable). */
 function stableStringify(obj) {
     return _stableStringify(obj);
 }
+/** {@link hashValue} of the stable JSON for `obj` (for content-addressing object payloads). */
 function hashObject(obj) {
     const stableJson = stableStringify(obj);
     const hash = hashValue(stableJson);
     return hash;
 }
+/** Base64 with URL-safe alphabet and no `=` padding (used throughout keys and wire formats). */
 function encodeBase64(data) {
     // return Buffer.from(data).toString("base64url"); // no padding by default
     const str = utils.encodeBase64(data);
     return str.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
 }
+/**
+ * Inverse of {@link encodeBase64}; accepts standard or URL-safe base64 and repads as needed.
+ * @throws TypeError if `data` is not a string
+ */
 function decodeBase64(data) {
     if (typeof data !== "string") {
         throw new TypeError(`decodeBase64 expected a string but received ${typeof data}`);
@@ -70,9 +80,11 @@ function decodeBase64(data) {
     }
     return utils.decodeBase64(data);
 }
+/** Random token as base64url string (`size` raw bytes, default 32). */
 function newToken(size = 32) {
     return encodeBase64(nacl.randomBytes(size));
 }
+/** Generates a new Ed25519 keypair and derived X25519 box keys; all keys are base64url. */
 function newKeys() {
     const sign = nacl.sign.keyPair(); // Ed25519
     const curveSecret = ed2curve.convertSecretKey(sign.secretKey); // 32 bytes
@@ -83,6 +95,7 @@ function newKeys() {
         publicBoxKey: encodeBase64(box.publicKey),
     };
 }
+/** Re-derives public and box keys from an Ed25519 `secretKey` (same encoding as {@link newKeys}). */
 function hydrateKeys(secretKey) {
     const sk64 = decodeBase64(secretKey); // Ed25519 64-byte secretKey
     const curveSecret = ed2curve.convertSecretKey(sk64);
@@ -93,12 +106,17 @@ function hydrateKeys(secretKey) {
         publicBoxKey: encodeBase64(box.publicKey),
     };
 }
+/** Signs a UTF-8 message with Ed25519; returns base64url signed message (NaCl `sign` combined format). */
 function signMessageWithSecretKey(msg, secretKey) {
     const _secretKey = decodeBase64(secretKey);
     const msgDecoded = (0, tweetnacl_util_1.decodeUTF8)(msg);
     const msgSigned = nacl.sign(msgDecoded, _secretKey);
     return encodeBase64(msgSigned);
 }
+/**
+ * Verifies and strips an Ed25519 signed message; returns the original UTF-8 string.
+ * @throws If verification fails
+ */
 function openMessageWithPublicKey(msg, publicKey) {
     const _publicKey = decodeBase64(publicKey);
     const msgDecoded = decodeBase64(msg);
@@ -108,6 +126,10 @@ function openMessageWithPublicKey(msg, publicKey) {
     }
     return (0, tweetnacl_util_1.encodeUTF8)(msgOpened);
 }
+/**
+ * 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)
+ */
 function signObjectWithSecretKey(obj, secretKey) {
     const _secretKey = decodeBase64(secretKey);
     if (obj === undefined) {
@@ -125,6 +147,10 @@ function signObjectWithSecretKey(obj, secretKey) {
         publicKey: encodeBase64(_secretKey.slice(32)),
     };
 }
+/**
+ * Verifies a detached signature and returns `contents` after undoing the undefined/null sentinels.
+ * @throws If the signature is invalid
+ */
 function openSignedObject(signedObj) {
     const _publicKey = decodeBase64(signedObj.publicKey);
     const objStr = (0, serial_json_1.toJSONString)(signedObj.contents);
@@ -145,6 +171,10 @@ function openSignedObject(signedObj) {
     }
     return signedObj.contents;
 }
+/**
+ * X25519 box encrypts `data` (msgpack via {@link txEncode}) to `toPublicBoxKey` from keys derived from `mySecretKey`.
+ * @param toPublicBoxKey Recipient’s X25519 public key (base64url)
+ */
 function boxDataWithKeys(data, toPublicBoxKey, mySecretKey) {
     const _secretKey = decodeBase64(mySecretKey);
     const curveSecret = ed2curve.convertSecretKey(_secretKey);
@@ -159,12 +189,17 @@ function boxDataWithKeys(data, toPublicBoxKey, mySecretKey) {
         fromPublicKey: encodeBase64(boxKeyPair.publicKey),
     };
 }
+/** Narrowing guard: value looks like an {@link IDataBox} envelope. */
 function isBoxedData(data) {
     return (typeof data === "object" &&
         typeof data.contents === "string" &&
         typeof data.nonce === "string" &&
         typeof data.fromPublicKey === "string");
 }
+/**
+ * Decrypts a box from {@link boxDataWithKeys} using the recipient’s Ed25519 secret (same format as {@link newKeys}).
+ * @throws If decryption or authentication fails
+ */
 function openBoxWithSecretKey(box, mySecretKey) {
     const _secretKey = decodeBase64(mySecretKey);
     const curveSecret = ed2curve.convertSecretKey(_secretKey);
@@ -196,14 +231,20 @@ function decryptString(data, secretKey) {
     }
     return (0, tweetnacl_util_1.encodeUTF8)(decryptedData);
 }
+/** JSON-serializes `data` then NaCl `secretbox` with a random nonce; returns base64 payload `~` base64 nonce. */
 function encryptData(data, secretKey) {
     const _data = (0, serial_json_1.toJSONString)(data);
     return encryptString(_data, secretKey);
 }
+/** Inverse of {@link encryptData}. Returns `null` if secretbox open fails. */
 function decryptData(encryptedData, secretKey) {
     const _data = decryptString(encryptedData, secretKey);
     return (0, serial_json_1.fromJSONString)(_data);
 }
+/**
+ * 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}
+ */
 function addSignatureToObject(obj, secretKey) {
     obj = { ...obj };
     delete obj.signature;
@@ -212,7 +253,8 @@ function addSignatureToObject(obj, secretKey) {
     return { ...obj, signature: objSignature };
 }
 /**
- * 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
  */
 function verifyObjectSignature(objectWithSignature) {
     if (!objectWithSignature.signature) {
@@ -228,6 +270,7 @@ function verifyObjectSignature(objectWithSignature) {
     };
     openSignedObject(signedObject); // will throw if invalid
 }
+/** True if {@link verifyObjectSignature} would succeed. */
 function isObjectSignatureValid(objectWithSignature) {
     try {
         verifyObjectSignature(objectWithSignature);
@@ -237,6 +280,9 @@ function isObjectSignatureValid(objectWithSignature) {
     }
     return true;
 }
+/**
+ * Parses the Ed25519 public key prefix from a `publicKey:signature` field, or `undefined` if malformed.
+ */
 function getPublicKeyFromObjectSignature(objectWithSignature) {
     const parts = objectWithSignature.signature?.split(":");
     if (!parts || parts.length !== 2) {

package/dist/serial-json.d.ts

@@ -1,5 +1,16 @@
+/** True for plain object literals (excludes array, Date, and null). */
 export declare function isObject(x: any): x is Record<string, any>;
+/**
+ * Clones a value into a JSON-serializable tree: Dates, Buffers, cycles, `undefined`, `NaN`, RegExp, etc. use sentinel strings.
+ * Shared references are preserved with `__duplicate_ref_*` and `__this_ref` markers for {@link fromJSON}.
+ */
 export declare function toJSON(obj: any): any;
+/**
+ * Reverses {@link toJSON}: restores special values, shared references, and keys escaped with `__DOLLAR_`.
+ * @param _externalReferences Reserved for future use (function revival, etc.)
+ */
 export declare function fromJSON(obj: any, _externalReferences?: any): any;
+/** `JSON.stringify` of {@link toJSON} (stable, extended types). */
 export declare function toJSONString(obj: any): string;
+/** `JSON.parse` then {@link fromJSON}. */
 export declare function fromJSONString(str: string): any;

package/dist/serial-json.js

@@ -6,9 +6,14 @@ exports.fromJSON = fromJSON;
 exports.toJSONString = toJSONString;
 exports.fromJSONString = fromJSONString;
 const _ = require("lodash");
+/** True for plain object literals (excludes array, Date, and null). */
 function isObject(x) {
     return _.isObject(x) && !_.isArray(x) && !_.isDate(x) && x !== null;
 }
+/**
+ * Clones a value into a JSON-serializable tree: Dates, Buffers, cycles, `undefined`, `NaN`, RegExp, etc. use sentinel strings.
+ * Shared references are preserved with `__duplicate_ref_*` and `__this_ref` markers for {@link fromJSON}.
+ */
 function toJSON(obj) {
     if (!_.isObject(obj)) {
         return obj;
@@ -95,6 +100,10 @@ function toJSON(obj) {
     obj = recurse(obj);
     return obj;
 }
+/**
+ * Reverses {@link toJSON}: restores special values, shared references, and keys escaped with `__DOLLAR_`.
+ * @param _externalReferences Reserved for future use (function revival, etc.)
+ */
 function fromJSON(obj, _externalReferences) {
     var dup_refs = {};
     function recurse(obj) {
@@ -185,9 +194,11 @@ function fromJSON(obj, _externalReferences) {
     obj = recurse(obj);
     return obj;
 }
+/** `JSON.stringify` of {@link toJSON} (stable, extended types). */
 function toJSONString(obj) {
     return JSON.stringify(toJSON(obj));
 }
+/** `JSON.parse` then {@link fromJSON}. */
 function fromJSONString(str) {
     return fromJSON(JSON.parse(str));
 }

package/dist/utils.d.ts

@@ -1,29 +1,76 @@
 import type { ITableMetaData } from "./data/orm";
 import { type IDeviceConnection } from "./types/peer-device";
+/** Builds a random string of base-36 characters with unbiased distribution (tweetnacl-backed). */
 export declare function cryptoRandomString(length: number): string;
+/**
+ * Creates a new 25-character peer id: base-36 time prefix (10 chars) + random suffix (15 chars).
+ * Sort order correlates with creation time. Use {@link isid} to validate user-provided values.
+ */
 export declare function newid(): string;
+/** Lexicographic lower bound for valid peer ids (epoch). */
 export declare const MIN_ID: string;
+/** Lexicographic upper bound for valid peer ids (far future). */
 export declare const MAX_ID: string;
+/**
+ * Returns whether `id` is a 25-char base-36 string whose embedded time is not in the future (5 min skew allowed).
+ * @param id Candidate id (coerced to string)
+ */
 export declare function isid(id: any): boolean;
+/** Returns the `Date.now()`-compatible millisecond time encoded in the first 10 base-36 characters of a peer id. */
 export declare function idTime(id: string): number;
+/** Interprets a peer id’s time prefix as a `Date` (see {@link idTime}). */
 export declare function idDate(id: string): Date;
 /**
- * This returns the random number as two parts to prevent loss of precision when converting to large numbers
+ * Returns the 15-character random suffix of a peer id as two base-36 integers so large values stay exact in JS.
+ * @param id A 25-character peer id from {@link newid}
  */
 export declare function idRandNums(id: string): [number, number];
+/** Fast non-cryptographic 32-bit string hash (sign-insensitive) for display keys and bucketing. */
 export declare function simpleHash(str: string): number;
+/** Like TypeScript’s `Partial` for specific keys: required keys in `K` become optional. */
 export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/** `simpleHash` of JSON-stable stringification of an object. */
 export declare function simpleObjectHash(obj: any): number;
+/** Resolves after `ms` milliseconds (0 yields a microtask-yield on most runtimes). */
 export declare function sleep(ms?: number): Promise<void>;
+/** Turns `fooBar` into `Foo Bar` for labels (also replaces `_` with space). */
 export declare function camelCaseToSpaces(s?: string): string;
+/** Like {@link camelCaseToSpaces} but lowercased and joined with hyphens (kebab-case). */
 export declare function camelCaseToHyphens(s?: string): string;
+/** USD currency formatter with two fraction digits. */
 export declare const moneyFormatter: Intl.NumberFormat;
+/**
+ * Formats a number as USD. Uses {@link moneyFormatter} when `precision` is 2; otherwise builds a custom `Intl` formatter.
+ * @param value Amount in major currency units
+ * @param precision Decimal places (default 2)
+ */
 export declare function formatMoney(value: number, precision?: number): string;
+/**
+ * Caches the in-flight `Promise` per serialized argument tuple. Re-invoking with the same args returns the same promise.
+ * When `cacheTtl` is set, the cache entry is removed after that many ms after completion.
+ */
 export declare function memoizePromise<F extends (...args: any[]) => Promise<any>>(fn: F, opts?: {
     cacheTtl?: number;
 }): F;
+/**
+ * Debounces per distinct argument list: each unique `JSON.stringify(args)` gets its own debounced function (lodash debounce).
+ * @param wait Debounce wait in ms (default 300)
+ * @throws If the internal map is missing an entry (should not happen)
+ */
 export declare function debounceByArgs<F extends (...args: any[]) => any>(fn: F, wait?: number): F;
+/**
+ * Monotonic-ish high-resolution time when `performance` exists; otherwise `Date.now()`.
+ * Uses `timeOrigin + now()` in browsers; suitable for relative timing, not wall-clock.
+ */
 export declare function getTimestamp(): number;
+/**
+ * Runs `fn` with adaptive timeout from {@link IDeviceConnection.latencyMs}, retrying on error or until the op finishes.
+ * Updates `connection` latency and error rate from outcomes.
+ * @param opts.timeout Clamped timeout; defaults to {@link PeerDeviceConsts} min/max
+ * @param opts.retriesOnError Max error retries
+ * @param opts.retriesOnTimeout Max “timed out” races before giving up
+ * @throws Last error, timeout exhaustion, or if the connection is closed
+ */
 export declare function retryOnErrorOrTimeout<T>({ fn, connection, opts, }: {
     fn: () => Promise<T>;
     connection: IDeviceConnection;
@@ -34,6 +81,7 @@ export declare function retryOnErrorOrTimeout<T>({ fn, connection, opts, }: {
     };
 }): Promise<T>;
 /**
- * Table name is "name_id" if `id` is present, otherwise just "name"
+ * Physical table name: `"name_id"` when `tableId` is set, else `name`.
+ * @param metaData Table metadata from the ORM layer
  */
 export declare function getFullTableName(metaData: ITableMetaData): string;

package/dist/utils.js

@@ -22,6 +22,7 @@ const _ = require("lodash");
 const nacl = require("tweetnacl");
 const peer_device_1 = require("./types/peer-device");
 const stableStringify = require("fast-json-stable-stringify");
+/** Builds a random string of base-36 characters with unbiased distribution (tweetnacl-backed). */
 function cryptoRandomString(length) {
     let s = "";
     let r = nacl.randomBytes(length + 6);
@@ -42,6 +43,10 @@ function cryptoRandomString(length) {
     }
     return s.substring(0, length);
 }
+/**
+ * Creates a new 25-character peer id: base-36 time prefix (10 chars) + random suffix (15 chars).
+ * Sort order correlates with creation time. Use {@link isid} to validate user-provided values.
+ */
 function newid() {
     // modeled after mongo ids, timestamp + counter + random but we're going to skip counter and have bigger random
     // people can switch to using a counter + random later if they want (or do something else with the random part).
@@ -64,8 +69,14 @@ function newid() {
     const time = Date.now().toString(36).padStart(10, "0"); // e.g: "00kq6xh45f", length == 10
     return time + cryptoRandomString(15);
 }
+/** Lexicographic lower bound for valid peer ids (epoch). */
 exports.MIN_ID = "0".repeat(25); // 1970
+/** Lexicographic upper bound for valid peer ids (far future). */
 exports.MAX_ID = `f55n5nmuua${"z".repeat(15)}`; // 50k years from now
+/**
+ * Returns whether `id` is a 25-char base-36 string whose embedded time is not in the future (5 min skew allowed).
+ * @param id Candidate id (coerced to string)
+ */
 function isid(id) {
     id = String(id);
     const idMatch = Boolean(/^[0-9a-z]{25}$/i.exec(id));
@@ -76,21 +87,25 @@ function isid(id) {
     }
     return false;
 }
+/** Returns the `Date.now()`-compatible millisecond time encoded in the first 10 base-36 characters of a peer id. */
 function idTime(id) {
     const time36 = id.substr(0, 10);
     return Number.parseInt(time36, 36);
 }
+/** Interprets a peer id’s time prefix as a `Date` (see {@link idTime}). */
 function idDate(id) {
     return new Date(idTime(id));
 }
 /**
- * This returns the random number as two parts to prevent loss of precision when converting to large numbers
+ * Returns the 15-character random suffix of a peer id as two base-36 integers so large values stay exact in JS.
+ * @param id A 25-character peer id from {@link newid}
  */
 function idRandNums(id) {
     const numPart1 = id.substr(10, 8);
     const numPart2 = id.substr(18, 7);
     return [Number.parseInt(numPart1, 36), Number.parseInt(numPart2, 36)];
 }
+/** Fast non-cryptographic 32-bit string hash (sign-insensitive) for display keys and bucketing. */
 function simpleHash(str) {
     let hash = 0;
     for (let i = 0; i < str.length; i++) {
@@ -100,12 +115,15 @@ function simpleHash(str) {
     }
     return Math.abs(hash);
 }
+/** `simpleHash` of JSON-stable stringification of an object. */
 function simpleObjectHash(obj) {
     return simpleHash(stableStringify(obj));
 }
+/** Resolves after `ms` milliseconds (0 yields a microtask-yield on most runtimes). */
 function sleep(ms = 0) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/** Turns `fooBar` into `Foo Bar` for labels (also replaces `_` with space). */
 function camelCaseToSpaces(s = "") {
     s = s.replace(/([a-z])([A-Z])/g, "$1 $2");
     // s = s.replace(/(GL)([A-Z])/g, '$1 $2');  // anything like GLAccounts, GLBatches, etc.
@@ -113,16 +131,23 @@ function camelCaseToSpaces(s = "") {
     s = s[0]?.toUpperCase() + s.substr(1);
     return s;
 }
+/** Like {@link camelCaseToSpaces} but lowercased and joined with hyphens (kebab-case). */
 function camelCaseToHyphens(s = "") {
     s = camelCaseToSpaces(s);
     return s.split(" ").join("-").toLowerCase();
 }
+/** USD currency formatter with two fraction digits. */
 exports.moneyFormatter = new Intl.NumberFormat("en-US", {
     style: "currency",
     currency: "USD",
     minimumFractionDigits: 2,
     maximumFractionDigits: 2,
 });
+/**
+ * Formats a number as USD. Uses {@link moneyFormatter} when `precision` is 2; otherwise builds a custom `Intl` formatter.
+ * @param value Amount in major currency units
+ * @param precision Decimal places (default 2)
+ */
 function formatMoney(value, precision = 2) {
     if (precision === 2) {
         return exports.moneyFormatter.format(value);
@@ -135,6 +160,10 @@ function formatMoney(value, precision = 2) {
     });
     return _moneyFormatter.format(value);
 }
+/**
+ * Caches the in-flight `Promise` per serialized argument tuple. Re-invoking with the same args returns the same promise.
+ * When `cacheTtl` is set, the cache entry is removed after that many ms after completion.
+ */
 function memoizePromise(fn, opts) {
     const cache = new Map();
     const memoized = (...args) => {
@@ -156,6 +185,11 @@ function memoizePromise(fn, opts) {
     };
     return memoized;
 }
+/**
+ * Debounces per distinct argument list: each unique `JSON.stringify(args)` gets its own debounced function (lodash debounce).
+ * @param wait Debounce wait in ms (default 300)
+ * @throws If the internal map is missing an entry (should not happen)
+ */
 function debounceByArgs(fn, wait = 300) {
     const debouncedFunctions = new Map();
     const debounced = (...args) => {
@@ -172,6 +206,10 @@ function debounceByArgs(fn, wait = 300) {
     };
     return debounced;
 }
+/**
+ * Monotonic-ish high-resolution time when `performance` exists; otherwise `Date.now()`.
+ * Uses `timeOrigin + now()` in browsers; suitable for relative timing, not wall-clock.
+ */
 function getTimestamp() {
     // check if in node.js environment
     if (typeof performance === "undefined" || !performance.timeOrigin) {
@@ -180,6 +218,14 @@ function getTimestamp() {
     }
     return performance.timeOrigin + performance.now();
 }
+/**
+ * Runs `fn` with adaptive timeout from {@link IDeviceConnection.latencyMs}, retrying on error or until the op finishes.
+ * Updates `connection` latency and error rate from outcomes.
+ * @param opts.timeout Clamped timeout; defaults to {@link PeerDeviceConsts} min/max
+ * @param opts.retriesOnError Max error retries
+ * @param opts.retriesOnTimeout Max “timed out” races before giving up
+ * @throws Last error, timeout exhaustion, or if the connection is closed
+ */
 async function retryOnErrorOrTimeout({ fn, connection, opts = {}, }) {
     const timeoutMin = opts.timeout ?? peer_device_1.PeerDeviceConsts.TIMEOUT_MIN;
     const timeoutMax = opts.timeout ?? peer_device_1.PeerDeviceConsts.TIMEOUT_MAX;
@@ -244,7 +290,8 @@ async function retryOnErrorOrTimeout({ fn, connection, opts = {}, }) {
     }
 }
 /**
- * Table name is "name_id" if `id` is present, otherwise just "name"
+ * Physical table name: `"name_id"` when `tableId` is set, else `name`.
+ * @param metaData Table metadata from the ORM layer
  */
 function getFullTableName(metaData) {
     return [metaData.name, metaData.tableId].filter((v) => v && v.length > 0).join("_");

package/package.json

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