@peers-app/peers-sdk 0.20.4 → 0.20.5

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