@auxilium/datalynk-client 1.4.0 → 1.4.1

package/dist/gps.d.ts

@@ -41,6 +41,10 @@ export type GpsOptions = false | {
     maxStaleMs?: number;
     /** Restart watchPosition if no fresh fix arrives. Default is 60000 */
     watchdogMs?: number;
+    /** Wait for socket-server ack on manual send(). Default is false */
+    waitForAck?: boolean;
+    /** Ack wait timeout when waitForAck is true. Default is 15000 */
+    ackTimeoutMs?: number;
 };
 export type GpsPositionPayload = {
     lat: number;
@@ -68,9 +72,32 @@ export type GpsListenOptions = {
     trailLimit?: number;
 };
 export type GpsListener = (event: any) => any;
+/** Server response body inside `{ gps: ... }` */
+export type GpsAck = {
+    ok: boolean;
+    seq?: number | null;
+    error?: string;
+    stage?: string;
+    slice?: number | string;
+    field?: string;
+    trackingId?: string;
+    liveKey?: string;
+    dirtyKey?: string;
+    activeKey?: string;
+    trailKey?: string;
+    sessionId?: string | null;
+    deviceId?: string | null;
+    pending?: boolean;
+};
+export type GpsSendOptions = {
+    /** When true, wait for matching socket-server ack (matched by seq). Default false */
+    waitForAck?: boolean;
+};
 /** Browser/manual GPS sender backed by socket-server Redis GPS storage */
 export declare class Gps {
     private readonly api;
+    private static readonly GPS_ACK_TIMEOUT_MS;
+    private ackResolvers;
     private deviceId;
     private heartbeat?;
     private lastFixAt;
@@ -93,12 +120,17 @@ export declare class Gps {
     start(): void;
     /** Stop sharing GPS and close the dedicated GPS socket */
     stop(): void;
-    /** Send a raw GPS message. Useful when an app already has its own GPS engine */
-    send(position: GpsManualPositionPayload, extra?: any): void;
+    /**
+     * Send a position from an app-owned GPS engine.
+     * By default returns after the message is queued/sent; set `waitForAck` to await server confirmation.
+     */
+    send(position: GpsManualPositionPayload, extra?: any, options?: GpsSendOptions): Promise<GpsAck>;
     /** Listen to GPS updates for the configured slice/field */
     listen(callback: GpsListener, options?: GpsListenOptions): Unsubscribe;
     private bindResumeEvents;
+    private clearAckResolvers;
     private connectSocket;
+    private onSocketMessage;
     private createId;
     private flushPendingPayloads;
     private getClientDetails;

package/dist/gps.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gps.d.ts","sourceRoot":"","sources":["../src/gps.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gps.d.ts","sourceRoot":"","sources":["../src/gps.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -3774,7 +3774,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       } });
     }
   }
-  const version = "1.4.0";
+  const version = "1.4.1";
   class WebRtc {
     constructor(api) {
       __publicField(this, "ice");
@@ -3895,8 +3895,9 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       return session;
     }
   }
