@sixfathoms/lplex 0.2.0 → 0.3.0

package/README.md

@@ -58,7 +58,7 @@ for (const d of devices) {
 }
 ```
 
-### `client.values(signal?): Promise<DeviceValues[]>`
+### `client.values(filter?, 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.
 
@@ -72,6 +72,15 @@ for (const device of snapshot) {
 }
 ```
 
+Pass a `Filter` to narrow results by PGN and/or device criteria:
+
+```typescript
+const positions = await client.values({
+  pgn: [129025],
+  manufacturer: ["Garmin"],
+});
+```
+
 ### `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.
@@ -326,7 +335,7 @@ interface DeviceValues {
 | `/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. |
+| `/values` | GET | Last-seen value per (device, PGN). Query params: `pgn`, `manufacturer`, `instance`, `name` (repeatable). Returns JSON array grouped by device. |
 
 ## License
 

package/dist/index.cjs

@@ -171,8 +171,10 @@ var Client = class {
     return resp.json();
   }
   /** Fetch the last-seen value for each (device, PGN) pair. */
-  async values(signal) {
-    const url = `${this.#baseURL}/values`;
+  async values(filter, signal) {
+    let url = `${this.#baseURL}/values`;
+    const qs = filterToQueryString(filter);
+    if (qs) url += `?${qs}`;
     const resp = await this.#fetch(url, { signal });
     if (!resp.ok) {
       const body = await resp.text();
@@ -201,6 +203,18 @@ var Client = class {
     }
     return parseSSE(resp.body);
   }
+  /** Fetch the last-seen decoded values for each (device, PGN) pair. */
+  async decodedValues(filter, signal) {
+    let url = `${this.#baseURL}/values/decoded`;
+    const qs = filterToQueryString(filter);
+    if (qs) url += `?${qs}`;
+    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();
+  }
   /** Transmit a CAN frame through the server. */
   async send(params, signal) {
     const url = `${this.#baseURL}/send`;
@@ -215,6 +229,44 @@ var Client = class {
       throw new HttpError("POST", url, resp.status, body);
     }
   }
+  /**
+   * Send an ISO Request (PGN 59904) and wait for the response frame.
+   * Returns the response frame, or throws HttpError with status 504 on timeout.
+   */
+  async query(params, signal) {
+    const url = `${this.#baseURL}/query`;
+    const resp = await this.#fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(params),
+      signal
+    });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("POST", url, resp.status, body);
+    }
+    return resp.json();
+  }
+  /** Check server health. */
+  async health(signal) {
+    const url = `${this.#baseURL}/healthz`;
+    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 boat-side replication status (only available when replication is configured). */
+  async replicationStatus(signal) {
+    const url = `${this.#baseURL}/replication/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();
+  }
   /** Create or reconnect a buffered session on the server. */
   async createSession(config, signal) {
     const url = `${this.#baseURL}/clients/${config.clientId}`;
@@ -239,23 +291,28 @@ var Client = class {
   }
 };
 function filterIsEmpty(f) {
-  return !f.pgn?.length && !f.manufacturer?.length && !f.instance?.length && !f.name?.length;
+  return !f.pgn?.length && !f.exclude_pgn?.length && !f.manufacturer?.length && !f.instance?.length && !f.name?.length && !f.exclude_name?.length;
 }
 function filterToQueryString(f) {
   if (!f || filterIsEmpty(f)) return "";
   const params = new URLSearchParams();
   for (const p of f.pgn ?? []) params.append("pgn", p.toString());
+  for (const p of f.exclude_pgn ?? [])
+    params.append("exclude_pgn", p.toString());
   for (const m of f.manufacturer ?? []) params.append("manufacturer", m);
   for (const i of f.instance ?? []) params.append("instance", i.toString());
   for (const n of f.name ?? []) params.append("name", n);
+  for (const n of f.exclude_name ?? []) params.append("exclude_name", n);
   return params.toString();
 }
 function filterToJSON(f) {
   const m = {};
   if (f.pgn?.length) m.pgn = f.pgn;
+  if (f.exclude_pgn?.length) m.exclude_pgn = f.exclude_pgn;
   if (f.manufacturer?.length) m.manufacturer = f.manufacturer;
   if (f.instance?.length) m.instance = f.instance;
   if (f.name?.length) m.name = f.name;
+  if (f.exclude_name?.length) m.exclude_name = f.exclude_name;
   return m;
 }
 

package/dist/index.d.cts

@@ -42,9 +42,11 @@ type Event = {
  */
 interface Filter {
     pgn?: number[];
+    exclude_pgn?: number[];
     manufacturer?: string[];
     instance?: number[];
     name?: string[];
+    exclude_name?: string[];
 }
 /** Configuration for creating a buffered session. */
 interface SessionConfig {
@@ -82,6 +84,43 @@ interface DeviceValues {
     model_id?: string;
     values: PGNValue[];
 }
+/** A single PGN's decoded value for a device. */
+interface DecodedPGNValue {
+    pgn: number;
+    ts: string;
+    data: string;
+    seq: number;
+    decoded: Record<string, unknown>;
+}
+/** Decoded values grouped by device. */
+interface DecodedDeviceValues {
+    name: string;
+    src: number;
+    manufacturer?: string;
+    model_id?: string;
+    values: DecodedPGNValue[];
+}
+/** Parameters for an ISO Request query (POST /query). */
+interface QueryParams {
+    pgn: number;
+    dst: number;
+    timeout?: string;
+}
+/** Health check response from GET /healthz. */
+interface HealthStatus {
+    status: string;
+}
+/** Boat-side replication status from GET /replication/status. */
+interface ReplicationStatus {
+    connected: boolean;
+    instance_id: string;
+    local_head_seq: number;
+    cloud_cursor: number;
+    holes: SeqRange[];
+    live_lag: number;
+    backfill_remaining_seqs: number;
+    last_ack: string;
+}
 /** Summary of a cloud instance, returned by GET /instances. */
 interface InstanceSummary {
     id: string;
@@ -143,14 +182,25 @@ declare class Client {
     /** 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[]>;
+    values(filter?: Filter, signal?: AbortSignal): Promise<DeviceValues[]>;
     /**
      * Open an ephemeral SSE stream with optional filtering.
      * No session, no replay, no ACK.
      */
     subscribe(filter?: Filter, signal?: AbortSignal): Promise<AsyncIterable<Event>>;
+    /** Fetch the last-seen decoded values for each (device, PGN) pair. */
+    decodedValues(filter?: Filter, signal?: AbortSignal): Promise<DecodedDeviceValues[]>;
     /** Transmit a CAN frame through the server. */
     send(params: SendParams, signal?: AbortSignal): Promise<void>;
+    /**
+     * Send an ISO Request (PGN 59904) and wait for the response frame.
+     * Returns the response frame, or throws HttpError with status 504 on timeout.
+     */
+    query(params: QueryParams, signal?: AbortSignal): Promise<Frame>;
+    /** Check server health. */
+    health(signal?: AbortSignal): Promise<HealthStatus>;
+    /** Fetch boat-side replication status (only available when replication is configured). */
+    replicationStatus(signal?: AbortSignal): Promise<ReplicationStatus>;
     /** Create or reconnect a buffered session on the server. */
     createSession(config: SessionConfig, signal?: AbortSignal): Promise<Session>;
 }
@@ -191,4 +241,4 @@ declare class HttpError extends LplexError {
     constructor(method: string, path: string, status: number, body: string);
 }
 
-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 };
+export { Client, type ClientOptions, CloudClient, type CloudClientOptions, type DecodedDeviceValues, type DecodedPGNValue, type Device, type DeviceValues, type Event, type Filter, type Frame, type HealthStatus, HttpError, type InstanceStatus, type InstanceSummary, LplexError, type PGNValue, type QueryParams, type ReplicationEvent, type ReplicationEventType, type ReplicationStatus, type SendParams, type SeqRange, Session, type SessionConfig, type SessionInfo };

package/dist/index.d.ts

@@ -42,9 +42,11 @@ type Event = {
  */
 interface Filter {
     pgn?: number[];
+    exclude_pgn?: number[];
     manufacturer?: string[];
     instance?: number[];
     name?: string[];
+    exclude_name?: string[];
 }
 /** Configuration for creating a buffered session. */
 interface SessionConfig {
@@ -82,6 +84,43 @@ interface DeviceValues {
     model_id?: string;
     values: PGNValue[];
 }
+/** A single PGN's decoded value for a device. */
+interface DecodedPGNValue {
+    pgn: number;
+    ts: string;
+    data: string;
+    seq: number;
+    decoded: Record<string, unknown>;
+}
+/** Decoded values grouped by device. */
+interface DecodedDeviceValues {
+    name: string;
+    src: number;
+    manufacturer?: string;
+    model_id?: string;
+    values: DecodedPGNValue[];
+}
+/** Parameters for an ISO Request query (POST /query). */
+interface QueryParams {
+    pgn: number;
+    dst: number;
+    timeout?: string;
+}
+/** Health check response from GET /healthz. */
+interface HealthStatus {
+    status: string;
+}
+/** Boat-side replication status from GET /replication/status. */
+interface ReplicationStatus {
+    connected: boolean;
+    instance_id: string;
+    local_head_seq: number;
+    cloud_cursor: number;
+    holes: SeqRange[];
+    live_lag: number;
+    backfill_remaining_seqs: number;
+    last_ack: string;
+}
 /** Summary of a cloud instance, returned by GET /instances. */
 interface InstanceSummary {
     id: string;
@@ -143,14 +182,25 @@ declare class Client {
     /** 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[]>;
+    values(filter?: Filter, signal?: AbortSignal): Promise<DeviceValues[]>;
     /**
      * Open an ephemeral SSE stream with optional filtering.
      * No session, no replay, no ACK.
      */
     subscribe(filter?: Filter, signal?: AbortSignal): Promise<AsyncIterable<Event>>;
+    /** Fetch the last-seen decoded values for each (device, PGN) pair. */
+    decodedValues(filter?: Filter, signal?: AbortSignal): Promise<DecodedDeviceValues[]>;
     /** Transmit a CAN frame through the server. */
     send(params: SendParams, signal?: AbortSignal): Promise<void>;
+    /**
+     * Send an ISO Request (PGN 59904) and wait for the response frame.
+     * Returns the response frame, or throws HttpError with status 504 on timeout.
+     */
+    query(params: QueryParams, signal?: AbortSignal): Promise<Frame>;
+    /** Check server health. */
+    health(signal?: AbortSignal): Promise<HealthStatus>;
+    /** Fetch boat-side replication status (only available when replication is configured). */
+    replicationStatus(signal?: AbortSignal): Promise<ReplicationStatus>;
     /** Create or reconnect a buffered session on the server. */
     createSession(config: SessionConfig, signal?: AbortSignal): Promise<Session>;
 }
@@ -191,4 +241,4 @@ declare class HttpError extends LplexError {
     constructor(method: string, path: string, status: number, body: string);
 }
 
-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 };
+export { Client, type ClientOptions, CloudClient, type CloudClientOptions, type DecodedDeviceValues, type DecodedPGNValue, type Device, type DeviceValues, type Event, type Filter, type Frame, type HealthStatus, HttpError, type InstanceStatus, type InstanceSummary, LplexError, type PGNValue, type QueryParams, type ReplicationEvent, type ReplicationEventType, type ReplicationStatus, type SendParams, type SeqRange, Session, type SessionConfig, type SessionInfo };

package/dist/index.js

@@ -141,8 +141,10 @@ var Client = class {
     return resp.json();
   }
   /** Fetch the last-seen value for each (device, PGN) pair. */
-  async values(signal) {
-    const url = `${this.#baseURL}/values`;
+  async values(filter, signal) {
+    let url = `${this.#baseURL}/values`;
+    const qs = filterToQueryString(filter);
+    if (qs) url += `?${qs}`;
     const resp = await this.#fetch(url, { signal });
     if (!resp.ok) {
       const body = await resp.text();
@@ -171,6 +173,18 @@ var Client = class {
     }
     return parseSSE(resp.body);
   }
+  /** Fetch the last-seen decoded values for each (device, PGN) pair. */
+  async decodedValues(filter, signal) {
+    let url = `${this.#baseURL}/values/decoded`;
+    const qs = filterToQueryString(filter);
+    if (qs) url += `?${qs}`;
+    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();
+  }
   /** Transmit a CAN frame through the server. */
   async send(params, signal) {
     const url = `${this.#baseURL}/send`;
@@ -185,6 +199,44 @@ var Client = class {
       throw new HttpError("POST", url, resp.status, body);
     }
   }
+  /**
+   * Send an ISO Request (PGN 59904) and wait for the response frame.
+   * Returns the response frame, or throws HttpError with status 504 on timeout.
+   */
+  async query(params, signal) {
+    const url = `${this.#baseURL}/query`;
+    const resp = await this.#fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(params),
+      signal
+    });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("POST", url, resp.status, body);
+    }
+    return resp.json();
+  }
+  /** Check server health. */
+  async health(signal) {
+    const url = `${this.#baseURL}/healthz`;
+    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 boat-side replication status (only available when replication is configured). */
+  async replicationStatus(signal) {
+    const url = `${this.#baseURL}/replication/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();
+  }
   /** Create or reconnect a buffered session on the server. */
   async createSession(config, signal) {
     const url = `${this.#baseURL}/clients/${config.clientId}`;
@@ -209,23 +261,28 @@ var Client = class {
   }
 };
 function filterIsEmpty(f) {
-  return !f.pgn?.length && !f.manufacturer?.length && !f.instance?.length && !f.name?.length;
+  return !f.pgn?.length && !f.exclude_pgn?.length && !f.manufacturer?.length && !f.instance?.length && !f.name?.length && !f.exclude_name?.length;
 }
 function filterToQueryString(f) {
   if (!f || filterIsEmpty(f)) return "";
   const params = new URLSearchParams();
   for (const p of f.pgn ?? []) params.append("pgn", p.toString());
+  for (const p of f.exclude_pgn ?? [])
+    params.append("exclude_pgn", p.toString());
   for (const m of f.manufacturer ?? []) params.append("manufacturer", m);
   for (const i of f.instance ?? []) params.append("instance", i.toString());
   for (const n of f.name ?? []) params.append("name", n);
+  for (const n of f.exclude_name ?? []) params.append("exclude_name", n);
   return params.toString();
 }
 function filterToJSON(f) {
   const m = {};
   if (f.pgn?.length) m.pgn = f.pgn;
+  if (f.exclude_pgn?.length) m.exclude_pgn = f.exclude_pgn;
   if (f.manufacturer?.length) m.manufacturer = f.manufacturer;
   if (f.instance?.length) m.instance = f.instance;
   if (f.name?.length) m.name = f.name;
+  if (f.exclude_name?.length) m.exclude_name = f.exclude_name;
   return m;
 }
 

package/package.json

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