@sixfathoms/lplex 0.0.0

package/dist/index.cjs

@@ -0,0 +1,256 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Client: () => Client,
+  HttpError: () => HttpError,
+  LplexError: () => LplexError,
+  Session: () => Session
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var LplexError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LplexError";
+  }
+};
+var HttpError = class extends LplexError {
+  status;
+  body;
+  constructor(method, path, status, body) {
+    super(`${method} ${path} returned ${status}: ${body}`);
+    this.name = "HttpError";
+    this.status = status;
+    this.body = body;
+  }
+};
+
+// src/sse.ts
+async function* parseSSE(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      for (let newlineIdx = buffer.indexOf("\n"); newlineIdx !== -1; newlineIdx = buffer.indexOf("\n")) {
+        const line = buffer.slice(0, newlineIdx);
+        buffer = buffer.slice(newlineIdx + 1);
+        if (!line.startsWith("data: ")) continue;
+        const json = line.slice(6);
+        let parsed;
+        try {
+          parsed = JSON.parse(json);
+        } catch {
+          continue;
+        }
+        if (typeof parsed !== "object" || parsed === null) continue;
+        const event = classify(parsed);
+        if (event) yield event;
+      }
+    }
+    buffer += decoder.decode();
+    if (buffer.startsWith("data: ")) {
+      const json = buffer.slice(6);
+      try {
+        const parsed = JSON.parse(json);
+        if (typeof parsed === "object" && parsed !== null) {
+          const event = classify(parsed);
+          if (event) yield event;
+        }
+      } catch {
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+function classify(obj) {
+  if ("type" in obj && obj.type === "device") {
+    return { type: "device", device: obj };
+  }
+  if ("seq" in obj) {
+    return { type: "frame", frame: obj };
+  }
+  return null;
+}
+
+// src/session.ts
+var Session = class {
+  #baseURL;
+  #fetch;
+  #info;
+  #lastAckedSeq = 0;
+  /** @internal Created by Client.createSession, not for direct use. */
+  constructor(baseURL, fetchFn, info) {
+    this.#baseURL = baseURL;
+    this.#fetch = fetchFn;
+    this.#info = info;
+  }
+  get info() {
+    return this.#info;
+  }
+  get lastAckedSeq() {
+    return this.#lastAckedSeq;
+  }
+  /**
+   * Open the SSE stream for this session. Replays buffered frames
+   * from the cursor, then streams live.
+   */
+  async subscribe(signal) {
+    const url = `${this.#baseURL}/clients/${this.#info.client_id}/events`;
+    const resp = await this.#fetch(url, {
+      headers: { Accept: "text/event-stream" },
+      signal
+    });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("GET", url, resp.status, body);
+    }
+    if (!resp.body) {
+      throw new HttpError("GET", url, resp.status, "no response body");
+    }
+    return parseSSE(resp.body);
+  }
+  /** Advance the cursor for this session to the given sequence number. */
+  async ack(seq, signal) {
+    const url = `${this.#baseURL}/clients/${this.#info.client_id}/ack`;
+    const resp = await this.#fetch(url, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ seq }),
+      signal
+    });
+    if (resp.status !== 204) {
+      const body = await resp.text();
+      throw new HttpError("PUT", url, resp.status, body);
+    }
+    this.#lastAckedSeq = seq;
+  }
+};
+
+// src/client.ts
+var Client = class {
+  #baseURL;
+  #fetch;
+  constructor(baseURL, options) {
+    this.#baseURL = baseURL.replace(/\/+$/, "");
+    this.#fetch = options?.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  /** Fetch a snapshot of all NMEA 2000 devices discovered by the server. */
+  async devices(signal) {
+    const url = `${this.#baseURL}/devices`;
+    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.
+   */
+  async subscribe(filter, signal) {
+    let url = `${this.#baseURL}/events`;
+    const qs = filterToQueryString(filter);
+    if (qs) url += `?${qs}`;
+    const resp = await this.#fetch(url, {
+      headers: { Accept: "text/event-stream" },
+      signal
+    });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("GET", url, resp.status, body);
+    }
+    if (!resp.body) {
+      throw new HttpError("GET", url, resp.status, "no response body");
+    }
+    return parseSSE(resp.body);
+  }
+  /** Transmit a CAN frame through the server. */
+  async send(params, signal) {
+    const url = `${this.#baseURL}/send`;
+    const resp = await this.#fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(params),
+      signal
+    });
+    if (resp.status !== 202) {
+      const body = await resp.text();
+      throw new HttpError("POST", url, resp.status, body);
+    }
+  }
+  /** Create or reconnect a buffered session on the server. */
+  async createSession(config, signal) {
+    const url = `${this.#baseURL}/clients/${config.clientId}`;
+    const putBody = {
+      buffer_timeout: config.bufferTimeout
+    };
+    if (config.filter && !filterIsEmpty(config.filter)) {
+      putBody.filter = filterToJSON(config.filter);
+    }
+    const resp = await this.#fetch(url, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(putBody),
+      signal
+    });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("PUT", url, resp.status, body);
+    }
+    const info = await resp.json();
+    return new Session(this.#baseURL, this.#fetch, info);
+  }
+};
+function filterIsEmpty(f) {
+  return !f.pgn?.length && !f.manufacturer?.length && !f.instance?.length && !f.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 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);
+  return params.toString();
+}
+function filterToJSON(f) {
+  const m = {};
+  if (f.pgn?.length) m.pgn = f.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;
+  return m;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Client,
+  HttpError,
+  LplexError,
+  Session
+});

