@peers-app/peers-sdk 0.30.2 → 0.30.3

package/dist/contracts/system/mesh-metrics-types.d.ts

@@ -0,0 +1,148 @@
+/** Trigger for an overlapping, at most five-minute connectivity measurement. */
+export type MeshEpisodeReason = "startup" | "resume" | "network-change" | "connection-loss";
+/** Provenance of a dial; explicit requests and group joins are also distinguished. */
+export type MeshDialReason = "own-device" | "group-network-info" | "broadcast-answer" | "configured-server" | "lan-scan" | "websocket-upgrade" | "incoming" | "direct-request" | "group-join";
+/** Bounded path categories used for lifetime counters; attempts also retain the address. */
+export type MeshPath = "websocket" | "webrtc" | "cloud" | "discovery";
+/** Failure categories, independent of free-form transport error messages. */
+export type MeshFailureReason = "ttl0" | "no-route" | "signaling-timeout" | "socket-error" | "socket-timeout" | "handshake" | "rejected" | "closed" | "superseded" | "unsupported";
+/** Observed stage; timestamps are offsets in milliseconds from the attempt's queued time. */
+export type MeshStage = "queued" | "started" | "authenticated" | "admitted" | "ready" | "firstSync";
+/** Optional observational metadata passed through a dial without affecting its result. */
+export interface IMeshDial {
+    attemptId?: string;
+    reason?: MeshDialReason;
+    targetDeviceId?: string;
+}
+/** One dial or inbound connection. Missing stages have not been observed. */
+export interface IMeshAttempt {
+    attemptId: string;
+    targetDeviceId?: string;
+    reason: MeshDialReason;
+    direction: "outgoing" | "incoming";
+    path: MeshPath;
+    address?: string;
+    queuedAt: number;
+    stages: Partial<Record<MeshStage, number>>;
+    answeredDeviceId?: string;
+    expectedIdentity?: boolean;
+    answered: boolean;
+    lastSignalFailure?: {
+        reason: "ttl0" | "no-route";
+        detail?: string;
+    };
+    ready: Record<string, number>;
+    firstSync: Record<string, number>;
+    outcome: "pending" | "admitted" | "failed" | "unfinished";
+    endReason?: "buffer-evicted" | "disposed";
+    endedAt?: number;
+    durationMs?: number;
+    failure?: {
+        stage: MeshStage;
+        reason: MeshFailureReason;
+        detail?: string;
+    };
+    doubleDial: boolean;
+    offline: boolean;
+    outOfOrder: boolean;
+}
+/** Millisecond durations derived from one episode; absent means not observed. */
+export interface IMeshDurations {
+    T_first?: number;
+    T_own?: number;
+    T_cover?: number;
+    T_resume?: number;
+    repairStart?: number;
+}
+/** Coverage at the latest observation (at completion for a finished episode). */
+export interface IMeshContextCoverage {
+    dataContextId: string;
+    possibleSourceDeviceIds: string[];
+    usableDeviceIds: string[];
+    excluded: boolean;
+}
+/** One connectivity episode, independent of any other episode in flight. */
+export interface IMeshEpisode {
+    episodeId: string;
+    reason: MeshEpisodeReason;
+    trigger?: string;
+    startedAt: number;
+    endedAt?: number;
+    durationMs?: number;
+    outcome: "active" | "covered" | "unfinished";
+    endReason?: "covered" | "deadline" | "buffer-evicted" | "disposed";
+    metrics: IMeshDurations;
+    contexts: IMeshContextCoverage[];
+}
+/** Nearest-rank percentiles of observed values only; count exposes the denominator. */
+export interface IMeshPercentiles {
+    count: number;
+    p50?: number;
+    p90?: number;
+    p95?: number;
+    p99?: number;
+}
+/** Lifetime dial totals. Incoming connections are separate from the outgoing-dial ratio. */
+export interface IMeshPathCounters {
+    dials: number;
+    connections: number;
+    incomingConnections: number;
+    dialsPerConnection: number | null;
+    failures: Partial<Record<MeshFailureReason, number>>;
+}
+/** Shared relay totals and current gauges, also exposed on non-Services hosts. */
+export interface IMeshServicesCounters {
+    directRelays: number;
+    floodsForwarded: number;
+    floodsPruned: number;
+    pendingEmits: number;
+    concurrentConnections: number;
+    connects: number;
+    disconnects: number;
+}
+/** In-memory diagnostics snapshot. No history survives a runtime restart. */
+export interface IMeshStats {
+    startedAt: number;
+    sampledAt: number;
+    uptimeMs: number;
+    readyToDialMs?: number;
+    limits: {
+        episodes: number;
+        attempts: number;
+        episodeMs: number;
+    };
+    currentEpisodes: IMeshEpisode[];
+    recentEpisodes: IMeshEpisode[];
+    percentiles: Record<keyof IMeshDurations, IMeshPercentiles>;
+    counters: {
+        paths: Record<MeshPath, IMeshPathCounters>;
+        lanScan: {
+            scans: number;
+            probes: number;
+            connected: number;
+        };
+        unfinishedAttempts: number;
+        doubleDials: number;
+        offlineDials: number;
+        offlineDialsPerHour: number;
+        broadcasts: {
+            sent: number;
+            answered: number;
+            ttl0: number;
+            failed: number;
+            pending: number;
+            perHour: number;
+        };
+        services: IMeshServicesCounters;
+    };
+    recentAttempts: IMeshAttempt[];
+    recentBroadcasts: IMeshBroadcast[];
+}
+/** A discovery broadcast and its observed reply, bounded with the attempt history. */
+export interface IMeshBroadcast {
+    broadcastId: string;
+    dataContextId?: string;
+    sentAt: number;
+    durationMs?: number;
+    outcome: "pending" | "answered" | "ttl0" | "failed";
+}

