@cloudparse/up-miniapps-sdk 0.5.7 → 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. */
@@ -1528,6 +1530,13 @@ declare class MiniAppSDK {
      * @param options The options to provide to the shell app
      */
     initialize(options: IInitializationOptions): Promise<IInitializationResponse>;
+    /**
+     * Returns the last known `env` (shell-provided config like `backendUrl`),
+     * refreshed automatically by `initialize()` and every `UPDATE_CONTEXT`
+     * push — read this instead of caching your own copy of `env` values.
+     * Returns `null` before the first successful `initialize()`/context push.
+     */
+    getEnv<T extends Record<string, unknown> = Record<string, unknown>>(): T | null;
     /**
      * Registers a callback for a specific event from the native shell.
      * @param event The name of the event to listen for.
@@ -1548,4 +1557,216 @@ declare class MiniAppSDK {
  */
 declare const sdk: MiniAppSDK;
 
-export { type BridgeMessageType, BridgeMocker, type BridgeMockerProps, type CenterCallbackParams, 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, sdk as default, renderMap, sdk, useIsMocked, useJourney, useLiveRouting, useMapControls, useMockLocation, useRoute, useTrimmedRoute, useUserLocation };
+interface CreateApiServiceOptions {
+    /**
+     * Backend URL to use before the shell has ever supplied one via
+     * `initialize()`/`UPDATE_CONTEXT`, or if a boot ever completes without
+     * one (e.g. a degraded/standalone fallback). Should be the app's real
+     * production backend, typically read from a build-time env var baked
+     * via `.env.production` — never a local dev address, since that value
+     * is what actually reaches the network if the live one is ever missing.
+     */
+    defaultBaseUrl: string;
+    /** Same fallback role as `defaultBaseUrl`, for `wsUrl` instead of `baseUrl`. Optional — omit if this app derives its WS URL from `baseUrl` itself. */
+    defaultWsBackendUrl?: string;
+}
+interface ApiServiceClient {
+    /** Current backend URL — see `getBaseUrl`'s doc comment below for the full resolution order. */
+    readonly baseUrl: string;
+    /** Current WebSocket backend URL, same resolution order as `baseUrl` but reading the dedicated ws fields instead. `undefined` if neither the shell nor `defaultWsBackendUrl` ever supplied one. */
+    readonly wsUrl: string | undefined;
+    get<T = unknown>(path: string): Promise<INetworkResponse<T>>;
+    post<T = unknown>(path: string, body?: unknown): Promise<INetworkResponse<T>>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<INetworkResponse<T>>;
+    delete(path: string): Promise<INetworkResponse<void>>;
+    graphqlQuery<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<INetworkResponse<{
+        data: T;
+        errors?: {
+            message: string;
+        }[];
+    }>>;
+}
+/**
+ * Creates a small REST/GraphQL client that always proxies through
+ * `sdk.network.request` and always resolves the backend URL LIVE — from
+ * `window.__UP_BACKEND_URLS__` (earliest, synchronous, see
+ * `getEarlyBackendUrl` above), then `sdk.getEnv()` (updated by
+ * `initialize()`/`UPDATE_CONTEXT`) — never from a value cached at some
+ * earlier point in the boot sequence. This is the fix for a real,
+ * repeatedly reproduced bug: apps used to assign a mutable `baseUrl` field
+ * imperatively from `initialize()`'s response / `UPDATE_CONTEXT`; if that
+ * one assignment was ever skipped (e.g. the underlying bridge request
+ * losing its response — see `Bridge.send`'s retry, which reduces but does
+ * not entirely eliminate that risk) the field stayed wrong for the rest of
+ * the session, silently sending requests to `defaultBaseUrl` instead.
+ * Reading fresh here means the very next call after either source is
+ * populated self-heals automatically, and there is no second, independent
+ * copy of the URL that can go stale.
+ *
+ * Response shape is the raw `INetworkResponse<T>` (status/data/headers) —
+ * this stays a thin transport client; app-specific response unwrapping,
+ * error-message translation, etc. belong in each app's own thin wrapper
+ * around this, not here.
+ */
+declare function createApiService(options: CreateApiServiceOptions): ApiServiceClient;
+
+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. */
@@ -1528,6 +1530,13 @@ declare class MiniAppSDK {
      * @param options The options to provide to the shell app
      */
     initialize(options: IInitializationOptions): Promise<IInitializationResponse>;
+    /**
+     * Returns the last known `env` (shell-provided config like `backendUrl`),
+     * refreshed automatically by `initialize()` and every `UPDATE_CONTEXT`
+     * push — read this instead of caching your own copy of `env` values.
+     * Returns `null` before the first successful `initialize()`/context push.
+     */
+    getEnv<T extends Record<string, unknown> = Record<string, unknown>>(): T | null;
     /**
      * Registers a callback for a specific event from the native shell.
      * @param event The name of the event to listen for.
@@ -1548,4 +1557,216 @@ declare class MiniAppSDK {
  */
 declare const sdk: MiniAppSDK;
 
-export { type BridgeMessageType, BridgeMocker, type BridgeMockerProps, type CenterCallbackParams, 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, sdk as default, renderMap, sdk, useIsMocked, useJourney, useLiveRouting, useMapControls, useMockLocation, useRoute, useTrimmedRoute, useUserLocation };
+interface CreateApiServiceOptions {
+    /**
+     * Backend URL to use before the shell has ever supplied one via
+     * `initialize()`/`UPDATE_CONTEXT`, or if a boot ever completes without
+     * one (e.g. a degraded/standalone fallback). Should be the app's real
+     * production backend, typically read from a build-time env var baked
+     * via `.env.production` — never a local dev address, since that value
+     * is what actually reaches the network if the live one is ever missing.
+     */
+    defaultBaseUrl: string;
+    /** Same fallback role as `defaultBaseUrl`, for `wsUrl` instead of `baseUrl`. Optional — omit if this app derives its WS URL from `baseUrl` itself. */
+    defaultWsBackendUrl?: string;
+}
+interface ApiServiceClient {
+    /** Current backend URL — see `getBaseUrl`'s doc comment below for the full resolution order. */
+    readonly baseUrl: string;
+    /** Current WebSocket backend URL, same resolution order as `baseUrl` but reading the dedicated ws fields instead. `undefined` if neither the shell nor `defaultWsBackendUrl` ever supplied one. */
+    readonly wsUrl: string | undefined;
+    get<T = unknown>(path: string): Promise<INetworkResponse<T>>;
+    post<T = unknown>(path: string, body?: unknown): Promise<INetworkResponse<T>>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<INetworkResponse<T>>;
+    delete(path: string): Promise<INetworkResponse<void>>;
+    graphqlQuery<T = unknown>(query: string, variables?: Record<string, unknown>): Promise<INetworkResponse<{
+        data: T;
+        errors?: {
+            message: string;
+        }[];
+    }>>;
+}
+/**
+ * Creates a small REST/GraphQL client that always proxies through
+ * `sdk.network.request` and always resolves the backend URL LIVE — from
+ * `window.__UP_BACKEND_URLS__` (earliest, synchronous, see
+ * `getEarlyBackendUrl` above), then `sdk.getEnv()` (updated by
+ * `initialize()`/`UPDATE_CONTEXT`) — never from a value cached at some
+ * earlier point in the boot sequence. This is the fix for a real,
+ * repeatedly reproduced bug: apps used to assign a mutable `baseUrl` field
+ * imperatively from `initialize()`'s response / `UPDATE_CONTEXT`; if that
+ * one assignment was ever skipped (e.g. the underlying bridge request
+ * losing its response — see `Bridge.send`'s retry, which reduces but does
+ * not entirely eliminate that risk) the field stayed wrong for the rest of
+ * the session, silently sending requests to `defaultBaseUrl` instead.
+ * Reading fresh here means the very next call after either source is
+ * populated self-heals automatically, and there is no second, independent
+ * copy of the URL that can go stale.
+ *
+ * Response shape is the raw `INetworkResponse<T>` (status/data/headers) —
+ * this stays a thin transport client; app-specific response unwrapping,
+ * error-message translation, etc. belong in each app's own thin wrapper
+ * around this, not here.
+ */
+declare function createApiService(options: CreateApiServiceOptions): ApiServiceClient;
+
+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 };