package/dist/index.d.cts

@@ -0,0 +1,116 @@
+/** A single CAN frame received from the lplex server. */
+interface Frame {
+    seq: number;
+    ts: string;
+    prio: number;
+    pgn: number;
+    src: number;
+    dst: number;
+    data: string;
+}
+/** An NMEA 2000 device discovered on the bus. */
+interface Device {
+    src: number;
+    name: string;
+    manufacturer: string;
+    manufacturer_code: number;
+    device_class: number;
+    device_function: number;
+    device_instance: number;
+    unique_number: number;
+    model_id: string;
+    software_version: string;
+    model_version: string;
+    model_serial: string;
+    product_code: number;
+    first_seen: string;
+    last_seen: string;
+    packet_count: number;
+    byte_count: number;
+}
+/** Discriminated union for SSE events. */
+type Event = {
+    type: "frame";
+    frame: Frame;
+} | {
+    type: "device";
+    device: Device;
+};
+/**
+ * Filter for CAN frames.
+ * Categories are AND'd, values within a category are OR'd.
+ */
+interface Filter {
+    pgn?: number[];
+    manufacturer?: string[];
+    instance?: number[];
+    name?: string[];
+}
+/** Configuration for creating a buffered session. */
+interface SessionConfig {
+    clientId: string;
+    bufferTimeout: string;
+    filter?: Filter;
+}
+/** Server response from creating or reconnecting a session. */
+interface SessionInfo {
+    client_id: string;
+    seq: number;
+    cursor: number;
+    devices: Device[];
+}
+/** Parameters for transmitting a CAN frame. */
+interface SendParams {
+    pgn: number;
+    src: number;
+    dst: number;
+    prio: number;
+    data: string;
+}
+
+type FetchFn$1 = typeof globalThis.fetch;
+declare class Session {
+    #private;
+    /** @internal Created by Client.createSession, not for direct use. */
+    constructor(baseURL: string, fetchFn: FetchFn$1, info: SessionInfo);
+    get info(): SessionInfo;
+    get lastAckedSeq(): number;
+    /**
+     * Open the SSE stream for this session. Replays buffered frames
+     * from the cursor, then streams live.
+     */
+    subscribe(signal?: AbortSignal): Promise<AsyncIterable<Event>>;
+    /** Advance the cursor for this session to the given sequence number. */
+    ack(seq: number, signal?: AbortSignal): Promise<void>;
+}
+
+type FetchFn = typeof globalThis.fetch;
+interface ClientOptions {
+    fetch?: FetchFn;
+}
+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[]>;
+    /**
+     * Open an ephemeral SSE stream with optional filtering.
+     * No session, no replay, no ACK.
+     */
+    subscribe(filter?: Filter, signal?: AbortSignal): Promise<AsyncIterable<Event>>;
+    /** Transmit a CAN frame through the server. */
+    send(params: SendParams, signal?: AbortSignal): Promise<void>;
+    /** Create or reconnect a buffered session on the server. */
+    createSession(config: SessionConfig, signal?: AbortSignal): Promise<Session>;
+}
+
+declare class LplexError extends Error {
+    constructor(message: string);
+}
+declare class HttpError extends LplexError {
+    readonly status: number;
+    readonly body: string;
+    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 };

package/dist/index.d.ts

