@cloudparse/up-miniapps-sdk 0.6.1 → 0.6.2

package/dist/index.d.cts

@@ -1614,6 +1614,15 @@ interface WsMessage {
     event?: string;
     [key: string]: unknown;
 }
+/**
+ * `"open"` is the only state where the wire connection is actually live —
+ * `"connecting"` covers both the initial handshake and every reconnect
+ * backoff wait, `"closed"` covers not-yet-started and lost-and-not-yet-
+ * retried. A consumer that wants a poll-based fallback (only meaningful
+ * while genuinely disconnected) should treat anything other than `"open"`
+ * as "poll".
+ */
+type WsConnectionStatus = "connecting" | "open" | "closed";
 interface BaseWsServiceOptions<TMessage extends WsMessage> {
     /**
      * The REST client from `createApiService` — reused here for two things:
@@ -1720,6 +1729,21 @@ interface WsServiceClient<TMessage extends WsMessage = WsMessage> {
      * function.
      */
     onMessage(callback: (message: TMessage) => void): () => void;
+    /**
+     * Current connection status, read synchronously — no subscription needed
+     * for a one-off check.
+     */
+    getStatus(): WsConnectionStatus;
+    /**
+     * Subscribes to connection status transitions. Fires once immediately
+     * with the current status on subscribe, then again on every change.
+     * Returns an unsubscribe function. Intended for a consumer that wants a
+     * poll-based fallback only while genuinely disconnected (see
+     * `WsConnectionStatus`'s own doc comment) — driving that off `onMessage`
+     * pings alone can't distinguish "connected but quiet" from "never
+     * connected".
+     */
+    onStatusChange(callback: (status: WsConnectionStatus) => void): () => void;
 }
 interface BroadcastWsServiceClient<TMessage extends WsMessage = WsMessage> {
     /** Opens the connection if not already open/connecting. Safe to call repeatedly. */
@@ -1733,6 +1757,10 @@ interface BroadcastWsServiceClient<TMessage extends WsMessage = WsMessage> {
      * client. Implicitly calls `connect()`. Returns an unsubscribe function.
      */
     onMessage(callback: (message: TMessage) => void): () => void;
+    /** Current connection status, read synchronously. See `WsConnectionStatus`. */
+    getStatus(): WsConnectionStatus;
+    /** Subscribes to connection status transitions. See `WsServiceClient.onStatusChange`. */
+    onStatusChange(callback: (status: WsConnectionStatus) => void): () => void;
 }
 /**
  * Creates a reconnecting, (usually) authenticated WebSocket client — the WS
@@ -1769,4 +1797,4 @@ interface BroadcastWsServiceClient<TMessage extends WsMessage = WsMessage> {
 declare function createWsService<TMessage extends WsMessage = WsMessage>(options: CreateChannelWsServiceOptions<TMessage>): WsServiceClient<TMessage>;
 declare function createWsService<TMessage extends WsMessage = WsMessage>(options: CreateBroadcastWsServiceOptions<TMessage>): BroadcastWsServiceClient<TMessage>;
 
-export { type ApiServiceClient, type BridgeMessageType, BridgeMocker, type BridgeMockerProps, type BroadcastWsServiceClient, type CenterCallbackParams, type CreateApiServiceOptions, type CreateBroadcastWsServiceOptions, type CreateChannelWsServiceOptions, type CreateWsServiceOptions, type CustomControl, DebugConsole, type DebugConsoleProps, type DeclarativeJourneyOptions, type DrawerState, type EtaData, type FidelityTransactionTypeType, type FlyToParams, GeolocationEvent, GlobalEvent, type HapticStyleType, type IBridgeEnvelope, type IContextState, type IEdgeInsets, type IFidelityBalance, type IFidelityHistoryParams, type IFidelityTransaction, type IGenerateQrCodeOptions, type IInitializationOptions, type IInitializationResponse, type ILocationData, type INetworkOptions, type INetworkResponse, type IPaymentRequest, type IPickImageResult, type ISaveImageResult, type IUserProfile, type LiveRoutingOptions, type LiveRoutingResult, type LocationStreamConfig, Map, MapControls, MapControlsContext, type MapControlsProps, type MapControlsState, type MapInsets, MapMenu, MapMenuDivider, type MapMenuDividerProps, MapMenuFooter, type MapMenuFooterProps, MapMenuItem, type MapMenuItemProps, type MapMenuProps, MapMenuTitle, type MapMenuTitleProps, type MapProps, type MenuItem, MiniAppSDK, MockLocationContext, type MockLocationContextType, type NetworkMethodType, type POI, QRScanner, type QRScannerProps, RouteLayer, type RouteLayerProps, RouteRequest, RouteResponse, RouteStep, type SDKEvent, SDKMapProvider, SDKProvider, type SDKProviderProps, type ScrollConfig, type StreamAccelerometerData, type StreamHeadingData, type StreamLocationData, type StreamUpdatePayload, type SwipeAxisPriority, SwipeCarousel, type SwipeCarouselItem, type SwipeCarouselProps, type SwipeCarouselVerticalDragConfig, UIEvent, type UseJourneyOptions, type UseJourneyResult, type UserLocationState, type WsMessage, type WsServiceClient, createApiService, createWsService, sdk as default, renderMap, sdk, useIsMocked, useJourney, useLiveRouting, useMapControls, useMockLocation, useRoute, useTrimmedRoute, useUserLocation };
+export { type ApiServiceClient, type BridgeMessageType, BridgeMocker, type BridgeMockerProps, type BroadcastWsServiceClient, type CenterCallbackParams, type CreateApiServiceOptions, type CreateBroadcastWsServiceOptions, type CreateChannelWsServiceOptions, type CreateWsServiceOptions, type CustomControl, DebugConsole, type DebugConsoleProps, type DeclarativeJourneyOptions, type DrawerState, type EtaData, type FidelityTransactionTypeType, type FlyToParams, GeolocationEvent, GlobalEvent, type HapticStyleType, type IBridgeEnvelope, type IContextState, type IEdgeInsets, type IFidelityBalance, type IFidelityHistoryParams, type IFidelityTransaction, type IGenerateQrCodeOptions, type IInitializationOptions, type IInitializationResponse, type ILocationData, type INetworkOptions, type INetworkResponse, type IPaymentRequest, type IPickImageResult, type ISaveImageResult, type IUserProfile, type LiveRoutingOptions, type LiveRoutingResult, type LocationStreamConfig, Map, MapControls, MapControlsContext, type MapControlsProps, type MapControlsState, type MapInsets, MapMenu, MapMenuDivider, type MapMenuDividerProps, MapMenuFooter, type MapMenuFooterProps, MapMenuItem, type MapMenuItemProps, type MapMenuProps, MapMenuTitle, type MapMenuTitleProps, type MapProps, type MenuItem, MiniAppSDK, MockLocationContext, type MockLocationContextType, type NetworkMethodType, type POI, QRScanner, type QRScannerProps, RouteLayer, type RouteLayerProps, RouteRequest, RouteResponse, RouteStep, type SDKEvent, SDKMapProvider, SDKProvider, type SDKProviderProps, type ScrollConfig, type StreamAccelerometerData, type StreamHeadingData, type StreamLocationData, type StreamUpdatePayload, type SwipeAxisPriority, SwipeCarousel, type SwipeCarouselItem, type SwipeCarouselProps, type SwipeCarouselVerticalDragConfig, UIEvent, type UseJourneyOptions, type UseJourneyResult, type UserLocationState, type WsConnectionStatus, type WsMessage, type WsServiceClient, createApiService, createWsService, sdk as default, renderMap, sdk, useIsMocked, useJourney, useLiveRouting, useMapControls, useMockLocation, useRoute, useTrimmedRoute, useUserLocation };

package/dist/index.d.ts

@@ -1614,6 +1614,15 @@ interface WsMessage {
     event?: string;
     [key: string]: unknown;
 }
+/**
+ * `"open"` is the only state where the wire connection is actually live —
+ * `"connecting"` covers both the initial handshake and every reconnect
+ * backoff wait, `"closed"` covers not-yet-started and lost-and-not-yet-
+ * retried. A consumer that wants a poll-based fallback (only meaningful
+ * while genuinely disconnected) should treat anything other than `"open"`
+ * as "poll".
+ */
+type WsConnectionStatus = "connecting" | "open" | "closed";
 interface BaseWsServiceOptions<TMessage extends WsMessage> {
     /**
      * The REST client from `createApiService` — reused here for two things:
@@ -1720,6 +1729,21 @@ interface WsServiceClient<TMessage extends WsMessage = WsMessage> {
      * function.
      */
     onMessage(callback: (message: TMessage) => void): () => void;
+    /**
+     * Current connection status, read synchronously — no subscription needed
+     * for a one-off check.
+     */
+    getStatus(): WsConnectionStatus;
+    /**
+     * Subscribes to connection status transitions. Fires once immediately
+     * with the current status on subscribe, then again on every change.
+     * Returns an unsubscribe function. Intended for a consumer that wants a
+     * poll-based fallback only while genuinely disconnected (see
+     * `WsConnectionStatus`'s own doc comment) — driving that off `onMessage`
+     * pings alone can't distinguish "connected but quiet" from "never
+     * connected".
+     */
+    onStatusChange(callback: (status: WsConnectionStatus) => void): () => void;
 }
 interface BroadcastWsServiceClient<TMessage extends WsMessage = WsMessage> {
     /** Opens the connection if not already open/connecting. Safe to call repeatedly. */
@@ -1733,6 +1757,10 @@ interface BroadcastWsServiceClient<TMessage extends WsMessage = WsMessage> {
      * client. Implicitly calls `connect()`. Returns an unsubscribe function.
      */
     onMessage(callback: (message: TMessage) => void): () => void;
+    /** Current connection status, read synchronously. See `WsConnectionStatus`. */
+    getStatus(): WsConnectionStatus;
+    /** Subscribes to connection status transitions. See `WsServiceClient.onStatusChange`. */
+    onStatusChange(callback: (status: WsConnectionStatus) => void): () => void;
 }
 /**
  * Creates a reconnecting, (usually) authenticated WebSocket client — the WS
@@ -1769,4 +1797,4 @@ interface BroadcastWsServiceClient<TMessage extends WsMessage = WsMessage> {
 declare function createWsService<TMessage extends WsMessage = WsMessage>(options: CreateChannelWsServiceOptions<TMessage>): WsServiceClient<TMessage>;
 declare function createWsService<TMessage extends WsMessage = WsMessage>(options: CreateBroadcastWsServiceOptions<TMessage>): BroadcastWsServiceClient<TMessage>;
 
-export { type ApiServiceClient, type BridgeMessageType, BridgeMocker, type BridgeMockerProps, type BroadcastWsServiceClient, type CenterCallbackParams, type CreateApiServiceOptions, type CreateBroadcastWsServiceOptions, type CreateChannelWsServiceOptions, type CreateWsServiceOptions, type CustomControl, DebugConsole, type DebugConsoleProps, type DeclarativeJourneyOptions, type DrawerState, type EtaData, type FidelityTransactionTypeType, type FlyToParams, GeolocationEvent, GlobalEvent, type HapticStyleType, type IBridgeEnvelope, type IContextState, type IEdgeInsets, type IFidelityBalance, type IFidelityHistoryParams, type IFidelityTransaction, type IGenerateQrCodeOptions, type IInitializationOptions, type IInitializationResponse, type ILocationData, type INetworkOptions, type INetworkResponse, type IPaymentRequest, type IPickImageResult, type ISaveImageResult, type IUserProfile, type LiveRoutingOptions, type LiveRoutingResult, type LocationStreamConfig, Map, MapControls, MapControlsContext, type MapControlsProps, type MapControlsState, type MapInsets, MapMenu, MapMenuDivider, type MapMenuDividerProps, MapMenuFooter, type MapMenuFooterProps, MapMenuItem, type MapMenuItemProps, type MapMenuProps, MapMenuTitle, type MapMenuTitleProps, type MapProps, type MenuItem, MiniAppSDK, MockLocationContext, type MockLocationContextType, type NetworkMethodType, type POI, QRScanner, type QRScannerProps, RouteLayer, type RouteLayerProps, RouteRequest, RouteResponse, RouteStep, type SDKEvent, SDKMapProvider, SDKProvider, type SDKProviderProps, type ScrollConfig, type StreamAccelerometerData, type StreamHeadingData, type StreamLocationData, type StreamUpdatePayload, type SwipeAxisPriority, SwipeCarousel, type SwipeCarouselItem, type SwipeCarouselProps, type SwipeCarouselVerticalDragConfig, UIEvent, type UseJourneyOptions, type UseJourneyResult, type UserLocationState, type WsMessage, type WsServiceClient, createApiService, createWsService, sdk as default, renderMap, sdk, useIsMocked, useJourney, useLiveRouting, useMapControls, useMockLocation, useRoute, useTrimmedRoute, useUserLocation };
+export { type ApiServiceClient, type BridgeMessageType, BridgeMocker, type BridgeMockerProps, type BroadcastWsServiceClient, type CenterCallbackParams, type CreateApiServiceOptions, type CreateBroadcastWsServiceOptions, type CreateChannelWsServiceOptions, type CreateWsServiceOptions, type CustomControl, DebugConsole, type DebugConsoleProps, type DeclarativeJourneyOptions, type DrawerState, type EtaData, type FidelityTransactionTypeType, type FlyToParams, GeolocationEvent, GlobalEvent, type HapticStyleType, type IBridgeEnvelope, type IContextState, type IEdgeInsets, type IFidelityBalance, type IFidelityHistoryParams, type IFidelityTransaction, type IGenerateQrCodeOptions, type IInitializationOptions, type IInitializationResponse, type ILocationData, type INetworkOptions, type INetworkResponse, type IPaymentRequest, type IPickImageResult, type ISaveImageResult, type IUserProfile, type LiveRoutingOptions, type LiveRoutingResult, type LocationStreamConfig, Map, MapControls, MapControlsContext, type MapControlsProps, type MapControlsState, type MapInsets, MapMenu, MapMenuDivider, type MapMenuDividerProps, MapMenuFooter, type MapMenuFooterProps, MapMenuItem, type MapMenuItemProps, type MapMenuProps, MapMenuTitle, type MapMenuTitleProps, type MapProps, type MenuItem, MiniAppSDK, MockLocationContext, type MockLocationContextType, type NetworkMethodType, type POI, QRScanner, type QRScannerProps, RouteLayer, type RouteLayerProps, RouteRequest, RouteResponse, RouteStep, type SDKEvent, SDKMapProvider, SDKProvider, type SDKProviderProps, type ScrollConfig, type StreamAccelerometerData, type StreamHeadingData, type StreamLocationData, type StreamUpdatePayload, type SwipeAxisPriority, SwipeCarousel, type SwipeCarouselItem, type SwipeCarouselProps, type SwipeCarouselVerticalDragConfig, UIEvent, type UseJourneyOptions, type UseJourneyResult, type UserLocationState, type WsConnectionStatus, type WsMessage, type WsServiceClient, createApiService, createWsService, sdk as default, renderMap, sdk, useIsMocked, useJourney, useLiveRouting, useMapControls, useMockLocation, useRoute, useTrimmedRoute, useUserLocation };

package/dist/index.js

@@ -3487,7 +3487,7 @@ var loadImage2 = (src) => new Promise((resolve, reject) => {
 });
 
 // package.json
-var version = "0.6.1";
+var version = "0.6.2";
 
 // src/sdk.ts
 function deepFreeze(obj) {
@@ -5093,6 +5093,13 @@ function createWsService(options) {
   let reconnectTimeout = null;
   let reconnectDelay = 1e3;
   let isConnecting = false;
+  let status = "closed";
+  const statusListeners = /* @__PURE__ */ new Set();
+  const setStatus = (next) => {
+    if (status === next) return;
+    status = next;
+    for (const cb of statusListeners) cb(status);
+  };
   const getWsUrl = () => options.baseUrl || options.api.wsUrl || "";
   const sendAction = (action, channelId) => {
     if (ws?.readyState === WebSocket.OPEN) {
@@ -5111,6 +5118,7 @@ function createWsService(options) {
       return;
     }
     isConnecting = true;
+    setStatus("connecting");
     try {
       const wsUrl = getWsUrl();
       if (!wsUrl) {
@@ -5118,6 +5126,7 @@ function createWsService(options) {
           "[WS] No WebSocket backend URL available, connection delayed."
         );
         isConnecting = false;
+        setStatus("closed");
         return;
       }
       let authParams = {};
@@ -5133,6 +5142,7 @@ function createWsService(options) {
       } else {
         console.warn("[WS] No auth available, connection delayed.");
         isConnecting = false;
+        setStatus("closed");
         return;
       }
       const params = new URLSearchParams({ ...options.query, ...authParams });
@@ -5140,6 +5150,7 @@ function createWsService(options) {
       ws = new WebSocket(query ? `${wsUrl}?${query}` : wsUrl);
       ws.onopen = () => {
         isConnecting = false;
+        setStatus("open");
         reconnectDelay = 1e3;
         if (channelField) {
           for (const channelId of subscriptions.keys()) {
@@ -5166,6 +5177,7 @@ function createWsService(options) {
       };
       ws.onclose = () => {
         isConnecting = false;
+        setStatus("closed");
         scheduleReconnect();
       };
       ws.onerror = (err) => {
@@ -5176,6 +5188,7 @@ function createWsService(options) {
     } catch (err) {
       console.error("[WS] Failed to establish connection:", err);
       isConnecting = false;
+      setStatus("closed");
       scheduleReconnect();
     }
   };
@@ -5189,6 +5202,15 @@ function createWsService(options) {
       ws.close();
       ws = null;
     }
+    setStatus("closed");
+  };
+  const getStatus = () => status;
+  const onStatusChange = (callback) => {
+    statusListeners.add(callback);
+    callback(status);
+    return () => {
+      statusListeners.delete(callback);
+    };
   };
   const subscribe = (channelId, callback) => {
     const isNewChannel = !subscriptions.has(channelId);
@@ -5214,9 +5236,9 @@ function createWsService(options) {
     };
   };
   if (channelField) {
-    return { connect, disconnect, onMessage, subscribe };
+    return { connect, disconnect, onMessage, subscribe, getStatus, onStatusChange };
   }
-  return { connect, disconnect, onMessage };
+  return { connect, disconnect, onMessage, getStatus, onStatusChange };
 }
 
 // src/index.ts