@sovereignbase/station-client 0.0.0

package/dist/index.cjs

@@ -0,0 +1,346 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; } var _class;/*
+ * Copyright 2026 Sovereignbase
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+
+// src/StationClient/class.ts
+var _msgpack = require('@msgpack/msgpack');
+var StationClient = (_class = class {
+  __init() {this.eventTarget = new EventTarget()}
+  
+  
+  
+  __init2() {this.instanceId = self.crypto.randomUUID()}
+  __init3() {this.onlineHandler = () => {
+    void this.opportunisticConnect();
+  }}
+  __init4() {this.broadcastChannel = null}
+  __init5() {this.webSocket = null}
+  __init6() {this.isLeader = false}
+  __init7() {this.isClosed = false}
+  __init8() {this.isConnecting = false}
+  __init9() {this.outboundQueue = []}
+  __init10() {this.pendingTransacts = /* @__PURE__ */ new Map()}
+  __init11() {this.pendingTransactTargets = /* @__PURE__ */ new Map()}
+  /**
+   * Initializes a new {@link StationClient} instance.
+   *
+   * @param webSocketUrl The base station WebSocket URL. When omitted, the instance operates in local-only mode.
+   */
+  constructor(webSocketUrl = "") {;_class.prototype.__init.call(this);_class.prototype.__init2.call(this);_class.prototype.__init3.call(this);_class.prototype.__init4.call(this);_class.prototype.__init5.call(this);_class.prototype.__init6.call(this);_class.prototype.__init7.call(this);_class.prototype.__init8.call(this);_class.prototype.__init9.call(this);_class.prototype.__init10.call(this);_class.prototype.__init11.call(this);
+    this.webSocketUrl = webSocketUrl;
+    this.channelName = `origin-channel-lock::${this.webSocketUrl}`;
+    this.lockName = `origin-channel-lock::${this.webSocketUrl}`;
+    this.broadcastChannel = new BroadcastChannel(this.channelName);
+    this.broadcastChannel.onmessage = (event) => {
+      const envelope = event.data;
+      if (!envelope) return;
+      if (envelope.kind === "relay") {
+        this.eventTarget.dispatchEvent(
+          new CustomEvent("message", { detail: envelope.message })
+        );
+        if (!this.isLeader) return;
+        this.sendToStation(envelope.message);
+        return;
+      }
+      if (envelope.kind === "transact-response") {
+        if (envelope.target !== this.instanceId) return;
+        const pending = this.pendingTransacts.get(envelope.id);
+        if (!pending) return;
+        this.pendingTransacts.delete(envelope.id);
+        pending.cleanup();
+        pending.resolve(envelope.message);
+        return;
+      }
+      if (envelope.kind === "transact-abort") {
+        if (!this.isLeader) return;
+        const pendingTarget2 = this.pendingTransactTargets.get(envelope.id);
+        if (pendingTarget2) clearTimeout(pendingTarget2.timeoutId);
+        this.pendingTransactTargets.delete(envelope.id);
+        return;
+      }
+      if (!this.isLeader) return;
+      if (!this.webSocketUrl || self.navigator.onLine !== true || !this.webSocket || this.webSocket.readyState !== WebSocket.OPEN) {
+        _optionalChain([this, 'access', _ => _.broadcastChannel, 'optionalAccess', _2 => _2.postMessage, 'call', _3 => _3({
+          kind: "transact-response",
+          id: envelope.id,
+          target: envelope.source,
+          message: false
+        })]);
+        return;
+      }
+      const pendingTarget = this.pendingTransactTargets.get(envelope.id);
+      if (pendingTarget) clearTimeout(pendingTarget.timeoutId);
+      this.pendingTransactTargets.set(envelope.id, {
+        target: envelope.source,
+        timeoutId: setTimeout(() => {
+          this.pendingTransactTargets.delete(envelope.id);
+        }, _nullishCoalesce(envelope.ttlMs, () => ( 3e4)))
+      });
+      this.sendToStation([
+        "station-client-request",
+        envelope.id,
+        envelope.message
+      ]);
+    };
+    if (this.webSocketUrl && navigator.onLine) void this.opportunisticConnect();
+    if (this.webSocketUrl) {
+      self.addEventListener("online", this.onlineHandler);
+    }
+  }
+  /**main methods*/
+  /**
+   * Broadcasts a message to other same-origin contexts and opportunistically forwards it to the base station.
+   *
+   * @param message The message to broadcast.
+   */
+  relay(message) {
+    if (this.isClosed) return;
+    _optionalChain([this, 'access', _4 => _4.broadcastChannel, 'optionalAccess', _5 => _5.postMessage, 'call', _6 => _6({ kind: "relay", message })]);
+    this.sendToStation(message);
+  }
+  /**
+   * Sends a request to the base station and resolves with the corresponding response message.
+   *
+   * @param message The message to send.
+   * @param options Options that control cancellation and stale follower cleanup.
+   * @returns A promise that resolves with the response message, or `false` when the request cannot be issued.
+   */
+  transact(message, options = {}) {
+    if (this.isClosed) return Promise.resolve(false);
+    const id = self.crypto.randomUUID();
+    const { signal, ttlMs } = options;
+    return new Promise((resolve, reject) => {
+      const abortReason = () => _nullishCoalesce(_optionalChain([signal, 'optionalAccess', _7 => _7.reason]), () => ( new DOMException("The operation was aborted.", "AbortError")));
+      if (_optionalChain([signal, 'optionalAccess', _8 => _8.aborted])) {
+        reject(abortReason());
+        return;
+      }
+      if (!this.webSocketUrl || self.navigator.onLine !== true) {
+        resolve(false);
+        return;
+      }
+      if (this.isLeader && (!this.webSocket || this.webSocket.readyState !== WebSocket.OPEN)) {
+        resolve(false);
+        return;
+      }
+      const handleAbort = () => {
+        this.pendingTransacts.delete(id);
+        const pendingTarget = this.pendingTransactTargets.get(id);
+        if (pendingTarget) clearTimeout(pendingTarget.timeoutId);
+        this.pendingTransactTargets.delete(id);
+        _optionalChain([signal, 'optionalAccess', _9 => _9.removeEventListener, 'call', _10 => _10("abort", handleAbort)]);
+        if (!this.isLeader) {
+          _optionalChain([this, 'access', _11 => _11.broadcastChannel, 'optionalAccess', _12 => _12.postMessage, 'call', _13 => _13({ kind: "transact-abort", id })]);
+        }
+        reject(abortReason());
+      };
+      this.pendingTransacts.set(id, {
+        resolve,
+        reject,
+        cleanup: () => {
+          _optionalChain([signal, 'optionalAccess', _14 => _14.removeEventListener, 'call', _15 => _15("abort", handleAbort)]);
+        }
+      });
+      _optionalChain([signal, 'optionalAccess', _16 => _16.addEventListener, 'call', _17 => _17("abort", handleAbort, { once: true })]);
+      if (this.isLeader) {
+        this.sendToStation(["station-client-request", id, message]);
+        return;
+      }
+      _optionalChain([this, 'access', _18 => _18.broadcastChannel, 'optionalAccess', _19 => _19.postMessage, 'call', _20 => _20({
+        kind: "transact",
+        id,
+        source: this.instanceId,
+        ttlMs,
+        message
+      })]);
+    });
+  }
+  /**
+   * Closes the client and releases its local and remote resources.
+   */
+  close() {
+    const wasLeader = this.isLeader;
+    const broadcastChannel = this.broadcastChannel;
+    this.isClosed = true;
+    self.removeEventListener("online", this.onlineHandler);
+    if (!wasLeader) {
+      for (const id of this.pendingTransacts.keys()) {
+        try {
+          _optionalChain([broadcastChannel, 'optionalAccess', _21 => _21.postMessage, 'call', _22 => _22({ kind: "transact-abort", id })]);
+        } catch (e) {
+        }
+      }
+    }
+    try {
+      _optionalChain([broadcastChannel, 'optionalAccess', _23 => _23.close, 'call', _24 => _24()]);
+    } catch (e2) {
+    }
+    try {
+      _optionalChain([this, 'access', _25 => _25.webSocket, 'optionalAccess', _26 => _26.close, 'call', _27 => _27(1e3, "closed")]);
+    } catch (e3) {
+    }
+    this.broadcastChannel = null;
+    this.webSocket = null;
+    this.isLeader = false;
+    this.outboundQueue.length = 0;
+    for (const pending of this.pendingTransacts.values()) {
+      pending.cleanup();
+      pending.reject(new Error("Station client closed"));
+    }
+    this.pendingTransacts.clear();
+    for (const pendingTarget of this.pendingTransactTargets.values()) {
+      clearTimeout(pendingTarget.timeoutId);
+    }
+    this.pendingTransactTargets.clear();
+  }
+  /**listeners*/
+  /**
+   * Appends an event listener for events whose type attribute value is `type`.
+   *
+   * @param type The event type to listen for.
+   * @param listener The callback that receives the event.
+   * @param options An options object that specifies characteristics about the event listener.
+   */
+  addEventListener(type, listener, options) {
+    this.eventTarget.addEventListener(
+      type,
+      listener,
+      options
+    );
+  }
+  /**
+   * Removes an event listener previously registered with {@link addEventListener}.
+   *
+   * @param type The event type to remove.
+   * @param listener The callback to remove.
+   * @param options An options object that specifies characteristics about the event listener.
+   */
+  removeEventListener(type, listener, options) {
+    this.eventTarget.removeEventListener(
+      type,
+      listener,
+      options
+    );
+  }
+  /**helpers*/
+  sendToStation(message) {
+    if (!this.isLeader || !this.webSocketUrl) return;
+    if (!this.webSocket || this.webSocket.readyState !== WebSocket.OPEN) {
+      if (self.navigator.onLine) {
+        if (this.outboundQueue.length >= 64) this.outboundQueue.shift();
+        this.outboundQueue.push(message);
+      }
+      return;
+    }
+    try {
+      this.webSocket.send(_msgpack.encode.call(void 0, message));
+    } catch (e4) {
+    }
+  }
+  flushOutboundQueue() {
+    if (!this.webSocket || this.webSocket.readyState !== WebSocket.OPEN) return;
+    while (this.outboundQueue.length > 0) {
+      const message = this.outboundQueue.shift();
+      if (!message) continue;
+      try {
+        this.webSocket.send(_msgpack.encode.call(void 0, message));
+      } catch (e5) {
+        this.outboundQueue.unshift(message);
+        return;
+      }
+    }
+  }
+  async opportunisticConnect() {
+    if (this.isClosed || this.isConnecting || !this.webSocketUrl) return;
+    if (!self.navigator.locks) return;
+    this.isConnecting = true;
+    try {
+      while (!this.isClosed) {
+        if (self.navigator.onLine !== true) return;
+        await self.navigator.locks.request(
+          this.lockName,
+          { ifAvailable: true },
+          async (lockHandle) => {
+            if (!lockHandle || this.isClosed) return;
+            this.isLeader = true;
+            let socket;
+            try {
+              socket = new WebSocket(this.webSocketUrl);
+            } catch (e6) {
+              this.isLeader = false;
+              this.webSocket = null;
+              return;
+            }
+            socket.binaryType = "arraybuffer";
+            this.webSocket = socket;
+            socket.onopen = () => {
+              this.flushOutboundQueue();
+            };
+            socket.onmessage = (event) => {
+              const message = _msgpack.decode.call(void 0, event.data);
+              if (!message) return;
+              if (Array.isArray(message) && message[0] === "station-client-response" && typeof message[1] === "string") {
+                const id = message[1];
+                const pendingTarget = this.pendingTransactTargets.get(id);
+                if (pendingTarget) {
+                  clearTimeout(pendingTarget.timeoutId);
+                  this.pendingTransactTargets.delete(id);
+                  _optionalChain([this, 'access', _28 => _28.broadcastChannel, 'optionalAccess', _29 => _29.postMessage, 'call', _30 => _30({
+                    kind: "transact-response",
+                    id,
+                    target: pendingTarget.target,
+                    message: message[2]
+                  })]);
+                  return;
+                }
+                const pending = this.pendingTransacts.get(id);
+                if (!pending) return;
+                this.pendingTransacts.delete(id);
+                pending.cleanup();
+                pending.resolve(message[2]);
+                return;
+              }
+              this.eventTarget.dispatchEvent(
+                new CustomEvent("message", { detail: message })
+              );
+              _optionalChain([this, 'access', _31 => _31.broadcastChannel, 'optionalAccess', _32 => _32.postMessage, 'call', _33 => _33({
+                kind: "relay",
+                message
+              })]);
+            };
+            socket.onclose = () => {
+              if (this.webSocket === socket) this.webSocket = null;
+              this.isLeader = false;
+            };
+            await new Promise((resolve) => {
+              socket.addEventListener("close", () => resolve(), { once: true });
+            });
+            this.isLeader = false;
+            if (this.webSocket === socket) this.webSocket = null;
+          }
+        );
+        if (this.isClosed || self.navigator.onLine !== true) return;
+        await new Promise((resolve) => setTimeout(resolve, 1e4));
+      }
+    } finally {
+      this.isConnecting = false;
+    }
+  }
+}, _class);
+
+
+exports.StationClient = StationClient;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["c:\\Users\\jorts\\station-client\\dist\\index.cjs"],"names":[],"mappings":"AAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,2CAAiD;AACjD,IAAI,cAAc,YAAE,MAAM;AAC1B,iBAAE,YAAY,EAAE,IAAI,WAAW,CAAC,EAAC;AACjC,EAAE;AACF,EAAE;AACF,EAAE;AACF,kBAAE,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,EAAC;AACvC,kBAAE,cAAc,EAAE,CAAC,EAAE,GAAG;AACxB,IAAI,KAAK,IAAI,CAAC,oBAAoB,CAAC,CAAC;AACpC,EAAE,EAAC;AACH,kBAAE,iBAAiB,EAAE,KAAI;AACzB,kBAAE,UAAU,EAAE,KAAI;AAClB,kBAAE,SAAS,EAAE,MAAK;AAClB,kBAAE,SAAS,EAAE,MAAK;AAClB,kBAAE,aAAa,EAAE,MAAK;AACtB,kBAAE,cAAc,EAAE,CAAC,EAAC;AACpB,mBAAE,iBAAiB,kBAAkB,IAAI,GAAG,CAAC,EAAC;AAC9C,mBAAE,uBAAuB,kBAAkB,IAAI,GAAG,CAAC,EAAC;AACpD;AACA;AACA;AACA;AACA;AACA,EAAE,WAAW,CAAC,aAAa,EAAE,EAAE,EAAE;AACjC,IAAI,IAAI,CAAC,aAAa,EAAE,YAAY;AACpC,IAAI,IAAI,CAAC,YAAY,EAAE,CAAC,qBAAqB,EAAE,IAAI,CAAC,YAAY,CAAC,CAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,UAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,wBAAA;AACA,UAAA;AACA,UAAA;AACA,UAAA;AACA,UAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,UAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,oBAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,wBAAA;AACA,QAAA;AACA,0BAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,0BAAA;AACA,QAAA;AACA,MAAA;AACA,sBAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,sBAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,QAAA;AACA,0BAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,sBAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,sBAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA,EAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,IAAA;AACA,IAAA;AACA,EAAA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,MAAA;AACA,MAAA;AACA,QAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA,EAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,IAAA;AACA,MAAA;AACA,QAAA;AACA,QAAA;AACA,UAAA;AACA,UAAA;AACA,UAAA;AACA,YAAA;AACA,YAAA;AACA,YAAA;AACA,YAAA;AACA,cAAA;AACA,YAAA;AACA,cAAA;AACA,cAAA;AACA,cAAA;AACA,YAAA;AACA,YAAA;AACA,YAAA;AACA,YAAA;AACA,cAAA;AACA,YAAA;AACA,YAAA;AACA,cAAA;AACA,cAAA;AACA,cAAA;AACA,gBAAA;AACA,gBAAA;AACA,gBAAA;AACA,kBAAA;AACA,kBAAA;AACA,kCAAA;AACA,oBAAA;AACA,oBAAA;AACA,oBAAA;AACA,oBAAA;AACA,kBAAA;AACA,kBAAA;AACA,gBAAA;AACA,gBAAA;AACA,gBAAA;AACA,gBAAA;AACA,gBAAA;AACA,gBAAA;AACA,gBAAA;AACA,cAAA;AACA,cAAA;AACA,gBAAA;AACA,cAAA;AACA,8BAAA;AACA,gBAAA;AACA,gBAAA;AACA,cAAA;AACA,YAAA;AACA,YAAA;AACA,cAAA;AACA,cAAA;AACA,YAAA;AACA,YAAA;AACA,cAAA;AACA,YAAA;AACA,YAAA;AACA,YAAA;AACA,UAAA;AACA,QAAA;AACA,QAAA;AACA,QAAA;AACA,MAAA;AACA,IAAA;AACA,MAAA;AACA,IAAA;AACA,EAAA;AACA;AACA;AACA;AACA","file":"C:\\Users\\jorts\\station-client\\dist\\index.cjs","sourcesContent":[null]}

