@peers-app/peers-sdk 0.20.4 → 0.20.6

package/dist/types/peer-device.d.ts

@@ -1,41 +1,77 @@
-import type { GroupMemberRole, IChangeRecord } from "../data";
+import type { GroupMemberRole, IChangeRecord, IDeviceInfo } from "../data";
 import type { DataFilter, IDataQueryParams } from "../data/orm";
+import type { ISignedObject } from "../keys";
+/** A remotely addressable Peers device that can exchange data and mesh messages. */
 export interface IPeerDevice {
+    /** Stable identifier for this device installation. */
     deviceId: string;
+    /** User identity that owns this device. */
     userId: string;
+    /** Role used when this device participates in a shared group. */
     role: GroupMemberRole;
+    /** Lists change records available from this device. */
     listChanges(filter?: DataFilter<IChangeRecord>, opts?: IDataQueryParams<IChangeRecord>): Promise<IChangeRecord[]>;
+    /** Returns current connectivity and resource information for this device. */
     getNetworkInfo(): Promise<INetworkInfo>;
+    /** Reports the latest change timestamp applied from another device. */
     notifyOfChanges(deviceId: string, timestampLastApplied: number): Promise<void>;
+    /** Sends a routed message to another device. */
     sendDeviceMessage(message: IDeviceMessage): Promise<any>;
 }
+/** A signed, routable message exchanged through the Peers device mesh. */
 export interface IDeviceMessage<T = any> {
+    /** Unique identifier used for deduplication and retention. */
     deviceMessageId: string;
+    /** Device that originated the message. */
     fromDeviceId: string;
+    /** Signed source identity used to bootstrap fresh same-user devices. */
+    fromDeviceInfo?: ISignedObject<IDeviceInfo>;
+    /** Intended destination device. */
     toDeviceId: string;
+    /** Personal or group data context in which the message is valid. */
     dataContextId: string;
+    /** Remaining forwarding hops. */
     ttl: number;
+    /** Signed or boxed application payload while in transit. */
     payload: T;
+    /** Device IDs through which the message has already passed. */
     hops: string[];
+    /** Optional preferred route supplied by routing intelligence. */
     suggestedPath?: string[];
 }
+/** Connectivity, synchronization, and resource snapshot reported by a device. */
 export interface INetworkInfo {
+    /** Device that produced this snapshot. */
     deviceId: string;
+    /** Latest change timestamp applied by the reporting device. */
     timestampLastApplied: number;
+    /** Current direct device connections. */
     connections: IDeviceConnection[];
+    /** Device IDs this device prefers to connect to. */
     preferredDeviceIds: string[];
+    /** Current CPU utilization percentage. */
     cpuPercent: number;
+    /** Current memory utilization percentage. */
     memPercent: number;
+    /** Number of additional direct connections available. */
     connectionSlotsAvailable: number;
 }
+/** Health and synchronization metadata for one direct device connection. */
 export interface IDeviceConnection {
+    /** Connected remote device. */
     deviceId: string;
+    /** Observed round-trip latency in milliseconds. */
     latencyMs: number;
+    /** Observed request error rate. */
     errorRate: number;
+    /** Latest change timestamp applied by the remote device. */
     timestampLastApplied: number;
+    /** Optional cleanup callback for closing the connection. */
     onClose?(): Promise<void>;
+    /** Whether the connection has already closed. */
     closed?: boolean;
 }
