@sixfathoms/lplex 0.1.0 → 0.2.0

package/README.md

@@ -58,6 +58,20 @@ for (const d of devices) {
 }
 ```
 
+### `client.values(signal?): Promise<DeviceValues[]>`
+
+Returns the last-seen value for each (device, PGN) pair, grouped by device. Useful for getting a snapshot of current bus state without subscribing to SSE.
+
+```typescript
+const snapshot = await client.values();
+for (const device of snapshot) {
+  console.log(`${device.manufacturer} (src=${device.src}):`);
+  for (const v of device.values) {
+    console.log(`  PGN ${v.pgn}: ${v.data} @ ${v.ts}`);
+  }
+}
+```
+
 ### `client.subscribe(filter?, signal?): Promise<AsyncIterable<Event>>`
 
 Opens an ephemeral SSE stream. No session state, no replay. Frames flow until you stop reading or abort.
@@ -285,6 +299,21 @@ interface SendParams {
   prio: number;
   data: string;            // hex-encoded
 }
+
+interface PGNValue {
+  pgn: number;
+  ts: string;              // RFC 3339 timestamp
+  data: string;            // hex-encoded payload
+  seq: number;             // sequence number
+}
+
+interface DeviceValues {
+  name: string;            // hex CAN NAME (empty if unknown)
+  src: number;             // source address
+  manufacturer?: string;
+  model_id?: string;
+  values: PGNValue[];      // sorted by PGN
+}
 ```
 
 ## Server Endpoints
@@ -297,6 +326,7 @@ interface SendParams {
 | `/clients/{id}/ack` | PUT | ACK sequence number. JSON body: `{ "seq": N }`. Returns 204. |
 | `/send` | POST | Transmit CAN frame. JSON body: `pgn`, `src`, `dst`, `prio`, `data`. Returns 202. |
 | `/devices` | GET | Device snapshot. Returns JSON array. |
+| `/values` | GET | Last-seen value per (device, PGN). Returns JSON array grouped by device. |
 
 ## License
 

package/dist/index.cjs

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   Client: () => Client,
+  CloudClient: () => CloudClient,
   HttpError: () => HttpError,
   LplexError: () => LplexError,
   Session: () => Session
@@ -169,6 +170,16 @@ var Client = class {
     }
     return resp.json();
   }
+  /** Fetch the last-seen value for each (device, PGN) pair. */
+  async values(signal) {
+    const url = `${this.#baseURL}/values`;
+    const resp = await this.#fetch(url, { signal });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("GET", url, resp.status, body);
+    }
+    return resp.json();
+  }
   /**
    * Open an ephemeral SSE stream with optional filtering.
    * No session, no replay, no ACK.
@@ -247,9 +258,64 @@ function filterToJSON(f) {
   if (f.name?.length) m.name = f.name;
   return m;
 }
+
+// src/cloud.ts
+var CloudClient = class {
+  #baseURL;
+  #fetch;
+  #fetchOpt;
+  constructor(baseURL, options) {
+    this.#baseURL = baseURL.replace(/\/+$/, "");
+    this.#fetch = options?.fetch ?? globalThis.fetch.bind(globalThis);
+    this.#fetchOpt = options ?? {};
+  }
+  /**
+   * Returns a {@link Client} scoped to a specific instance.
+   * The returned client's `devices()`, `subscribe()`, etc. hit the
+   * cloud's per-instance endpoints.
+   */
+  client(instanceId) {
+    const opts = {};
+    if (this.#fetchOpt.fetch) opts.fetch = this.#fetchOpt.fetch;
+    return new Client(`${this.#baseURL}/instances/${instanceId}`, opts);
+  }
+  /** List all known instances. */
+  async instances(signal) {
+    const url = `${this.#baseURL}/instances`;
+    const resp = await this.#fetch(url, { signal });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("GET", url, resp.status, body);
+    }
+    const data = await resp.json();
+    return data.instances;
+  }
+  /** Get detailed replication status for one instance. */
+  async status(instanceId, signal) {
+    const url = `${this.#baseURL}/instances/${instanceId}/status`;
+    const resp = await this.#fetch(url, { signal });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("GET", url, resp.status, body);
+    }
+    return resp.json();
+  }
+  /** Fetch recent replication diagnostic events for an instance. */
+  async replicationEvents(instanceId, limit, signal) {
+    let url = `${this.#baseURL}/instances/${instanceId}/replication/events`;
+    if (limit !== void 0) url += `?limit=${limit}`;
+    const resp = await this.#fetch(url, { signal });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("GET", url, resp.status, body);
+    }
+    return resp.json();
+  }
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Client,
+  CloudClient,
   HttpError,
   LplexError,
   Session

