@cloudparse/up-miniapps-sdk 0.5.7 → 0.6.0

package/dist/index.d.cts

@@ -1528,6 +1528,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 +1555,57 @@ 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;
+
+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 };

package/dist/index.d.ts

@@ -1528,6 +1528,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 +1555,57 @@ 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;
+
+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 };

package/dist/index.js

@@ -63,6 +63,8 @@ var Button = React.forwardRef(
 Button.displayName = "Button";
 
 // src/bridge.ts
+var BridgeTimeoutError = class extends Error {
+};
 var Bridge = class {
   callbacks = /* @__PURE__ */ new Map();
   eventListeners = /* @__PURE__ */ new Map();
@@ -133,18 +135,32 @@ var Bridge = class {
    * @param type The action type (e.g., "GET_LOCATION").
    * @param payload Data associated with the action.
    * @param timeoutMs Time in milliseconds to wait for a response before rejecting.
+   * @param retries Number of additional attempts if a request times out (default 1 — one retry).
+   *   Exists because the response for a request can be lost in transit — e.g. the host's
+   *   injected response script running before this WebView's own `message` listener has
+   *   attached, worse under rapid mount/unmount cycles — with no application-visible symptom
+   *   other than the full 30s timeout. A blind retry self-heals that class of loss without
+   *   needing to diagnose which specific transport race dropped the original message; every
+   *   call site benefits automatically instead of each consumer app hand-rolling its own
+   *   retry-after-catch logic (which previously only covered `initialize()`, and imperfectly).
    * @returns A promise that resolves with the native response.
    */
-  send(type, payload, timeoutMs = 3e4) {
+  send(type, payload, timeoutMs = 3e4, retries = 1) {
     if (!this.isNative()) {
       return this.handleMockMessage(type, payload);
     }
+    return this.sendOnce(type, payload, timeoutMs).catch((err) => {
+      if (retries <= 0 || !(err instanceof BridgeTimeoutError)) throw err;
+      return this.send(type, payload, timeoutMs, retries - 1);
+    });
+  }
+  sendOnce(type, payload, timeoutMs) {
     return new Promise((resolve, reject) => {
       const callbackId = `${type}_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
       const timeout = setTimeout(() => {
         if (this.callbacks.has(callbackId)) {
           this.callbacks.delete(callbackId);
-          reject(new Error(`Bridge request timeout: ${type}`));
+          reject(new BridgeTimeoutError(`Bridge request timeout: ${type}`));
         }
       }, timeoutMs);
       this.callbacks.set(callbackId, {
@@ -3458,7 +3474,7 @@ var loadImage2 = (src) => new Promise((resolve, reject) => {
 });
 
 // package.json
-var version = "0.5.7";
+var version = "0.6.0";
 
 // src/sdk.ts
 function deepFreeze(obj) {
@@ -3473,6 +3489,7 @@ function deepFreeze(obj) {
   return Object.freeze(obj);
 }
 var globalRoutingConfig = null;
+var lastKnownEnv = null;
 var MiniAppSDK = class {
   /**
    * Map services.
@@ -3795,7 +3812,14 @@ var MiniAppSDK = class {
   });
   constructor() {
     this.bridge = new Bridge();
+    this.bridge.on(
+      "UPDATE_CONTEXT" /* UPDATE_CONTEXT */,
+      (data) => {
+        if (data?.env) lastKnownEnv = data.env;
+      }
+    );
     this.initialize = this.initialize.bind(this);
+    this.getEnv = this.getEnv.bind(this);
     this.on = this.on.bind(this);
     this.off = this.off.bind(this);
   }
@@ -3819,8 +3843,22 @@ var MiniAppSDK = class {
    * The starting point for the Mini-App. Must be called before any other SDK methods.
    * @param options The options to provide to the shell app
    */
-  initialize(options) {
-    return this.bridge.send("INITIALIZE", options);
+  async initialize(options) {
+    const res = await this.bridge.send(
+      "INITIALIZE",
+      options
+    );
+    if (res?.env) lastKnownEnv = res.env;
+    return res;
+  }
+  /**
+   * 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() {
+    return lastKnownEnv;
   }
   /**
    * Registers a callback for a specific event from the native shell.
@@ -4967,6 +5005,72 @@ var SwipeCarousel = ({
   );
 };
 
+// src/services/apiService.ts
+function buildUrl(baseUrl, path) {
+  if (path.startsWith("http://") || path.startsWith("https://")) {
+    return path;
+  }
+  let cleanBase = baseUrl.trim();
+  while (cleanBase.endsWith("/")) {
+    cleanBase = cleanBase.slice(0, -1);
+  }
+  let cleanPath = path.trim();
+  if (!cleanPath.startsWith("/")) {
+    cleanPath = `/${cleanPath}`;
+  }
+  const baseEndsWithV1 = cleanBase.endsWith("/api/v1");
+  const pathStartsWithV1 = cleanPath.startsWith("/api/v1/") || cleanPath === "/api/v1";
+  if (baseEndsWithV1 && pathStartsWithV1) {
+    const strippedPath = cleanPath.slice(7);
+    return `${cleanBase}${strippedPath}`;
+  }
+  return `${cleanBase}${cleanPath}`;
+}
+function getEarlyBackendUrl(kind) {
+  if (typeof window === "undefined") return void 0;
+  const early = window.__UP_BACKEND_URLS__;
+  return early?.[kind] ?? void 0;
+}
+function createApiService(options) {
+  const getBaseUrl = () => getEarlyBackendUrl("http") || sdk.getEnv()?.backendUrl || options.defaultBaseUrl;
+  const getWsUrl = () => getEarlyBackendUrl("ws") || sdk.getEnv()?.wsBackendUrl || options.defaultWsBackendUrl;
+  return {
+    get baseUrl() {
+      return getBaseUrl();
+    },
+    delete: (path) => sdk.network.request({
+      method: "DELETE",
+      url: buildUrl(getBaseUrl(), path)
+    }),
+    get: (path) => sdk.network.request({
+      headers: { "Content-Type": "application/json" },
+      method: "GET",
+      url: buildUrl(getBaseUrl(), path)
+    }),
+    graphqlQuery: (query, variables = {}) => sdk.network.request({
+      body: { query, variables },
+      headers: { "Content-Type": "application/json" },
+      method: "POST",
+      url: buildUrl(getBaseUrl(), "/graphql")
+    }),
+    patch: (path, body) => sdk.network.request({
+      body,
+      headers: { "Content-Type": "application/json" },
+      method: "PATCH",
+      url: buildUrl(getBaseUrl(), path)
+    }),
+    post: (path, body) => sdk.network.request({
+      body,
+      headers: { "Content-Type": "application/json" },
+      method: "POST",
+      url: buildUrl(getBaseUrl(), path)
+    }),
+    get wsUrl() {
+      return getWsUrl();
+    }
+  };
+}
+
 // src/index.ts
 var src_default = sdk;
 export {
@@ -4990,6 +5094,7 @@ export {
   SDKProvider,
   SwipeCarousel,
   UIEvent,
+  createApiService,
   src_default as default,
   handleClearRoute,
   handleDrawRoute,