@@ -0,0 +1,116 @@
+/** A single CAN frame received from the lplex server. */
+interface Frame {
+    seq: number;
+    ts: string;
+    prio: number;
+    pgn: number;
+    src: number;
+    dst: number;
+    data: string;
+}
+/** An NMEA 2000 device discovered on the bus. */
+interface Device {
+    src: number;
+    name: string;
+    manufacturer: string;
+    manufacturer_code: number;
+    device_class: number;
+    device_function: number;
+    device_instance: number;
+    unique_number: number;
+    model_id: string;
+    software_version: string;
+    model_version: string;
+    model_serial: string;
+    product_code: number;
+    first_seen: string;
+    last_seen: string;
+    packet_count: number;
+    byte_count: number;
+}
+/** Discriminated union for SSE events. */
+type Event = {
+    type: "frame";
+    frame: Frame;
+} | {
+    type: "device";
+    device: Device;
+};
+/**
+ * Filter for CAN frames.
+ * Categories are AND'd, values within a category are OR'd.
+ */
+interface Filter {
+    pgn?: number[];
+    manufacturer?: string[];
+    instance?: number[];
+    name?: string[];
+}
+/** Configuration for creating a buffered session. */
+interface SessionConfig {
+    clientId: string;
+    bufferTimeout: string;
+    filter?: Filter;
+}
+/** Server response from creating or reconnecting a session. */
+interface SessionInfo {
+    client_id: string;
+    seq: number;
+    cursor: number;
+    devices: Device[];
+}
+/** Parameters for transmitting a CAN frame. */
+interface SendParams {
+    pgn: number;
+    src: number;
+    dst: number;
+    prio: number;
+    data: string;
+}
+
+type FetchFn$1 = typeof globalThis.fetch;
+declare class Session {
+    #private;
+    /** @internal Created by Client.createSession, not for direct use. */
+    constructor(baseURL: string, fetchFn: FetchFn$1, info: SessionInfo);
+    get info(): SessionInfo;
+    get lastAckedSeq(): number;
+    /**
+     * Open the SSE stream for this session. Replays buffered frames
+     * from the cursor, then streams live.
+     */
+    subscribe(signal?: AbortSignal): Promise<AsyncIterable<Event>>;
+    /** Advance the cursor for this session to the given sequence number. */
+    ack(seq: number, signal?: AbortSignal): Promise<void>;
+}
+
+type FetchFn = typeof globalThis.fetch;
+interface ClientOptions {
+    fetch?: FetchFn;
+}
+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[]>;
+    /**
+     * Open an ephemeral SSE stream with optional filtering.
+     * No session, no replay, no ACK.
+     */
+    subscribe(filter?: Filter, signal?: AbortSignal): Promise<AsyncIterable<Event>>;
+    /** Transmit a CAN frame through the server. */
+    send(params: SendParams, signal?: AbortSignal): Promise<void>;
+    /** Create or reconnect a buffered session on the server. */
+    createSession(config: SessionConfig, signal?: AbortSignal): Promise<Session>;
+}
+
+declare class LplexError extends Error {
+    constructor(message: string);
+}
+declare class HttpError extends LplexError {
+    readonly status: number;
+    readonly body: string;
+    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 };

package/dist/index.js