package/dist/index.d.cts

@@ -67,12 +67,61 @@ interface SendParams {
     prio: number;
     data: string;
 }
+/** A single PGN's last-known value for a device. */
+interface PGNValue {
+    pgn: number;
+    ts: string;
+    data: string;
+    seq: number;
+}
+/** Last-known values grouped by device. */
+interface DeviceValues {
+    name: string;
+    src: number;
+    manufacturer?: string;
+    model_id?: string;
+    values: PGNValue[];
+}
+/** Summary of a cloud instance, returned by GET /instances. */
+interface InstanceSummary {
+    id: string;
+    connected: boolean;
+    cursor: number;
+    boat_head_seq: number;
+    holes: number;
+    lag_seqs: number;
+    last_seen: string;
+}
+/** A sequence range representing a gap in the replication stream. */
+interface SeqRange {
+    start: number;
+    end: number;
+}
+/** Detailed replication status for one instance. */
+interface InstanceStatus {
+    id: string;
+    connected: boolean;
+    cursor: number;
+    boat_head_seq: number;
+    boat_journal_bytes: number;
+    holes: SeqRange[];
+    lag_seqs: number;
+    last_seen: string;
+}
+/** Event types emitted by the replication pipeline. */
+type ReplicationEventType = "live_start" | "live_stop" | "backfill_start" | "backfill_stop" | "block_received" | "checkpoint";
+/** A single diagnostic event from the replication pipeline. */
+interface ReplicationEvent {
+    time: string;
+    type: ReplicationEventType;
+    detail?: Record<string, unknown>;
+}
 