package/dist/contracts/system/mesh-metrics-types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/system/network-contracts.d.ts

@@ -4,12 +4,15 @@ import type { Observable } from "../../observable";
 import type { INetworkInfo } from "../../types/peer-device";
 import type { IContractConsumerBase } from "../contract-proxy";
 import type { IContractDefinition } from "../types";
+import type { IMeshStats } from "./mesh-metrics-types";
+export type * from "./mesh-metrics-types";
 /** Version of the built-in System Network Diagnostics contract. */
 export declare const NETWORK_DIAGNOSTICS_CONTRACT_VERSION = 1;
 /** Version of the built-in System Network Control contract. */
 export declare const NETWORK_CONTROL_CONTRACT_VERSION = 1;
 /** Stable IDs for tools in System Network Diagnostics v1. */
 export declare const networkDiagnosticsToolIds: {
+    readonly getMeshStats: string;
     readonly getOverview: "00ms1yb50ym353ads0gel5jpv";
     readonly getConnections: "00ms1yb50ykny9kdgiclpa1t4";
     readonly getGroupSyncStatus: "00ms1yb50yp2q7jr0jglzsztq";
@@ -241,6 +244,11 @@ export interface INetworkDiagnosticsConsumer extends IContractConsumerBase {
         getOverview(): Promise<{
             overview: INetworkOverview;
         }>;
+        getMeshStats(input?: {
+            limit?: number;
+        }): Promise<{
+            stats: IMeshStats;
+        }>;
         getConnections(): Promise<{
             connections: INetworkConnectionInfo[];
         }>;

package/dist/contracts/system/network-contracts.js

@@ -6,12 +6,18 @@ exports.getNetworkControlContractDefinition = getNetworkControlContractDefinitio
 const system_ids_1 = require("../../system-ids");
 const field_type_1 = require("../../types/field-type");
 const system_contracts_1 = require("../system-contracts");
+const tool_catalog_identity_1 = require("../tool-catalog-identity");
 /** Version of the built-in System Network Diagnostics contract. */
 exports.NETWORK_DIAGNOSTICS_CONTRACT_VERSION = 1;
 /** Version of the built-in System Network Control contract. */
 exports.NETWORK_CONTROL_CONTRACT_VERSION = 1;
 /** Stable IDs for tools in System Network Diagnostics v1. */
 exports.networkDiagnosticsToolIds = {
+    getMeshStats: (0, tool_catalog_identity_1.deriveToolCatalogId)({
+        contractId: system_ids_1.networkDiagnosticsContractId,
+        version: exports.NETWORK_DIAGNOSTICS_CONTRACT_VERSION,
+        toolName: "getMeshStats",
+    }),
     getOverview: "00ms1yb50ym353ads0gel5jpv",
     getConnections: "00ms1yb50ykny9kdgiclpa1t4",
     getGroupSyncStatus: "00ms1yb50yp2q7jr0jglzsztq",
@@ -46,6 +52,16 @@ function getNetworkDiagnosticsContractDefinition() {
         description: "Portable local network, connection, and synchronization diagnostics.",
         tables: [],
         tools: [
+            {
+                name: "getMeshStats",
+                usageDescription: "Read bounded in-memory connectivity episodes, attempts, percentiles and relay counters.",
+                inputFields: [
+                    field("limit", field_type_1.FieldType.number, "Maximum recent attempts and broadcasts (default 50, range 0–500). Episodes and counters are always complete.", { optional: true }),
+                ],
+                outputFields: [
+                    field("stats", field_type_1.FieldType.object, "Connectivity measurements since runtime startup."),
+                ],
+            },
             {
                 name: "getOverview",
                 usageDescription: "Return aggregate network and group information.",

package/dist/data/files/files.js

@@ -3,7 +3,6 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FilesTable = void 0;
 exports.Files = Files;
 const user_context_singleton_1 = require("../../context/user-context-singleton");
-const rpc_types_1 = require("../../rpc-types");
 const orm_1 = require("../orm");
 const table_definitions_system_1 = require("../orm/table-definitions.system");
 const chunk_store_1 = require("./chunk-store");
@@ -166,18 +165,3 @@ exports.FilesTable = FilesTable;
 function Files(dataContext) {
     return (0, user_context_singleton_1.getTableContainer)(dataContext).getTable(file_types_1.filesMetaData, file_types_1.fileSchema);
 }
-// Deprecated RPCs, kept only for Family Hub 0.3.x until its port is Home's version. New code
-// uses System Files, which is bound to the caller's own data context.
-rpc_types_1.rpcServerCalls.getFileContentsBase64 = async (fileId) => {
-    const data = await Files().getFileContents(fileId);
-    if (data === null) {
-        throw new Error(`File not found: ${fileId}`);
-    }
-    return Buffer.from(data).toString("base64");
-};
-rpc_types_1.rpcServerCalls.saveFile = async (input) => {
-    const encoding = input.encoding || "utf8";
-    const dataBuffer = encoding === "base64" ? Buffer.from(input.data, "base64") : Buffer.from(input.data, "utf8");
-    // Kept: Family Hub 0.3.x doesn't declare its file fields, so nothing would reference these.
-    return await Files().saveFile({ name: input.name, mimeType: input.mimeType, keep: true }, new Uint8Array(dataBuffer));
-};

package/dist/device/connection.d.ts

@@ -21,6 +21,9 @@ export declare class Connection {
     private _remoteDeviceInfo;
     /** Trust assigned to the remote identity once the handshake completes. */
     trustLevel: TrustLevel;
+    /** Synchronous diagnostics only; observer errors cannot affect handshake results. */
+    onHandshakeObserved?: (stage: "authenticated" | "failed", error?: unknown) => void;
+    private observeHandshake;
     /** Server-side hook fired shortly after the successful handshake reply has been sent. */
     onHandshakeComplete: ((deviceInfo: IDeviceInfo) => void) | undefined;
     /** RPC timeout for {@link Connection.emit}. */

package/dist/device/connection.js

@@ -32,6 +32,16 @@ class Connection {
     };
     /** Trust assigned to the remote identity once the handshake completes. */
     trustLevel = socket_type_1.TrustLevel.Unknown;
+    /** Synchronous diagnostics only; observer errors cannot affect handshake results. */
+    onHandshakeObserved;
+    observeHandshake(stage, error) {
+        try {
+            this.onHandshakeObserved?.(stage, error);
+        }
+        catch {
+            /* diagnostics never affect the handshake */
+        }
+    }
     /** Server-side hook fired shortly after the successful handshake reply has been sent. */
     onHandshakeComplete;
     /** RPC timeout for {@link Connection.emit}. */
@@ -133,6 +143,7 @@ class Connection {
             }
         }
         catch (e) {
+            this.observeHandshake("failed", e);
             console.error("Error handling completeHandshake", e);
             callback({ error: e?.message ?? String(e), errorType: "RPC_ERROR" });
         }
@@ -412,6 +423,7 @@ class Connection {
         };
         this.trustLevel = trustLevel;
         this._verified = true;
+        this.observeHandshake("authenticated");
         return handshakeResponse;
     }
     /**
@@ -459,6 +471,7 @@ class Connection {
             return handshakeResponse;
         }
         catch (e) {
+            this.observeHandshake("failed", e);
             // A failed or timed-out attempt must neither retain its ephemeral secret nor let a
             // late reply authenticate it. Do not clear state belonging to a newer handshake.
             if (generation === this.handshakeGeneration)
@@ -522,6 +535,7 @@ class Connection {
                 : remoteDeviceInfo.deviceName,
         };
         this._verified = true;
+        this.observeHandshake("authenticated");
         this._connectionAddress = remoteAddress;
         return handshakeResponse;
     }

package/dist/rpc-types.d.ts

@@ -29,28 +29,6 @@ export interface IRemoteLogsQueryInput {
 export declare const rpcServerCalls: {
     encryptData: (value: string, groupId?: string) => Promise<string>;
     tableMethodCall: (dataContextId: string, tableName: string, methodName: string, ...args: any[]) => Promise<any>;
-    /**
-     * @deprecated Use System Files (`SystemFiles`, `readWholeFile`). Kept only for Family Hub
-     * 0.3.x; deleted once its port is Home's version.
-     */
-    getFileContentsBase64: (fileId: string) => Promise<string>;
-    /**
-     * @deprecated Use System Files (`SystemFiles`). Kept only for Family Hub 0.3.x; deleted once
-     * its port is Home's version.
-     */
-    saveFile: (input: {
-        name: string;
-        mimeType?: string;
-        data: string;
-        encoding?: "utf8" | "base64";
-        fileId?: string;
-    }) => Promise<{
-        fileId: string;
-        name: string;
-        fileSize: number;
-        fileHash: string;
-        mimeType?: string;
-    }>;
     deleteLocalDatabase: () => Promise<void>;
     /** Returns info about the pre-migration data directory, or `null` if already cleaned up. */
     getOldDataDirInfo: () => Promise<{

package/dist/rpc-types.js

@@ -14,16 +14,6 @@ function rpcStub(rpcName) {
 exports.rpcServerCalls = {
     encryptData: rpcStub("encryptData"),
     tableMethodCall: rpcStub("tableMethodCall"),
-    /**
-     * @deprecated Use System Files (`SystemFiles`, `readWholeFile`). Kept only for Family Hub
-     * 0.3.x; deleted once its port is Home's version.
-     */
-    getFileContentsBase64: rpcStub("getFileContentsBase64"),
-    /**
-     * @deprecated Use System Files (`SystemFiles`). Kept only for Family Hub 0.3.x; deleted once
-     * its port is Home's version.
-     */
-    saveFile: rpcStub("saveFile"),
     deleteLocalDatabase: rpcStub("deleteLocalDatabase"),
     /** Returns info about the pre-migration data directory, or `null` if already cleaned up. */
     getOldDataDirInfo: rpcStub("getOldDataDirInfo"),

package/package.json

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