+/** Shared tuning constants for device synchronization and routing. */
 export declare const PeerDeviceConsts: Readonly<{
     readonly MAX_CONNECTIONS: 30;
     readonly RESYNC_INTERVAL: 300000;
@@ -46,6 +82,7 @@ export declare const PeerDeviceConsts: Readonly<{
     readonly TIMEOUT_MAX: 30000;
     readonly NETWORK_INFO_CACHE_TIME: 1000;
 }>;
+/** Availability and queue information for a requested file chunk. */
 export type IFileChunkInfo = {
     hasChunk: false;
 } | {

package/dist/types/peer-device.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PeerDeviceConsts = void 0;
+/** Shared tuning constants for device synchronization and routing. */
 exports.PeerDeviceConsts = Object.freeze({
     // TODO set this based on device type (desktops and servers should be able to handle 100 connections)
     MAX_CONNECTIONS: 30,

package/dist/user-connect/user-connect.pvars.d.ts

@@ -1,3 +1,20 @@
-export declare const userConnectStatus: import("../data/persistent-vars").PersistentVar<any>;
+import { type UserConnectStatus } from "./user-connect.types";
+/**
+ * Shared lifetime for connection codes, aliases, invite intents, and UI countdowns.
+ * Ten minutes from creation or capture.
+ */
+export declare const USER_CONNECT_TTL_MS = 600000;
+/**
+ * Current structured status of the local user-connect ceremony.
+ * Prefer reading through {@link normalizeUserConnectStatus} when consuming
+ * values that may have been persisted before the structured type existed.
+ */
+export declare const userConnectStatus: import("../data/persistent-vars").PersistentVar<UserConnectStatus>;
+/**
+ * Active offer connection code (12 Crockford chars). Cleared after {@link USER_CONNECT_TTL_MS}.
+ */
 export declare const userConnectCodeOffer: import("../data/persistent-vars").PersistentVar<string>;
+/**
+ * Active answer connection code (12 Crockford chars). Cleared after {@link USER_CONNECT_TTL_MS}.
+ */
 export declare const userConnectCodeAnswer: import("../data/persistent-vars").PersistentVar<string>;

package/dist/user-connect/user-connect.pvars.js

@@ -1,35 +1,63 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.userConnectCodeAnswer = exports.userConnectCodeOffer = exports.userConnectStatus = void 0;
+exports.userConnectCodeAnswer = exports.userConnectCodeOffer = exports.userConnectStatus = exports.USER_CONNECT_TTL_MS = void 0;
 const persistent_vars_1 = require("../data/persistent-vars");
-exports.userConnectStatus = (0, persistent_vars_1.deviceVar)("userConnectStatus", { defaultValue: undefined });
+const user_connect_types_1 = require("./user-connect.types");
+/**
+ * Shared lifetime for connection codes, aliases, invite intents, and UI countdowns.
+ * Ten minutes from creation or capture.
+ */
+exports.USER_CONNECT_TTL_MS = 600_000;
+/**
+ * Current structured status of the local user-connect ceremony.
+ * Prefer reading through {@link normalizeUserConnectStatus} when consuming
+ * values that may have been persisted before the structured type existed.
+ */
+exports.userConnectStatus = (0, persistent_vars_1.deviceVar)("userConnectStatus", {
+    defaultValue: user_connect_types_1.USER_CONNECT_IDLE_STATUS,
+});
+/**
+ * Active offer connection code (12 Crockford chars). Cleared after {@link USER_CONNECT_TTL_MS}.
+ */
 exports.userConnectCodeOffer = (0, persistent_vars_1.deviceVar)("userConnectCodeOffer", { defaultValue: "" });
 exports.userConnectCodeOffer.loadingPromise.then(() => {
     let codeTimeout;
-    (0, exports.userConnectStatus)("");
+    if ((0, exports.userConnectCodeOffer)()) {
+        (0, exports.userConnectCodeOffer)("");
+    }
+    (0, exports.userConnectStatus)(user_connect_types_1.USER_CONNECT_IDLE_STATUS);
     exports.userConnectCodeOffer.subscribe(() => {
-        (0, exports.userConnectStatus)("");
+        (0, exports.userConnectStatus)(user_connect_types_1.USER_CONNECT_IDLE_STATUS);
         clearTimeout(codeTimeout);
         if ((0, exports.userConnectCodeOffer)()) {
             codeTimeout = setTimeout(() => {
                 (0, exports.userConnectCodeOffer)("");
-            }, 600_000); // 10 minutes
+            }, exports.USER_CONNECT_TTL_MS);
         }
     });
 });
+/**
+ * Active answer connection code (12 Crockford chars). Cleared after {@link USER_CONNECT_TTL_MS}.
+ */
 exports.userConnectCodeAnswer = (0, persistent_vars_1.deviceVar)("userConnectCodeAnswer", {
     defaultValue: "",
 });
 exports.userConnectCodeAnswer.loadingPromise.then(() => {
     let codeTimeout;
-    (0, exports.userConnectStatus)("");
+    if ((0, exports.userConnectCodeAnswer)()) {
+        (0, exports.userConnectCodeAnswer)("");
+    }
+    (0, exports.userConnectStatus)(user_connect_types_1.USER_CONNECT_IDLE_STATUS);
     exports.userConnectCodeAnswer.subscribe(() => {
-        (0, exports.userConnectStatus)("");
+        (0, exports.userConnectStatus)(user_connect_types_1.USER_CONNECT_IDLE_STATUS);
         clearTimeout(codeTimeout);
         if ((0, exports.userConnectCodeAnswer)()) {
             codeTimeout = setTimeout(() => {
                 (0, exports.userConnectCodeAnswer)("");
-            }, 600_000); // 10 minutes
+            }, exports.USER_CONNECT_TTL_MS);
         }
     });
 });