-type FetchFn$1 = typeof globalThis.fetch;
+type FetchFn$2 = typeof globalThis.fetch;
 declare class Session {
     #private;
     /** @internal Created by Client.createSession, not for direct use. */
-    constructor(baseURL: string, fetchFn: FetchFn$1, info: SessionInfo);
+    constructor(baseURL: string, fetchFn: FetchFn$2, info: SessionInfo);
     get info(): SessionInfo;
     get lastAckedSeq(): number;
     /**
@@ -84,15 +133,17 @@ declare class Session {
     ack(seq: number, signal?: AbortSignal): Promise<void>;
 }
 
-type FetchFn = typeof globalThis.fetch;
+type FetchFn$1 = typeof globalThis.fetch;
 interface ClientOptions {
-    fetch?: FetchFn;
+    fetch?: FetchFn$1;
 }
 declare class Client {
     #private;
     constructor(baseURL: string, options?: ClientOptions);
     /** Fetch a snapshot of all NMEA 2000 devices discovered by the server. */
     devices(signal?: AbortSignal): Promise<Device[]>;
+    /** Fetch the last-seen value for each (device, PGN) pair. */
+    values(signal?: AbortSignal): Promise<DeviceValues[]>;
     /**
      * Open an ephemeral SSE stream with optional filtering.
      * No session, no replay, no ACK.
@@ -104,6 +155,33 @@ declare class Client {
     createSession(config: SessionConfig, signal?: AbortSignal): Promise<Session>;
 }
 
+type FetchFn = typeof globalThis.fetch;
+interface CloudClientOptions {
+    fetch?: FetchFn;
+}
+/**
+ * Client for the lplex-cloud management API.
+ *
+ * For per-instance data (devices, SSE), use {@link client} to get a
+ * regular {@link Client} scoped to that instance.
+ */
+declare class CloudClient {
+    #private;
+    constructor(baseURL: string, options?: CloudClientOptions);
+    /**
+     * Returns a {@link Client} scoped to a specific instance.
+     * The returned client's `devices()`, `subscribe()`, etc. hit the
+     * cloud's per-instance endpoints.
+     */
+    client(instanceId: string): Client;
+    /** List all known instances. */
+    instances(signal?: AbortSignal): Promise<InstanceSummary[]>;
+    /** Get detailed replication status for one instance. */
+    status(instanceId: string, signal?: AbortSignal): Promise<InstanceStatus>;
+    /** Fetch recent replication diagnostic events for an instance. */
+    replicationEvents(instanceId: string, limit?: number, signal?: AbortSignal): Promise<ReplicationEvent[]>;
+}
+
 declare class LplexError extends Error {
     constructor(message: string);
 }
@@ -113,4 +191,4 @@ declare class HttpError extends LplexError {
     constructor(method: string, path: string, status: number, body: string);
 }
 
-export { Client, type ClientOptions, type Device, type Event, type Filter, type Frame, HttpError, LplexError, type SendParams, Session, type SessionConfig, type SessionInfo };
+export { Client, type ClientOptions, CloudClient, type CloudClientOptions, type Device, type DeviceValues, type Event, type Filter, type Frame, HttpError, type InstanceStatus, type InstanceSummary, LplexError, type PGNValue, type ReplicationEvent, type ReplicationEventType, type SendParams, type SeqRange, Session, type SessionConfig, type SessionInfo };

package/dist/index.d.ts

@@ -67,12 +67,61 @@ interface SendParams {
     prio: number;
     data: string;
 }
+/** A single PGN's last-known value for a device. */
+interface PGNValue {
+    pgn: number;
+    ts: string;
+    data: string;
+    seq: number;
+}
+/** Last-known values grouped by device. */
+interface DeviceValues {
+    name: string;
+    src: number;
+    manufacturer?: string;
+    model_id?: string;
+    values: PGNValue[];
+}
+/** Summary of a cloud instance, returned by GET /instances. */
+interface InstanceSummary {
+    id: string;
+    connected: boolean;
+    cursor: number;
+    boat_head_seq: number;
+    holes: number;
+    lag_seqs: number;
+    last_seen: string;
+}
+/** A sequence range representing a gap in the replication stream. */
+interface SeqRange {
+    start: number;
+    end: number;
+}
+/** Detailed replication status for one instance. */
+interface InstanceStatus {
+    id: string;
+    connected: boolean;
+    cursor: number;
+    boat_head_seq: number;
+    boat_journal_bytes: number;
+    holes: SeqRange[];
+    lag_seqs: number;
+    last_seen: string;
+}
+/** Event types emitted by the replication pipeline. */
+type ReplicationEventType = "live_start" | "live_stop" | "backfill_start" | "backfill_stop" | "block_received" | "checkpoint";
+/** A single diagnostic event from the replication pipeline. */
+interface ReplicationEvent {
+    time: string;
+    type: ReplicationEventType;
+    detail?: Record<string, unknown>;
+}
 
-type FetchFn$1 = typeof globalThis.fetch;
+type FetchFn$2 = typeof globalThis.fetch;
 declare class Session {
     #private;
     /** @internal Created by Client.createSession, not for direct use. */
-    constructor(baseURL: string, fetchFn: FetchFn$1, info: SessionInfo);
+    constructor(baseURL: string, fetchFn: FetchFn$2, info: SessionInfo);
     get info(): SessionInfo;
     get lastAckedSeq(): number;
     /**
@@ -84,15 +133,17 @@ declare class Session {
     ack(seq: number, signal?: AbortSignal): Promise<void>;
 }
 
-type FetchFn = typeof globalThis.fetch;
+type FetchFn$1 = typeof globalThis.fetch;
 interface ClientOptions {
-    fetch?: FetchFn;
+    fetch?: FetchFn$1;
 }
 declare class Client {
     #private;
     constructor(baseURL: string, options?: ClientOptions);
     /** Fetch a snapshot of all NMEA 2000 devices discovered by the server. */
     devices(signal?: AbortSignal): Promise<Device[]>;
+    /** Fetch the last-seen value for each (device, PGN) pair. */
+    values(signal?: AbortSignal): Promise<DeviceValues[]>;
     /**
      * Open an ephemeral SSE stream with optional filtering.
      * No session, no replay, no ACK.
@@ -104,6 +155,33 @@ declare class Client {
     createSession(config: SessionConfig, signal?: AbortSignal): Promise<Session>;
 }
 
+type FetchFn = typeof globalThis.fetch;
+interface CloudClientOptions {
+    fetch?: FetchFn;
+}
+/**
+ * Client for the lplex-cloud management API.
+ *
+ * For per-instance data (devices, SSE), use {@link client} to get a
+ * regular {@link Client} scoped to that instance.
+ */
+declare class CloudClient {
+    #private;
+    constructor(baseURL: string, options?: CloudClientOptions);
+    /**
+     * Returns a {@link Client} scoped to a specific instance.
+     * The returned client's `devices()`, `subscribe()`, etc. hit the
+     * cloud's per-instance endpoints.
+     */
+    client(instanceId: string): Client;
+    /** List all known instances. */
+    instances(signal?: AbortSignal): Promise<InstanceSummary[]>;
+    /** Get detailed replication status for one instance. */
+    status(instanceId: string, signal?: AbortSignal): Promise<InstanceStatus>;
+    /** Fetch recent replication diagnostic events for an instance. */
+    replicationEvents(instanceId: string, limit?: number, signal?: AbortSignal): Promise<ReplicationEvent[]>;
+}
+
 declare class LplexError extends Error {
     constructor(message: string);
 }
@@ -113,4 +191,4 @@ declare class HttpError extends LplexError {
     constructor(method: string, path: string, status: number, body: string);
 }
 
-export { Client, type ClientOptions, type Device, type Event, type Filter, type Frame, HttpError, LplexError, type SendParams, Session, type SessionConfig, type SessionInfo };
+export { Client, type ClientOptions, CloudClient, type CloudClientOptions, type Device, type DeviceValues, type Event, type Filter, type Frame, HttpError, type InstanceStatus, type InstanceSummary, LplexError, type PGNValue, type ReplicationEvent, type ReplicationEventType, type SendParams, type SeqRange, Session, type SessionConfig, type SessionInfo };

package/dist/index.js

@@ -140,6 +140,16 @@ var Client = class {
     }
     return resp.json();
   }
+  /** Fetch the last-seen value for each (device, PGN) pair. */
+  async values(signal) {
+    const url = `${this.#baseURL}/values`;
+    const resp = await this.#fetch(url, { signal });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("GET", url, resp.status, body);
+    }
+    return resp.json();
+  }
   /**
    * Open an ephemeral SSE stream with optional filtering.
    * No session, no replay, no ACK.
@@ -218,8 +228,63 @@ function filterToJSON(f) {
   if (f.name?.length) m.name = f.name;
   return m;
 }
+
+// src/cloud.ts
+var CloudClient = class {
+  #baseURL;
+  #fetch;
+  #fetchOpt;
+  constructor(baseURL, options) {
+    this.#baseURL = baseURL.replace(/\/+$/, "");
+    this.#fetch = options?.fetch ?? globalThis.fetch.bind(globalThis);
+    this.#fetchOpt = options ?? {};
+  }
+  /**
+   * Returns a {@link Client} scoped to a specific instance.
+   * The returned client's `devices()`, `subscribe()`, etc. hit the
+   * cloud's per-instance endpoints.
+   */
+  client(instanceId) {
+    const opts = {};
+    if (this.#fetchOpt.fetch) opts.fetch = this.#fetchOpt.fetch;
+    return new Client(`${this.#baseURL}/instances/${instanceId}`, opts);
+  }
+  /** List all known instances. */
+  async instances(signal) {
+    const url = `${this.#baseURL}/instances`;
+    const resp = await this.#fetch(url, { signal });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("GET", url, resp.status, body);
+    }
+    const data = await resp.json();
+    return data.instances;
+  }
+  /** Get detailed replication status for one instance. */
+  async status(instanceId, signal) {
+    const url = `${this.#baseURL}/instances/${instanceId}/status`;
+    const resp = await this.#fetch(url, { signal });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("GET", url, resp.status, body);
+    }
+    return resp.json();
+  }
+  /** Fetch recent replication diagnostic events for an instance. */
+  async replicationEvents(instanceId, limit, signal) {
+    let url = `${this.#baseURL}/instances/${instanceId}/replication/events`;
+    if (limit !== void 0) url += `?limit=${limit}`;
+    const resp = await this.#fetch(url, { signal });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("GET", url, resp.status, body);
+    }
+    return resp.json();
+  }
+};
 export {
   Client,
+  CloudClient,
   HttpError,
   LplexError,
   Session

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sixfathoms/lplex",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript client for lplex CAN bus HTTP bridge",
   "type": "module",
   "main": "./dist/index.cjs",