@@ -0,0 +1,226 @@
+// src/errors.ts
+var LplexError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "LplexError";
+  }
+};
+var HttpError = class extends LplexError {
+  status;
+  body;
+  constructor(method, path, status, body) {
+    super(`${method} ${path} returned ${status}: ${body}`);
+    this.name = "HttpError";
+    this.status = status;
+    this.body = body;
+  }
+};
+
+// src/sse.ts
+async function* parseSSE(body) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      for (let newlineIdx = buffer.indexOf("\n"); newlineIdx !== -1; newlineIdx = buffer.indexOf("\n")) {
+        const line = buffer.slice(0, newlineIdx);
+        buffer = buffer.slice(newlineIdx + 1);
+        if (!line.startsWith("data: ")) continue;
+        const json = line.slice(6);
+        let parsed;
+        try {
+          parsed = JSON.parse(json);
+        } catch {
+          continue;
+        }
+        if (typeof parsed !== "object" || parsed === null) continue;
+        const event = classify(parsed);
+        if (event) yield event;
+      }
+    }
+    buffer += decoder.decode();
+    if (buffer.startsWith("data: ")) {
+      const json = buffer.slice(6);
+      try {
+        const parsed = JSON.parse(json);
+        if (typeof parsed === "object" && parsed !== null) {
+          const event = classify(parsed);
+          if (event) yield event;
+        }
+      } catch {
+      }
+    }
+  } finally {
+    reader.releaseLock();
+  }
+}
+function classify(obj) {
+  if ("type" in obj && obj.type === "device") {
+    return { type: "device", device: obj };
+  }
+  if ("seq" in obj) {
+    return { type: "frame", frame: obj };
+  }
+  return null;
+}
+
+// src/session.ts
+var Session = class {
+  #baseURL;
+  #fetch;
+  #info;
+  #lastAckedSeq = 0;
+  /** @internal Created by Client.createSession, not for direct use. */
+  constructor(baseURL, fetchFn, info) {
+    this.#baseURL = baseURL;
+    this.#fetch = fetchFn;
+    this.#info = info;
+  }
+  get info() {
+    return this.#info;
+  }
+  get lastAckedSeq() {
+    return this.#lastAckedSeq;
+  }
+  /**
+   * Open the SSE stream for this session. Replays buffered frames
+   * from the cursor, then streams live.
+   */
+  async subscribe(signal) {
+    const url = `${this.#baseURL}/clients/${this.#info.client_id}/events`;
+    const resp = await this.#fetch(url, {
+      headers: { Accept: "text/event-stream" },
+      signal
+    });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("GET", url, resp.status, body);
+    }
+    if (!resp.body) {
+      throw new HttpError("GET", url, resp.status, "no response body");
+    }
+    return parseSSE(resp.body);
+  }
+  /** Advance the cursor for this session to the given sequence number. */
+  async ack(seq, signal) {
+    const url = `${this.#baseURL}/clients/${this.#info.client_id}/ack`;
+    const resp = await this.#fetch(url, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ seq }),
+      signal
+    });
+    if (resp.status !== 204) {
+      const body = await resp.text();
+      throw new HttpError("PUT", url, resp.status, body);
+    }
+    this.#lastAckedSeq = seq;
+  }
+};
+
+// src/client.ts
+var Client = class {
+  #baseURL;
+  #fetch;
+  constructor(baseURL, options) {
+    this.#baseURL = baseURL.replace(/\/+$/, "");
+    this.#fetch = options?.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+  /** Fetch a snapshot of all NMEA 2000 devices discovered by the server. */
+  async devices(signal) {
+    const url = `${this.#baseURL}/devices`;
+    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.
+   */
+  async subscribe(filter, signal) {
+    let url = `${this.#baseURL}/events`;
+    const qs = filterToQueryString(filter);
+    if (qs) url += `?${qs}`;
+    const resp = await this.#fetch(url, {
+      headers: { Accept: "text/event-stream" },
+      signal
+    });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("GET", url, resp.status, body);
+    }
+    if (!resp.body) {
+      throw new HttpError("GET", url, resp.status, "no response body");
+    }
+    return parseSSE(resp.body);
+  }
+  /** Transmit a CAN frame through the server. */
+  async send(params, signal) {
+    const url = `${this.#baseURL}/send`;
+    const resp = await this.#fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(params),
+      signal
+    });
+    if (resp.status !== 202) {
+      const body = await resp.text();
+      throw new HttpError("POST", url, resp.status, body);
+    }
+  }
+  /** Create or reconnect a buffered session on the server. */
+  async createSession(config, signal) {
+    const url = `${this.#baseURL}/clients/${config.clientId}`;
+    const putBody = {
+      buffer_timeout: config.bufferTimeout
+    };
+    if (config.filter && !filterIsEmpty(config.filter)) {
+      putBody.filter = filterToJSON(config.filter);
+    }
+    const resp = await this.#fetch(url, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(putBody),
+      signal
+    });
+    if (!resp.ok) {
+      const body = await resp.text();
+      throw new HttpError("PUT", url, resp.status, body);
+    }
+    const info = await resp.json();
+    return new Session(this.#baseURL, this.#fetch, info);
+  }
+};
+function filterIsEmpty(f) {
+  return !f.pgn?.length && !f.manufacturer?.length && !f.instance?.length && !f.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 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);
+  return params.toString();
+}
+function filterToJSON(f) {
+  const m = {};
+  if (f.pgn?.length) m.pgn = f.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;
+  return m;
+}
+export {
+  Client,
+  HttpError,
+  LplexError,
+  Session
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@sixfathoms/lplex",
+  "version": "0.0.0",
+  "description": "TypeScript client for lplex CAN bus HTTP bridge",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "license": "MIT"
+}