+exports.userConnectStatus.loadingPromise.then(() => {
+    (0, exports.userConnectStatus)(user_connect_types_1.USER_CONNECT_IDLE_STATUS);
+});

package/dist/user-connect/user-connect.pvars.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/user-connect/user-connect.pvars.test.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const user_connect_types_1 = require("./user-connect.types");
+describe("normalizeUserConnectStatus", () => {
+    it("clears legacy string and malformed persisted statuses", () => {
+        expect((0, user_connect_types_1.normalizeUserConnectStatus)("")).toEqual(user_connect_types_1.USER_CONNECT_IDLE_STATUS);
+        expect((0, user_connect_types_1.normalizeUserConnectStatus)("Error: old error")).toEqual(user_connect_types_1.USER_CONNECT_IDLE_STATUS);
+        expect((0, user_connect_types_1.normalizeUserConnectStatus)("old-remote-user-id")).toEqual(user_connect_types_1.USER_CONNECT_IDLE_STATUS);
+        expect((0, user_connect_types_1.normalizeUserConnectStatus)(null)).toEqual(user_connect_types_1.USER_CONNECT_IDLE_STATUS);
+        expect((0, user_connect_types_1.normalizeUserConnectStatus)({ kind: "connected" })).toEqual(user_connect_types_1.USER_CONNECT_IDLE_STATUS);
+        expect((0, user_connect_types_1.normalizeUserConnectStatus)({ kind: "error", code: "unknown" })).toEqual(user_connect_types_1.USER_CONNECT_IDLE_STATUS);
+    });
+    it("preserves valid structured statuses", () => {
+        expect((0, user_connect_types_1.normalizeUserConnectStatus)({ kind: "offer-ready" })).toEqual({
+            kind: "offer-ready",
+        });
+        expect((0, user_connect_types_1.normalizeUserConnectStatus)({ kind: "connecting", attempt: 3 })).toEqual({
+            kind: "connecting",
+            attempt: 3,
+        });
+        expect((0, user_connect_types_1.normalizeUserConnectStatus)({
+            kind: "connected",
+            remoteUserId: "remote-user",
+            remoteDeviceId: "remote-device",
+        })).toEqual({
+            kind: "connected",
+            remoteUserId: "remote-user",
+            remoteDeviceId: "remote-device",
+        });
+        expect((0, user_connect_types_1.normalizeUserConnectStatus)({
+            kind: "error",
+            code: "remote-not-waiting",
+            detail: "diagnostic",
+        })).toEqual({
+            kind: "error",
+            code: "remote-not-waiting",
+            detail: "diagnostic",
+        });
+    });
+    it("normalizes invalid connection attempt numbers to the first attempt", () => {
+        expect((0, user_connect_types_1.normalizeUserConnectStatus)({ kind: "connecting", attempt: 0 })).toEqual({
+            kind: "connecting",
+            attempt: 1,
+        });
+    });
+});