-  class Gps {
+  const _Gps = class _Gps {
     constructor(api, options) {
+      __publicField(this, "ackResolvers", /* @__PURE__ */ new Map());
       __publicField(this, "deviceId");
       __publicField(this, "heartbeat");
       __publicField(this, "lastFixAt", 0);
@@ -3914,6 +3915,15 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       __publicField(this, "watchId");
       __publicField(this, "watchStartedAt", 0);
       __publicField(this, "options");
+      __publicField(this, "onSocketMessage", (event) => {
+        const ack = event == null ? void 0 : event.gps;
+        if (!ack || ack.seq == null) return;
+        const pending = this.ackResolvers.get(Number(ack.seq));
+        if (!pending) return;
+        clearTimeout(pending.timeout);
+        this.ackResolvers.delete(Number(ack.seq));
+        pending.resolve(ack);
+      });
       __publicField(this, "onPosition", (position) => {
         if (!this.options) return;
         if (!this.isFresh(position)) return;
@@ -3969,18 +3979,23 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       this.unsubs.forEach((unsub) => unsub());
       this.unsubs = [];
       this.pendingPayloads = [];
+      this.clearAckResolvers("GPS stopped");
       (_a = this.socket) == null ? void 0 : _a.close();
       this.socket = void 0;
     }
-    /** Send a raw GPS message. Useful when an app already has its own GPS engine */
-    send(position, extra = {}) {
+    /**
+     * Send a position from an app-owned GPS engine.
+     * By default returns after the message is queued/sent; set `waitForAck` to await server confirmation.
+     */
+    send(position, extra = {}, options = {}) {
       if (!this.options) throw new Error("Datalynk GPS is not configured");
       if (!this.api.token) throw new Error("Datalynk GPS cannot send before login");
       this.connectSocket();
-      this.sendPayload({
+      const waitForAck = options.waitForAck ?? this.options.waitForAck ?? false;
+      return this.sendPayload({
         ...extra,
         position: this.normalizePosition(position)
-      });
+      }, waitForAck);
     }
     /** Listen to GPS updates for the configured slice/field */
     listen(callback, options = {}) {
@@ -4020,12 +4035,18 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         document.removeEventListener("visibilitychange", restart);
       });
     }
+    clearAckResolvers(reason) {
+      this.ackResolvers.forEach(({ timeout, resolve }) => {
+        clearTimeout(timeout);
+        resolve({ ok: false, error: reason });
+      });
+      this.ackResolvers.clear();
+    }
     connectSocket() {
       if (!this.options || this.socket) return;
       if (!this.api.token) throw new Error("Datalynk GPS socket cannot connect before login");
       this.socket = new Socket(this.api, { url: this.options.socketUrl });
-      this.unsubs.push(this.socket.addListener(() => {
-      }, () => this.flushPendingPayloads()));
+      this.unsubs.push(this.socket.addListener(this.onSocketMessage, () => this.flushPendingPayloads()));
     }
     createId() {
       if (typeof crypto != "undefined" && crypto.randomUUID) return crypto.randomUUID();
@@ -4142,10 +4163,11 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       this.watchId = void 0;
       this.startWatch();
     }
-    sendPayload(payload) {
+    sendPayload(payload, waitForAck = false) {
       var _a, _b;
-      if (!this.options) return;
+      if (!this.options) return Promise.resolve({ ok: false, error: "Datalynk GPS is not configured" });
       this.connectSocket();
+      const seq = ++this.seq;
       const message = {
         gps: {
           slice: this.options.slice,
@@ -4154,7 +4176,7 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
           trackerId: this.trackerId,
           sessionId: this.sessionId,
           deviceId: this.deviceId,
-          seq: ++this.seq,
+          seq,
           client: this.getClientDetails(),
           sentAt: (/* @__PURE__ */ new Date()).toISOString(),
           gpsTimestamp: ((_a = payload.position) == null ? void 0 : _a.timestamp) || null,
@@ -4163,12 +4185,24 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
           ...payload
         }
       };
+      let ackPromise;
+      if (waitForAck) {
+        const timeoutMs = this.options.ackTimeoutMs ?? _Gps.GPS_ACK_TIMEOUT_MS;
+        ackPromise = new Promise((resolve) => {
+          const timeout = setTimeout(() => {
+            this.ackResolvers.delete(seq);
+            resolve({ ok: false, error: "GPS ack timeout", seq });
+          }, timeoutMs);
+          this.ackResolvers.set(seq, { resolve, timeout });
+        });
+      }
       if (!((_b = this.socket) == null ? void 0 : _b.open)) {
         this.pendingPayloads.push(message);
         this.pendingPayloads = this.pendingPayloads.slice(-25);
-        return;
+        return ackPromise ?? Promise.resolve({ ok: true, seq, pending: true });
       }
       this.socket.send(message);
+      return ackPromise ?? Promise.resolve({ ok: true, seq, pending: false });
     }
     sendPosition(position, force) {
       this.sendPayload({
@@ -4239,7 +4273,11 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
         return;
       }
       const sub = this.api.token$.subscribe((token) => {
-        if (!token || this.started || !this.options || this.options.autoStart === false) return;
+        if (!token) {
+          if (this.started) this.stop();
+          return;
+        }
+        if (this.started || !this.options || this.options.autoStart === false) return;
         try {
           this.start();
         } catch (error) {
@@ -4248,7 +4286,9 @@ var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "sy
       });
       this.unsubs.push(() => sub.unsubscribe());
     }
-  }
+  };
+  __publicField(_Gps, "GPS_ACK_TIMEOUT_MS", 15e3);
+  let Gps = _Gps;
   const _Api = class _Api {
     /**
      * Connect to Datalynk & send requests

package/dist/index.mjs

@@ -3770,7 +3770,7 @@ class Superuser {
     } });
   }
 }
-const version = "1.4.0";
+const version = "1.4.1";
 class WebRtc {
   constructor(api) {
     __publicField(this, "ice");
@@ -3891,8 +3891,9 @@ class WebRtc {
     return session;
   }
 }
-class Gps {
+const _Gps = class _Gps {
   constructor(api, options) {
+    __publicField(this, "ackResolvers", /* @__PURE__ */ new Map());
     __publicField(this, "deviceId");
     __publicField(this, "heartbeat");
     __publicField(this, "lastFixAt", 0);
@@ -3910,6 +3911,15 @@ class Gps {
     __publicField(this, "watchId");
     __publicField(this, "watchStartedAt", 0);
     __publicField(this, "options");
+    __publicField(this, "onSocketMessage", (event) => {
+      const ack = event == null ? void 0 : event.gps;
+      if (!ack || ack.seq == null) return;
+      const pending = this.ackResolvers.get(Number(ack.seq));
+      if (!pending) return;
+      clearTimeout(pending.timeout);
+      this.ackResolvers.delete(Number(ack.seq));
+      pending.resolve(ack);
+    });
     __publicField(this, "onPosition", (position) => {
       if (!this.options) return;
       if (!this.isFresh(position)) return;
@@ -3965,18 +3975,23 @@ class Gps {
     this.unsubs.forEach((unsub) => unsub());
     this.unsubs = [];
     this.pendingPayloads = [];
+    this.clearAckResolvers("GPS stopped");
     (_a = this.socket) == null ? void 0 : _a.close();
     this.socket = void 0;
   }
-  /** Send a raw GPS message. Useful when an app already has its own GPS engine */
-  send(position, extra = {}) {
+  /**
+   * Send a position from an app-owned GPS engine.
+   * By default returns after the message is queued/sent; set `waitForAck` to await server confirmation.
+   */
+  send(position, extra = {}, options = {}) {
     if (!this.options) throw new Error("Datalynk GPS is not configured");
     if (!this.api.token) throw new Error("Datalynk GPS cannot send before login");
     this.connectSocket();
-    this.sendPayload({
+    const waitForAck = options.waitForAck ?? this.options.waitForAck ?? false;
+    return this.sendPayload({
       ...extra,
       position: this.normalizePosition(position)
-    });
+    }, waitForAck);
   }
   /** Listen to GPS updates for the configured slice/field */
   listen(callback, options = {}) {
@@ -4016,12 +4031,18 @@ class Gps {
       document.removeEventListener("visibilitychange", restart);
     });
   }
+  clearAckResolvers(reason) {
+    this.ackResolvers.forEach(({ timeout, resolve }) => {
+      clearTimeout(timeout);
+      resolve({ ok: false, error: reason });
+    });
+    this.ackResolvers.clear();
+  }
   connectSocket() {
     if (!this.options || this.socket) return;
     if (!this.api.token) throw new Error("Datalynk GPS socket cannot connect before login");
     this.socket = new Socket(this.api, { url: this.options.socketUrl });
-    this.unsubs.push(this.socket.addListener(() => {
-    }, () => this.flushPendingPayloads()));
+    this.unsubs.push(this.socket.addListener(this.onSocketMessage, () => this.flushPendingPayloads()));
   }
   createId() {
     if (typeof crypto != "undefined" && crypto.randomUUID) return crypto.randomUUID();
@@ -4138,10 +4159,11 @@ class Gps {
     this.watchId = void 0;
     this.startWatch();
   }
-  sendPayload(payload) {
+  sendPayload(payload, waitForAck = false) {
     var _a, _b;
-    if (!this.options) return;
+    if (!this.options) return Promise.resolve({ ok: false, error: "Datalynk GPS is not configured" });
     this.connectSocket();
+    const seq = ++this.seq;
     const message = {
       gps: {
         slice: this.options.slice,
@@ -4150,7 +4172,7 @@ class Gps {
         trackerId: this.trackerId,
         sessionId: this.sessionId,
         deviceId: this.deviceId,
-        seq: ++this.seq,
+        seq,
         client: this.getClientDetails(),
         sentAt: (/* @__PURE__ */ new Date()).toISOString(),
         gpsTimestamp: ((_a = payload.position) == null ? void 0 : _a.timestamp) || null,
@@ -4159,12 +4181,24 @@ class Gps {
         ...payload
       }
     };
+    let ackPromise;
+    if (waitForAck) {
+      const timeoutMs = this.options.ackTimeoutMs ?? _Gps.GPS_ACK_TIMEOUT_MS;
+      ackPromise = new Promise((resolve) => {
+        const timeout = setTimeout(() => {
+          this.ackResolvers.delete(seq);
+          resolve({ ok: false, error: "GPS ack timeout", seq });
+        }, timeoutMs);
+        this.ackResolvers.set(seq, { resolve, timeout });
+      });
+    }
     if (!((_b = this.socket) == null ? void 0 : _b.open)) {
       this.pendingPayloads.push(message);
       this.pendingPayloads = this.pendingPayloads.slice(-25);
-      return;
+      return ackPromise ?? Promise.resolve({ ok: true, seq, pending: true });
     }
     this.socket.send(message);
+    return ackPromise ?? Promise.resolve({ ok: true, seq, pending: false });
   }
   sendPosition(position, force) {
     this.sendPayload({
@@ -4235,7 +4269,11 @@ class Gps {
       return;
     }
     const sub = this.api.token$.subscribe((token) => {
-      if (!token || this.started || !this.options || this.options.autoStart === false) return;
+      if (!token) {
+        if (this.started) this.stop();
+        return;
+      }
+      if (this.started || !this.options || this.options.autoStart === false) return;
       try {
         this.start();
       } catch (error) {
@@ -4244,7 +4282,9 @@ class Gps {
     });
     this.unsubs.push(() => sub.unsubscribe());
   }
-}
+};
+__publicField(_Gps, "GPS_ACK_TIMEOUT_MS", 15e3);
+let Gps = _Gps;
 const _Api = class _Api {
   /**
    * Connect to Datalynk & send requests

package/package.json

@@ -2,7 +2,7 @@
 	"name": "@auxilium/datalynk-client",
 	"description": "Datalynk client library",
 	"repository": "https://gitlab.auxiliumgroup.com/auxilium/datalynk/datalynk-client",
-	"version": "1.4.0",
+	"version": "1.4.1",
 	"author": "Zak Timson <zaktimson@gmail.com>",
 	"private": false,
 	"main": "./dist/index.cjs",