package/dist/index.d.cts

@@ -0,0 +1,107 @@
+/**
+ * Maps station client event names to their event payload shapes.
+ *
+ * @template T The application message shape.
+ */
+type StationClientEventMap<T extends Record<string, unknown>> = {
+    message: T;
+};
+/**
+ * Represents a strongly typed station client event listener.
+ *
+ * @template T The application message shape.
+ * @template K The event type.
+ */
+type StationClientEventListener<T extends Record<string, unknown>, K extends keyof StationClientEventMap<T>> = ((event: CustomEvent<StationClientEventMap<T>[K]>) => void) | {
+    handleEvent(event: CustomEvent<StationClientEventMap<T>[K]>): void;
+};
+/**
+ * Resolves an event name to its corresponding listener type.
+ *
+ * @template T The application message shape.
+ * @template K The event type.
+ */
+type StationClientEventListenerFor<T extends Record<string, unknown>, K extends string> = K extends keyof StationClientEventMap<T> ? StationClientEventListener<T, K> : EventListenerOrEventListenerObject;
+/**
+ * Provides options for {@link StationClient.transact}.
+ */
+type StationClientTransactOptions = {
+    /**
+     * An {@link AbortSignal} that can be used to cancel the operation.
+     */
+    signal?: AbortSignal;
+    /**
+     * The leader-side stale-entry time-to-live, in milliseconds.
+     */
+    ttlMs?: number;
+};
+
+/**
+ * Represents a base station client that coordinates local tab messaging and an opportunistic base station transport.
+ *
+ * @template T The application message shape.
+ */
+declare class StationClient<T extends Record<string, unknown>> {
+    private readonly eventTarget;
+    private readonly lockName;
+    private readonly channelName;
+    private readonly webSocketUrl;
+    private readonly instanceId;
+    private readonly onlineHandler;
+    private broadcastChannel;
+    private webSocket;
+    private isLeader;
+    private isClosed;
+    private isConnecting;
+    private readonly outboundQueue;
+    private readonly pendingTransacts;
+    private readonly pendingTransactTargets;
+    /**
+     * Initializes a new {@link StationClient} instance.
+     *
+     * @param webSocketUrl The base station WebSocket URL. When omitted, the instance operates in local-only mode.
+     */
+    constructor(webSocketUrl?: string);
+    /**main methods*/
+    /**
+     * Broadcasts a message to other same-origin contexts and opportunistically forwards it to the base station.
+     *
+     * @param message The message to broadcast.
+     */
+    relay(message: T): void;
+    /**
+     * Sends a request to the base station and resolves with the corresponding response message.
+     *
+     * @param message The message to send.
+     * @param options Options that control cancellation and stale follower cleanup.
+     * @returns A promise that resolves with the response message, or `false` when the request cannot be issued.
+     */
+    transact(message: T, options?: StationClientTransactOptions): Promise<T | false>;
+    /**
+     * Closes the client and releases its local and remote resources.
+     */
+    close(): void;
+    /**listeners*/
+    /**
+     * Appends an event listener for events whose type attribute value is `type`.
+     *
+     * @param type The event type to listen for.
+     * @param listener The callback that receives the event.
+     * @param options An options object that specifies characteristics about the event listener.
+     */
+    addEventListener<K extends keyof StationClientEventMap<T>>(type: K, listener: StationClientEventListenerFor<T, K> | null, options?: boolean | AddEventListenerOptions): void;
+    /**
+     * Removes an event listener previously registered with {@link addEventListener}.
+     *
+     * @param type The event type to remove.
+     * @param listener The callback to remove.
+     * @param options An options object that specifies characteristics about the event listener.
+     */
+    removeEventListener<K extends keyof StationClientEventMap<T>>(type: K, listener: StationClientEventListenerFor<T, K> | null, options?: boolean | EventListenerOptions): void;
+    /**helpers*/
+    private sendToStation;
+    private flushOutboundQueue;
+    private opportunisticConnect;
+}
+
+export { StationClient };

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Maps station client event names to their event payload shapes.
+ *
+ * @template T The application message shape.
+ */
+type StationClientEventMap<T extends Record<string, unknown>> = {
+    message: T;
+};
+/**
+ * Represents a strongly typed station client event listener.
+ *
+ * @template T The application message shape.
+ * @template K The event type.
+ */
+type StationClientEventListener<T extends Record<string, unknown>, K extends keyof StationClientEventMap<T>> = ((event: CustomEvent<StationClientEventMap<T>[K]>) => void) | {
+    handleEvent(event: CustomEvent<StationClientEventMap<T>[K]>): void;
+};
+/**
+ * Resolves an event name to its corresponding listener type.
+ *
+ * @template T The application message shape.
+ * @template K The event type.
+ */
+type StationClientEventListenerFor<T extends Record<string, unknown>, K extends string> = K extends keyof StationClientEventMap<T> ? StationClientEventListener<T, K> : EventListenerOrEventListenerObject;
+/**
+ * Provides options for {@link StationClient.transact}.
+ */
+type StationClientTransactOptions = {
+    /**
+     * An {@link AbortSignal} that can be used to cancel the operation.
+     */
+    signal?: AbortSignal;
+    /**
+     * The leader-side stale-entry time-to-live, in milliseconds.
+     */
+    ttlMs?: number;
+};
+
+/**
+ * Represents a base station client that coordinates local tab messaging and an opportunistic base station transport.
+ *
+ * @template T The application message shape.
+ */
+declare class StationClient<T extends Record<string, unknown>> {
+    private readonly eventTarget;
+    private readonly lockName;
+    private readonly channelName;
+    private readonly webSocketUrl;
+    private readonly instanceId;
+    private readonly onlineHandler;
+    private broadcastChannel;
+    private webSocket;
+    private isLeader;
+    private isClosed;
+    private isConnecting;
+    private readonly outboundQueue;
+    private readonly pendingTransacts;
+    private readonly pendingTransactTargets;
+    /**
+     * Initializes a new {@link StationClient} instance.
+     *
+     * @param webSocketUrl The base station WebSocket URL. When omitted, the instance operates in local-only mode.
+     */
+    constructor(webSocketUrl?: string);
+    /**main methods*/
+    /**
+     * Broadcasts a message to other same-origin contexts and opportunistically forwards it to the base station.
+     *
+     * @param message The message to broadcast.
+     */
+    relay(message: T): void;
+    /**
+     * Sends a request to the base station and resolves with the corresponding response message.
+     *
+     * @param message The message to send.
+     * @param options Options that control cancellation and stale follower cleanup.
+     * @returns A promise that resolves with the response message, or `false` when the request cannot be issued.
+     */
+    transact(message: T, options?: StationClientTransactOptions): Promise<T | false>;
+    /**
+     * Closes the client and releases its local and remote resources.
+     */
+    close(): void;
+    /**listeners*/
+    /**
+     * Appends an event listener for events whose type attribute value is `type`.
+     *
+     * @param type The event type to listen for.
+     * @param listener The callback that receives the event.
+     * @param options An options object that specifies characteristics about the event listener.
+     */
+    addEventListener<K extends keyof StationClientEventMap<T>>(type: K, listener: StationClientEventListenerFor<T, K> | null, options?: boolean | AddEventListenerOptions): void;
+    /**
+     * Removes an event listener previously registered with {@link addEventListener}.
+     *
+     * @param type The event type to remove.
+     * @param listener The callback to remove.
+     * @param options An options object that specifies characteristics about the event listener.
+     */
+    removeEventListener<K extends keyof StationClientEventMap<T>>(type: K, listener: StationClientEventListenerFor<T, K> | null, options?: boolean | EventListenerOptions): void;
+    /**helpers*/
+    private sendToStation;
+    private flushOutboundQueue;
+    private opportunisticConnect;
+}
+
+export { StationClient };