package/dist/user-connect/user-connect.types.d.ts

@@ -4,6 +4,42 @@
  * This flow allows two users to securely exchange user information
  * using a 12-character code (4-char rendezvous alias + 8-char shared secret).
  */
+/**
+ * Stable protocol error codes for the user-connect exchange.
+ * The UI owns presentation text; the device layer reports these codes.
+ */
+export type UserConnectErrorCode = "invalid-code" | "no-route" | "not-found-or-expired" | "remote-not-waiting" | "canceled" | "protocol-error";
+/**
+ * Discriminated status published by the device layer during a user-connect ceremony.
+ */
+export type UserConnectStatus = {
+    kind: "idle";
+} | {
+    kind: "offer-registering";
+} | {
+    kind: "offer-ready";
+} | {
+    kind: "connecting";
+    attempt: number;
+} | {
+    kind: "connected";
+    remoteUserId: string;
+    remoteDeviceId: string;
+} | {
+    kind: "error";
+    code: UserConnectErrorCode;
+    detail?: string;
+};
+/** Default idle status for a quiet connection ceremony. */
+export declare const USER_CONNECT_IDLE_STATUS: UserConnectStatus;
+/**
+ * Normalize a persisted or in-memory status value to the structured shape.
+ * Clears legacy string statuses (`""`, `"Error: …"`, bare user IDs) to idle so
+ * callers never treat stale strings as protocol facts.
+ * @param value Raw pvar value
+ * @returns A valid {@link UserConnectStatus}
+ */
+export declare function normalizeUserConnectStatus(value: unknown): UserConnectStatus;
 /**
  * User information exchanged during the connection flow.
  */

package/dist/user-connect/user-connect.types.js

@@ -6,3 +6,63 @@
  * using a 12-character code (4-char rendezvous alias + 8-char shared secret).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.USER_CONNECT_IDLE_STATUS = void 0;
+exports.normalizeUserConnectStatus = normalizeUserConnectStatus;
+/** Default idle status for a quiet connection ceremony. */
+exports.USER_CONNECT_IDLE_STATUS = { kind: "idle" };
+/**
+ * Normalize a persisted or in-memory status value to the structured shape.
+ * Clears legacy string statuses (`""`, `"Error: …"`, bare user IDs) to idle so
+ * callers never treat stale strings as protocol facts.
+ * @param value Raw pvar value
+ * @returns A valid {@link UserConnectStatus}
+ */
+function normalizeUserConnectStatus(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return exports.USER_CONNECT_IDLE_STATUS;
+    }
+    const candidate = value;
+    switch (candidate.kind) {
+        case "idle":
+        case "offer-registering":
+        case "offer-ready":
+            return { kind: candidate.kind };
+        case "connecting": {
+            const attempt = value.attempt;
+            return {
+                kind: "connecting",
+                attempt: typeof attempt === "number" && attempt > 0 ? attempt : 1,
+            };
+        }
+        case "connected": {
+            const remoteUserId = value.remoteUserId;
+            const remoteDeviceId = value.remoteDeviceId;
+            if (typeof remoteUserId === "string" &&
+                remoteUserId.length > 0 &&
+                typeof remoteDeviceId === "string" &&
+                remoteDeviceId.length > 0) {
+                return { kind: "connected", remoteUserId, remoteDeviceId };
+            }
+            return exports.USER_CONNECT_IDLE_STATUS;
+        }
+        case "error": {
+            const code = value.code;
+            const detail = value.detail;
+            if (code === "invalid-code" ||
+                code === "no-route" ||
+                code === "not-found-or-expired" ||
+                code === "remote-not-waiting" ||
+                code === "canceled" ||
+                code === "protocol-error") {
+                return {
+                    kind: "error",
+                    code,
+                    detail: typeof detail === "string" ? detail : undefined,
+                };
+            }
+            return exports.USER_CONNECT_IDLE_STATUS;
+        }
+        default:
+            return exports.USER_CONNECT_IDLE_STATUS;
+    }
+}

package/package.json

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