@cloudparse/up-miniapps-sdk 0.6.0 → 0.6.1

package/dist/index.d.cts

@@ -70,6 +70,8 @@ interface IUserProfile {
     countryCode: string;
     /** Phone number without country code. */
     localNumber: string;
+    /** How the user's account was created/registered. */
+    registrationType: "up" | "apple" | "google";
     /** Admin status. */
     admin: boolean;
     /** UP points balance. */
@@ -1608,4 +1610,163 @@ interface ApiServiceClient {
  */
 declare function createApiService(options: CreateApiServiceOptions): ApiServiceClient;
 
-export { type ApiServiceClient, type BridgeMessageType, BridgeMocker, type BridgeMockerProps, type CenterCallbackParams, type CreateApiServiceOptions, 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, createApiService, sdk as default, renderMap, sdk, useIsMocked, useJourney, useLiveRouting, useMapControls, useMockLocation, useRoute, useTrimmedRoute, useUserLocation };
+interface WsMessage {
+    event?: string;
+    [key: string]: unknown;
+}
+interface BaseWsServiceOptions<TMessage extends WsMessage> {
+    /**
+     * The REST client from `createApiService` — reused here for two things:
+     * its live `wsUrl` (so this shares the exact same URL resolution as
+     * every REST/GraphQL call, no separate copy to go stale), and its
+     * `post()` to mint a short-lived WS auth ticket in production (see
+     * `ticketPath` below).
+     */
+    api: Pick<ApiServiceClient, "post" | "wsUrl">;
+    /**
+     * REST path (relative, via `api.post`) that mints a short-lived,
+     * single-use ticket for the WS handshake — a mini-app's JS never holds
+     * its own real bearer token in production (`sdk.network.request` proxies
+     * every REST/GraphQL call through the native host shell, which injects
+     * auth on its own side; a raw browser `WebSocket` has no equivalent
+     * bridge and no way to set a custom header, so it authenticates via a
+     * ticket fetched over that same working REST path instead). Expected to
+     * return `{ ticket: string }`. Defaults to `"/ws-ticket"`, matching the
+     * established backend convention (see up-miniapps-backend's
+     * `GetWSTicket`). Pass `null` to disable ticket auth entirely — only
+     * appropriate for a mini-app whose backend has no ws-ticket route yet,
+     * or a genuinely public route (see `requireAuth` below).
+     */
+    ticketPath?: string | null;
+    /**
+     * Raw JWT to use when NOT running inside the native shell (standalone
+     * dev browser) — the consuming app reads its own build-time
+     * `import.meta.env.VITE_DEV_TOKEN` and passes it here; the SDK itself
+     * has no access to a consuming app's Vite env (this package is bundled
+     * by tsup, not Vite). Only ever used outside the shell — a ticket is
+     * always preferred when `isRunningInsideNativeShell()` is true.
+     */
+    devToken?: string | null;
+    /**
+     * Overrides the resolved WS URL outright, for a mini-app whose WS
+     * gateway genuinely lives somewhere `api.wsUrl` doesn't cover. Most
+     * consumers should leave this unset and rely on `api.wsUrl`.
+     */
+    baseUrl?: string;
+    /**
+     * Extra static query params appended to every connection URL. Browsers
+     * (and this WebView) give a raw `WebSocket` no custom-header API — a
+     * query param is the closest equivalent, e.g. for a custom auth scheme
+     * on top of the ticket/token this already sends.
+     */
+    query?: Record<string, string>;
+    /**
+     * When unset/`true` (the default), `connect()` refuses — warns and
+     * delays rather than opening an unauthenticated socket — if neither a
+     * ticket nor `devToken` is available. This is a deliberate safety net:
+     * a channel-scoped app (ticket-authorized per-room access) accidentally
+     * shipping with no auth configured would silently become an open room,
+     * not a loud failure.
+     *
+     * Set to `false` only for a backend route that's genuinely public with
+     * no per-connection identity at all — e.g. up-miniapps-by-night's `/ws`,
+     * which has no auth middleware by design, broadcasts the same public
+     * data to every connection, and has no rooms to gate. `connect()` then
+     * opens the socket with no ticket/token query param whatsoever. Pair
+     * with `ticketPath: null` (no point minting a ticket nobody checks).
+     */
+    requireAuth?: boolean;
+}
+/** Options for the channel-scoped mode — pass `channelField` to subscribe/unsubscribe to specific rooms. */
+interface CreateChannelWsServiceOptions<TMessage extends WsMessage = WsMessage> extends BaseWsServiceOptions<TMessage> {
+    /**
+     * Name of the field on each message that identifies which "room"/channel
+     * it belongs to (e.g. `"groupUuid"`, `"gameUuid"`). Also the field name
+     * used in the `{action, [channelField]: id}` subscribe/unsubscribe wire
+     * messages sent to the backend. Presence of this field is what selects
+     * channel mode over broadcast mode — see `CreateBroadcastWsServiceOptions`.
+     */
+    channelField: string;
+}
+/** Options for broadcast mode — omit `channelField` for a single global socket with no room concept. */
+interface CreateBroadcastWsServiceOptions<TMessage extends WsMessage = WsMessage> extends BaseWsServiceOptions<TMessage> {
+    channelField?: undefined;
+}
+type CreateWsServiceOptions<TMessage extends WsMessage = WsMessage> = CreateChannelWsServiceOptions<TMessage> | CreateBroadcastWsServiceOptions<TMessage>;
+interface WsServiceClient<TMessage extends WsMessage = WsMessage> {
+    /** Opens the connection if not already open/connecting. Safe to call repeatedly. */
+    connect(): Promise<void>;
+    /** Closes the connection and cancels any pending reconnect — no further automatic reconnect happens until `connect()`/`subscribe()` is called again. */
+    disconnect(): void;
+    /**
+     * Subscribes to every message for one channel id. Sends the shared
+     * `{action: "subscribe", [channelField]: id}` wire message automatically
+     * on the first subscriber for that channel (and `"unsubscribe"` on the
+     * last one leaving), and implicitly calls `connect()`. Returns an
+     * unsubscribe function. Multiple concurrent channel ids are fully
+     * supported — each gets its own wire subscribe/unsubscribe message and
+     * its own dispatch, independent of every other channel's subscribers.
+     */
+    subscribe(channelId: string, callback: (message: TMessage) => void): () => void;
+    /**
+     * Subscribes to every message this socket ever receives, regardless of
+     * channel — no wire message is sent for this (there's nothing to
+     * subscribe/unsubscribe to, it's just an additional tap on the same
+     * stream). Runs *alongside* any active `subscribe()` channel
+     * subscriptions, socket.io-style ("join specific rooms AND listen
+     * globally at once") — a message matching an active channel id is
+     * delivered to both that channel's subscribers and every `onMessage`
+     * listener. Implicitly calls `connect()`. Returns an unsubscribe
+     * function.
+     */
+    onMessage(callback: (message: TMessage) => void): () => void;
+}
+interface BroadcastWsServiceClient<TMessage extends WsMessage = WsMessage> {
+    /** Opens the connection if not already open/connecting. Safe to call repeatedly. */
+    connect(): Promise<void>;
+    /** Closes the connection and cancels any pending reconnect. */
+    disconnect(): void;
+    /**
+     * Subscribes to every message this socket ever receives — there's no
+     * room/channel concept in broadcast mode, so no subscribe/unsubscribe
+     * wire message is ever sent; the backend just pushes to every connected
+     * client. Implicitly calls `connect()`. Returns an unsubscribe function.
+     */
+    onMessage(callback: (message: TMessage) => void): () => void;
+}
+/**
+ * Creates a reconnecting, (usually) authenticated WebSocket client — the WS
+ * counterpart to `createApiService`. Centralizes exactly what every
+ * `up-miniapps-*` app was independently hand-rolling with small drifting
+ * bugs (one app's WS URL was captured once at construction and never
+ * recomputed for the whole session; another always used a dev-only token
+ * even in production, so it could never actually authenticate on a real
+ * device): live URL resolution, ticket-based production auth with a
+ * standalone-dev-token fallback, and exponential-backoff reconnect.
+ *
+ * Two modes, selected by whether `channelField` is present:
+ * - **Channel mode** (`channelField` set): room-scoped pub/sub, matches
+ *   up-miniapps-split/up-miniapps-cursor's group/game-room shape. Returns a
+ *   `WsServiceClient` with `subscribe(channelId, cb)` — multiple concurrent
+ *   channel ids are fully supported — PLUS `onMessage(cb)`, a catch-all that
+ *   runs alongside any active channel subscriptions (socket.io-style: join
+ *   specific rooms and listen globally at the same time, on one socket).
+ * - **Broadcast mode** (`channelField` omitted): one global socket, no
+ *   rooms, no subscribe/unsubscribe wire protocol — every message goes to
+ *   every listener. Matches up-miniapps-by-night's public live-update feed
+ *   (reactions/flash/favorite counts), which has no per-room access to gate
+ *   in the first place. Returns a `BroadcastWsServiceClient` with only
+ *   `onMessage(cb)` (no `subscribe` — there's no channel id to subscribe to).
+ *
+ * Deliberately stays a thin transport in both modes, same boundary as
+ * `createApiService`: message *content* interpretation (e.g. treating one
+ * event name as carrying real payload while every other message is a bare
+ * cache-invalidation ping) belongs in each app's own thin wrapper around
+ * this, not here — apps differ enough in what they consider safe to expose
+ * over WS that baking that policy into the SDK would be the wrong
+ * boundary.
+ */
+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 };

package/dist/index.d.ts

@@ -70,6 +70,8 @@ interface IUserProfile {
     countryCode: string;
     /** Phone number without country code. */
     localNumber: string;
+    /** How the user's account was created/registered. */
+    registrationType: "up" | "apple" | "google";
     /** Admin status. */
     admin: boolean;
     /** UP points balance. */
@@ -1608,4 +1610,163 @@ interface ApiServiceClient {
  */
 declare function createApiService(options: CreateApiServiceOptions): ApiServiceClient;
 
-export { type ApiServiceClient, type BridgeMessageType, BridgeMocker, type BridgeMockerProps, type CenterCallbackParams, type CreateApiServiceOptions, 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, createApiService, sdk as default, renderMap, sdk, useIsMocked, useJourney, useLiveRouting, useMapControls, useMockLocation, useRoute, useTrimmedRoute, useUserLocation };
+interface WsMessage {
+    event?: string;
+    [key: string]: unknown;
+}
+interface BaseWsServiceOptions<TMessage extends WsMessage> {
+    /**
+     * The REST client from `createApiService` — reused here for two things:
+     * its live `wsUrl` (so this shares the exact same URL resolution as
+     * every REST/GraphQL call, no separate copy to go stale), and its
+     * `post()` to mint a short-lived WS auth ticket in production (see
+     * `ticketPath` below).
+     */
+    api: Pick<ApiServiceClient, "post" | "wsUrl">;
+    /**
+     * REST path (relative, via `api.post`) that mints a short-lived,
+     * single-use ticket for the WS handshake — a mini-app's JS never holds
+     * its own real bearer token in production (`sdk.network.request` proxies
+     * every REST/GraphQL call through the native host shell, which injects
+     * auth on its own side; a raw browser `WebSocket` has no equivalent
+     * bridge and no way to set a custom header, so it authenticates via a
+     * ticket fetched over that same working REST path instead). Expected to
+     * return `{ ticket: string }`. Defaults to `"/ws-ticket"`, matching the
+     * established backend convention (see up-miniapps-backend's
+     * `GetWSTicket`). Pass `null` to disable ticket auth entirely — only
+     * appropriate for a mini-app whose backend has no ws-ticket route yet,
+     * or a genuinely public route (see `requireAuth` below).
+     */
+    ticketPath?: string | null;
+    /**
+     * Raw JWT to use when NOT running inside the native shell (standalone
+     * dev browser) — the consuming app reads its own build-time
+     * `import.meta.env.VITE_DEV_TOKEN` and passes it here; the SDK itself
+     * has no access to a consuming app's Vite env (this package is bundled
+     * by tsup, not Vite). Only ever used outside the shell — a ticket is
+     * always preferred when `isRunningInsideNativeShell()` is true.
+     */
+    devToken?: string | null;
+    /**
+     * Overrides the resolved WS URL outright, for a mini-app whose WS
+     * gateway genuinely lives somewhere `api.wsUrl` doesn't cover. Most
+     * consumers should leave this unset and rely on `api.wsUrl`.
+     */
+    baseUrl?: string;
+    /**
+     * Extra static query params appended to every connection URL. Browsers
+     * (and this WebView) give a raw `WebSocket` no custom-header API — a
+     * query param is the closest equivalent, e.g. for a custom auth scheme
+     * on top of the ticket/token this already sends.
+     */
+    query?: Record<string, string>;
+    /**
+     * When unset/`true` (the default), `connect()` refuses — warns and
+     * delays rather than opening an unauthenticated socket — if neither a
+     * ticket nor `devToken` is available. This is a deliberate safety net:
+     * a channel-scoped app (ticket-authorized per-room access) accidentally
+     * shipping with no auth configured would silently become an open room,
+     * not a loud failure.
+     *
+     * Set to `false` only for a backend route that's genuinely public with
+     * no per-connection identity at all — e.g. up-miniapps-by-night's `/ws`,
+     * which has no auth middleware by design, broadcasts the same public
+     * data to every connection, and has no rooms to gate. `connect()` then
+     * opens the socket with no ticket/token query param whatsoever. Pair
+     * with `ticketPath: null` (no point minting a ticket nobody checks).
+     */
+    requireAuth?: boolean;
+}
+/** Options for the channel-scoped mode — pass `channelField` to subscribe/unsubscribe to specific rooms. */
+interface CreateChannelWsServiceOptions<TMessage extends WsMessage = WsMessage> extends BaseWsServiceOptions<TMessage> {
+    /**
+     * Name of the field on each message that identifies which "room"/channel
+     * it belongs to (e.g. `"groupUuid"`, `"gameUuid"`). Also the field name
+     * used in the `{action, [channelField]: id}` subscribe/unsubscribe wire
+     * messages sent to the backend. Presence of this field is what selects
+     * channel mode over broadcast mode — see `CreateBroadcastWsServiceOptions`.
+     */
+    channelField: string;
+}
+/** Options for broadcast mode — omit `channelField` for a single global socket with no room concept. */
+interface CreateBroadcastWsServiceOptions<TMessage extends WsMessage = WsMessage> extends BaseWsServiceOptions<TMessage> {
+    channelField?: undefined;
+}
+type CreateWsServiceOptions<TMessage extends WsMessage = WsMessage> = CreateChannelWsServiceOptions<TMessage> | CreateBroadcastWsServiceOptions<TMessage>;
+interface WsServiceClient<TMessage extends WsMessage = WsMessage> {
+    /** Opens the connection if not already open/connecting. Safe to call repeatedly. */
+    connect(): Promise<void>;
+    /** Closes the connection and cancels any pending reconnect — no further automatic reconnect happens until `connect()`/`subscribe()` is called again. */
+    disconnect(): void;
+    /**
+     * Subscribes to every message for one channel id. Sends the shared
+     * `{action: "subscribe", [channelField]: id}` wire message automatically
+     * on the first subscriber for that channel (and `"unsubscribe"` on the
+     * last one leaving), and implicitly calls `connect()`. Returns an
+     * unsubscribe function. Multiple concurrent channel ids are fully
+     * supported — each gets its own wire subscribe/unsubscribe message and
+     * its own dispatch, independent of every other channel's subscribers.
+     */
+    subscribe(channelId: string, callback: (message: TMessage) => void): () => void;
+    /**
+     * Subscribes to every message this socket ever receives, regardless of
+     * channel — no wire message is sent for this (there's nothing to
+     * subscribe/unsubscribe to, it's just an additional tap on the same
+     * stream). Runs *alongside* any active `subscribe()` channel
+     * subscriptions, socket.io-style ("join specific rooms AND listen
+     * globally at once") — a message matching an active channel id is
+     * delivered to both that channel's subscribers and every `onMessage`
+     * listener. Implicitly calls `connect()`. Returns an unsubscribe
+     * function.
+     */
+    onMessage(callback: (message: TMessage) => void): () => void;
+}
+interface BroadcastWsServiceClient<TMessage extends WsMessage = WsMessage> {
+    /** Opens the connection if not already open/connecting. Safe to call repeatedly. */
+    connect(): Promise<void>;
+    /** Closes the connection and cancels any pending reconnect. */
+    disconnect(): void;
+    /**
+     * Subscribes to every message this socket ever receives — there's no
+     * room/channel concept in broadcast mode, so no subscribe/unsubscribe
+     * wire message is ever sent; the backend just pushes to every connected
+     * client. Implicitly calls `connect()`. Returns an unsubscribe function.
+     */
+    onMessage(callback: (message: TMessage) => void): () => void;
+}
+/**
+ * Creates a reconnecting, (usually) authenticated WebSocket client — the WS
+ * counterpart to `createApiService`. Centralizes exactly what every
+ * `up-miniapps-*` app was independently hand-rolling with small drifting
+ * bugs (one app's WS URL was captured once at construction and never
+ * recomputed for the whole session; another always used a dev-only token
+ * even in production, so it could never actually authenticate on a real
+ * device): live URL resolution, ticket-based production auth with a
+ * standalone-dev-token fallback, and exponential-backoff reconnect.
+ *
+ * Two modes, selected by whether `channelField` is present:
+ * - **Channel mode** (`channelField` set): room-scoped pub/sub, matches
+ *   up-miniapps-split/up-miniapps-cursor's group/game-room shape. Returns a
+ *   `WsServiceClient` with `subscribe(channelId, cb)` — multiple concurrent
+ *   channel ids are fully supported — PLUS `onMessage(cb)`, a catch-all that
+ *   runs alongside any active channel subscriptions (socket.io-style: join
+ *   specific rooms and listen globally at the same time, on one socket).
+ * - **Broadcast mode** (`channelField` omitted): one global socket, no
+ *   rooms, no subscribe/unsubscribe wire protocol — every message goes to
+ *   every listener. Matches up-miniapps-by-night's public live-update feed
+ *   (reactions/flash/favorite counts), which has no per-room access to gate
+ *   in the first place. Returns a `BroadcastWsServiceClient` with only
+ *   `onMessage(cb)` (no `subscribe` — there's no channel id to subscribe to).
+ *
+ * Deliberately stays a thin transport in both modes, same boundary as
+ * `createApiService`: message *content* interpretation (e.g. treating one
+ * event name as carrying real payload while every other message is a bare
+ * cache-invalidation ping) belongs in each app's own thin wrapper around
+ * this, not here — apps differ enough in what they consider safe to expose
+ * over WS that baking that policy into the SDK would be the wrong
+ * boundary.
+ */
+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 };

package/dist/index.js

@@ -62,6 +62,13 @@ var Button = React.forwardRef(
 );
 Button.displayName = "Button";
 
+// src/utils/environment.ts
+function isRunningInsideNativeShell() {
+  if (typeof window === "undefined") return false;
+  const w = window;
+  return w.__UP_REACT_NATIVE_APP__ === true || !!w.ReactNativeWebView;
+}
+
 // src/bridge.ts
 var BridgeTimeoutError = class extends Error {
 };
@@ -234,8 +241,7 @@ var Bridge = class {
    * Determine environment. Check flag or cache result.
    */
   isNative() {
-    if (typeof window === "undefined") return false;
-    return window.__UP_REACT_NATIVE_APP__ === true || !!window.ReactNativeWebView;
+    return isRunningInsideNativeShell();
   }
 };
 
@@ -1995,14 +2001,14 @@ var useUserLocation = () => {
   });
   const mapPayload = useCallback3((payload) => {
     const coords = payload.location?.coords || payload.coords;
-    const headingData = payload.heading || payload.coords;
+    const headingData = payload.heading;
     const newCoords = coords ? [coords.longitude, coords.latitude] : null;
     let heading = null;
     if (headingData?.trueHeading !== void 0 && headingData.trueHeading >= 0) {
       heading = headingData.trueHeading;
     } else if (headingData?.magneticHeading !== void 0 && headingData.magneticHeading >= 0) {
       heading = headingData.magneticHeading;
-    } else if (headingData?.heading !== null && headingData.heading >= 0) {
+    } else if (headingData?.heading !== null && headingData?.heading >= 0) {
       heading = headingData.heading;
     }
     return {
@@ -2479,7 +2485,14 @@ import { jsx as jsx11, jsxs as jsxs8 } from "react/jsx-runtime";
 var MockRadiusLayer = ({
   center,
   radiusMeters,
-  color = "#39ff88"
+  // Neutral gray, not any one app's accent color — this debug aid is shared
+  // across every mini-app (each with its own, different palette), so it
+  // shouldn't default to a color that reads as "part of the app" (was
+  // #39ff88, a neon green/yellow left over from an earlier shared theme,
+  // reported as looking like an unwanted yellow border around the user's
+  // position marker in up-miniapps-explore, which has since moved to a
+  // pastel palette with no neon accents at all).
+  color = "#e2e8f0"
 }) => {
   const data = useMemo4(
     () => buildGeoCircle(center, radiusMeters),
@@ -3474,7 +3487,7 @@ var loadImage2 = (src) => new Promise((resolve, reject) => {
 });
 
 // package.json
-var version = "0.6.0";
+var version = "0.6.1";
 
 // src/sdk.ts
 function deepFreeze(obj) {
@@ -5071,6 +5084,141 @@ function createApiService(options) {
   };
 }
 
+// src/services/wsService.ts
+function createWsService(options) {
+  const channelField = options.channelField;
+  let ws = null;
+  const subscriptions = /* @__PURE__ */ new Map();
+  const globalListeners = /* @__PURE__ */ new Set();
+  let reconnectTimeout = null;
+  let reconnectDelay = 1e3;
+  let isConnecting = false;
+  const getWsUrl = () => options.baseUrl || options.api.wsUrl || "";
+  const sendAction = (action, channelId) => {
+    if (ws?.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ action, [channelField]: channelId }));
+    }
+  };
+  const scheduleReconnect = () => {
+    if (reconnectTimeout) clearTimeout(reconnectTimeout);
+    reconnectTimeout = setTimeout(() => {
+      reconnectDelay = Math.min(reconnectDelay * 2, 3e4);
+      connect();
+    }, reconnectDelay);
+  };
+  const connect = async () => {
+    if (ws?.readyState === WebSocket.OPEN || ws?.readyState === WebSocket.CONNECTING || isConnecting) {
+      return;
+    }
+    isConnecting = true;
+    try {
+      const wsUrl = getWsUrl();
+      if (!wsUrl) {
+        console.warn(
+          "[WS] No WebSocket backend URL available, connection delayed."
+        );
+        isConnecting = false;
+        return;
+      }
+      let authParams = {};
+      if (isRunningInsideNativeShell() && options.ticketPath !== null) {
+        const ticketResponse = await options.api.post(
+          options.ticketPath ?? "/ws-ticket"
+        );
+        authParams = { ticket: ticketResponse.data.ticket };
+      } else if (options.devToken) {
+        const rawJwt = options.devToken.startsWith("Bearer ") ? options.devToken.slice(7) : options.devToken;
+        authParams = { token: rawJwt };
+      } else if (options.requireAuth === false) {
+      } else {
+        console.warn("[WS] No auth available, connection delayed.");
+        isConnecting = false;
+        return;
+      }
+      const params = new URLSearchParams({ ...options.query, ...authParams });
+      const query = params.toString();
+      ws = new WebSocket(query ? `${wsUrl}?${query}` : wsUrl);
+      ws.onopen = () => {
+        isConnecting = false;
+        reconnectDelay = 1e3;
+        if (channelField) {
+          for (const channelId of subscriptions.keys()) {
+            sendAction("subscribe", channelId);
+          }
+        }
+      };
+      ws.onmessage = (event) => {
+        try {
+          const payload = JSON.parse(event.data);
+          if (channelField) {
+            const channelId = payload[channelField];
+            if (typeof channelId === "string") {
+              const callbacks = subscriptions.get(channelId);
+              if (callbacks) {
+                for (const cb of callbacks) cb(payload);
+              }
+            }
+          }
+          for (const cb of globalListeners) cb(payload);
+        } catch (err) {
+          console.error("[WS] Failed to parse message:", err);
+        }
+      };
+      ws.onclose = () => {
+        isConnecting = false;
+        scheduleReconnect();
+      };
+      ws.onerror = (err) => {
+        console.error("[WS] error:", err);
+        isConnecting = false;
+        ws?.close();
+      };
+    } catch (err) {
+      console.error("[WS] Failed to establish connection:", err);
+      isConnecting = false;
+      scheduleReconnect();
+    }
+  };
+  const disconnect = () => {
+    if (reconnectTimeout) {
+      clearTimeout(reconnectTimeout);
+      reconnectTimeout = null;
+    }
+    if (ws) {
+      ws.onclose = null;
+      ws.close();
+      ws = null;
+    }
+  };
+  const subscribe = (channelId, callback) => {
+    const isNewChannel = !subscriptions.has(channelId);
+    if (isNewChannel) subscriptions.set(channelId, /* @__PURE__ */ new Set());
+    subscriptions.get(channelId)?.add(callback);
+    if (isNewChannel) sendAction("subscribe", channelId);
+    connect();
+    return () => {
+      const set = subscriptions.get(channelId);
+      if (!set) return;
+      set.delete(callback);
+      if (set.size === 0) {
+        subscriptions.delete(channelId);
+        sendAction("unsubscribe", channelId);
+      }
+    };
+  };
+  const onMessage = (callback) => {
+    globalListeners.add(callback);
+    connect();
+    return () => {
+      globalListeners.delete(callback);
+    };
+  };
+  if (channelField) {
+    return { connect, disconnect, onMessage, subscribe };
+  }
+  return { connect, disconnect, onMessage };
+}
+
 // src/index.ts
 var src_default = sdk;
 export {
@@ -5095,6 +5243,7 @@ export {
   SwipeCarousel,
   UIEvent,
   createApiService,
+  createWsService,
   src_default as default,
   handleClearRoute,
   handleDrawRoute,