@microsoft/power-apps-native-host 0.2.22

package/lib/module/ErrorBoundary.js

@@ -0,0 +1,122 @@
+"use strict";
+
+import React from 'react';
+import { ScrollView, StyleSheet, Text } from 'react-native';
+import { debugLog } from "./logger.js";
+import { getAppLogger, HostOperationNames } from "./telemetry/index.js";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * Top-level React error boundary.
+ *
+ * Catches any unhandled JS exception thrown during rendering / lifecycle and
+ * displays a diagnostic screen.  All error details are written to the native
+ * log via debugLog so diagnostics stay consistent with the host package logger.
+ *
+ * Place this component at the very root of the component tree so it captures
+ * failures in any screen.
+ *
+ * Exported from power-apps-native-host so it can be used in the template and
+ * in any custom app without duplicating the implementation.
+ */
+export class ErrorBoundary extends React.Component {
+  state = {
+    hasError: false,
+    error: null,
+    componentStack: null
+  };
+  static getDerivedStateFromError(error) {
+    return {
+      hasError: true,
+      error
+    };
+  }
+  componentDidCatch(error, info) {
+    this.setState({
+      componentStack: info.componentStack ?? null
+    });
+    debugLog('[PAHost][ErrorBoundary] Unhandled JS error:', error.message);
+    debugLog('[PAHost][ErrorBoundary] Error stack:', error.stack ?? '(no stack)');
+    debugLog('[PAHost][ErrorBoundary] Component stack:', info.componentStack ?? '(no component stack)');
+    getAppLogger().trackErrorEvent(HostOperationNames.RuntimeUnhandledJsError, {
+      errorName: error.constructor.name,
+      hasStack: Boolean(error.stack),
+      hasComponentStack: Boolean(info.componentStack)
+    });
+  }
+  render() {
+    if (!this.state.hasError) {
+      return this.props.children;
+    }
+    const {
+      error,
+      componentStack
+    } = this.state;
+    return /*#__PURE__*/_jsxs(ScrollView, {
+      contentContainerStyle: styles.container,
+      children: [/*#__PURE__*/_jsx(Text, {
+        style: styles.title,
+        children: "Something went wrong"
+      }), /*#__PURE__*/_jsxs(Text, {
+        style: styles.subtitle,
+        children: ["Check the native log for full details:", '\n', "adb logcat -s ReactNativeJS:V"]
+      }), /*#__PURE__*/_jsx(Text, {
+        style: styles.label,
+        children: "Error"
+      }), /*#__PURE__*/_jsx(Text, {
+        style: styles.mono,
+        children: error?.message ?? 'Unknown error'
+      }), error?.stack ? /*#__PURE__*/_jsxs(_Fragment, {
+        children: [/*#__PURE__*/_jsx(Text, {
+          style: styles.label,
+          children: "JS Stack"
+        }), /*#__PURE__*/_jsx(Text, {
+          style: styles.mono,
+          children: error.stack
+        })]
+      }) : null, componentStack ? /*#__PURE__*/_jsxs(_Fragment, {
+        children: [/*#__PURE__*/_jsx(Text, {
+          style: styles.label,
+          children: "Component Stack"
+        }), /*#__PURE__*/_jsx(Text, {
+          style: styles.mono,
+          children: componentStack
+        })]
+      }) : null]
+    });
+  }
+}
+const styles = StyleSheet.create({
+  container: {
+    flexGrow: 1,
+    padding: 20,
+    paddingTop: 60,
+    backgroundColor: '#1a1a1a'
+  },
+  title: {
+    fontSize: 22,
+    fontWeight: '700',
+    color: '#ff4d4d',
+    marginBottom: 8
+  },
+  subtitle: {
+    fontSize: 12,
+    color: '#888',
+    marginBottom: 20,
+    lineHeight: 18
+  },
+  label: {
+    fontSize: 11,
+    fontWeight: '600',
+    color: '#aaa',
+    marginTop: 16,
+    marginBottom: 4,
+    textTransform: 'uppercase',
+    letterSpacing: 0.8
+  },
+  mono: {
+    fontSize: 12,
+    color: '#e8e8e8',
+    fontFamily: 'monospace',
+    lineHeight: 18
+  }
+});

package/lib/module/auth/AuthContext.js

@@ -0,0 +1,276 @@
+"use strict";
+
+/*!
+ * power-apps-native-host — AuthContext
+ *
+ * A generic MSAL auth provider built on power-apps-native-auth's
+ * PublicClientApplication.  Provides AuthProvider, useAuth, and the
+ * AuthState / AuthProviderProps types.
+ *
+ * Usage in the consuming Expo app:
+ *
+ *   <AuthProvider msalConfig={authConfig.msal}>
+ *     <PowerAppsHostProvider acquireToken={acquireToken} ...>
+ *       {children}
+ *     </PowerAppsHostProvider>
+ *   </AuthProvider>
+ */
+
+import React, { createContext, useCallback, useContext, useEffect, useRef, useState } from 'react';
+import { Platform } from 'react-native';
+import { PublicClientApplication, registerAndEnrollAccount, deRegisterAndUnenrollAccount, computeMsalRedirectUri, getWrapConfig } from '@microsoft/power-apps-native-auth';
+import { getAppLogger, HostOperationNames } from "../telemetry/index.js";
+import { debugLog, debugWarn } from "../logger.js";
+
+// The Power Platform API (api.powerplatform.com) exposes its own scopes, not raw
+// OIDC scopes. Requesting 'openid'/'profile' alone causes AAD to decline.
+// '/.default' acquires a token covering all pre-consented permissions and
+// implicitly includes openid + profile + offline_access for the sign-in flow.
+import { jsx as _jsx } from "react/jsx-runtime";
+const SIGN_IN_SCOPES = ['https://api.powerplatform.com/.default'];
+function getSafeErrorName(error) {
+  return error instanceof Error ? error.constructor.name : typeof error;
+}
+const AuthContext = /*#__PURE__*/createContext(null);
+export function AuthProvider({
+  msalConfig,
+  intuneConfig,
+  children
+}) {
+  const [isAuthReady, setIsAuthReady] = useState(false);
+  const [isLoading, setIsLoading] = useState(true);
+  const [account, setAccount] = useState(null);
+  const [error, setError] = useState(null);
+
+  // useBroker, useEmbeddedWebView, and intune.enabled all default to !__DEV__ / __DEV__:
+  //   dev client  (__DEV__=true)  → broker off, embedded WebView on, MAM enrollment off
+  //   release build (__DEV__=false) → broker on, embedded WebView off, MAM enrollment on
+  // Callers can override via msalConfig.useBroker / msalConfig.useEmbeddedWebView / intuneConfig.enabled.
+  const useBroker = msalConfig.useBroker ?? !__DEV__;
+  const useEmbeddedWebView = msalConfig.useEmbeddedWebView ?? __DEV__;
+  const intuneEnabled = intuneConfig?.enabled ?? !__DEV__;
+
+  // In release builds, read clientId and tenantId from native platform sources
+  // patched by the production wrap pipeline (Android: string resources;
+  // iOS: Info.plist). Fall back to auth.config.json only when the native value
+  // is absent or is still the build-time placeholder (base package not yet
+  // wrapped).
+  const effectiveClientId = (() => {
+    if (__DEV__) return msalConfig.clientId;
+    try {
+      const {
+        clientId
+      } = getWrapConfig();
+      return clientId && !clientId.includes('_TAG') ? clientId : msalConfig.clientId;
+    } catch {
+      return msalConfig.clientId;
+    }
+  })();
+  const effectiveTenantId = (() => {
+    if (__DEV__) return msalConfig.tenantId;
+    try {
+      const {
+        tenantId
+      } = getWrapConfig();
+      return tenantId && !tenantId.includes('_TAG') ? tenantId : msalConfig.tenantId;
+    } catch {
+      return msalConfig.tenantId;
+    }
+  })();
+
+  // When broker is off (Android dev/embedded-WebView mode) the msauth:// redirect
+  // URI is not registered in AAD and will cause "multiple apps listening" errors
+  // because every dev client on the device claims the msauth.<package> intent
+  // filter. The nativeclient URI works for embedded-WebView sign-in and is
+  // registered for all AAD tenants.
+  //
+  // iOS MSAL rejects http(s) schemes for native flows (the "multiple apps
+  // listening" clash doesn't exist on iOS — msauth.<bundleId> is unique per
+  // bundle id), so iOS always uses computeMsalRedirectUri(). The dev-client
+  // consumer must register `msauth.<bundleId>://auth` in AAD and ensure the
+  // matching URL scheme is in CFBundleURLTypes (the production wrap pipeline
+  // injects it at release time).
+  //
+  // In release builds useBroker=true so all platforms compute the redirect
+  // URI natively from the app's own package name + signing cert.
+  const effectiveRedirectUri = !useBroker && Platform.OS === 'android' ? 'https://login.microsoftonline.com/common/oauth2/nativeclient' : computeMsalRedirectUri();
+
+  // No clientId → no-auth mode (e.g. dev-player before MSAL is configured).
+  // Skip MSAL entirely; treat the session as already signed in so the app
+  // renders without requiring credentials.
+  const noAuthMode = !effectiveClientId;
+  const pcaRef = useRef(null);
+  useEffect(() => {
+    if (noAuthMode) {
+      setIsAuthReady(true);
+      setIsLoading(false);
+      return;
+    }
+    const pca = new PublicClientApplication({
+      auth: {
+        clientId: effectiveClientId,
+        authority: `https://login.microsoftonline.com/${effectiveTenantId}`,
+        redirectUri: effectiveRedirectUri
+      },
+      useBroker,
+      ...(useEmbeddedWebView ? {
+        androidConfigOptions: {
+          authorization_user_agent: 'WEBVIEW'
+        }
+      } : {})
+    });
+    pcaRef.current = pca;
+    const authInitScenario = getAppLogger().trackScenario(HostOperationNames.AuthInit, {
+      useBroker,
+      platform: Platform.OS
+    });
+    pca.init().then(() => pca.getAccounts()).then(accounts => {
+      const restoredAccount = accounts[0] ?? null;
+      setAccount(restoredAccount);
+      if (restoredAccount) {
+        getAppLogger().identifyUser({
+          objectId: restoredAccount.identifier,
+          tenantId: restoredAccount.tenantId
+        });
+      }
+      setIsAuthReady(true);
+      setIsLoading(false);
+      authInitScenario.complete({
+        accountFound: accounts.length > 0
+      });
+    }).catch(e => {
+      debugLog('[AuthProvider] MSAL init failed:', e);
+      setError(e instanceof Error ? e : new Error(String(e)));
+      setIsAuthReady(true);
+      setIsLoading(false);
+      authInitScenario.fail(undefined, {
+        errorName: getSafeErrorName(e)
+      });
+    });
+    // Re-initialize only when the effective broker/identity settings change.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [effectiveClientId, effectiveTenantId, effectiveRedirectUri, useBroker]);
+  const signIn = useCallback(async () => {
+    const pca = pcaRef.current;
+    if (!pca) return;
+    setIsLoading(true);
+    setError(null);
+    const signInScenario = getAppLogger().trackScenario(HostOperationNames.AuthSignIn, {
+      useBroker
+    });
+    try {
+      // If init() failed on mount, retry it now before attempting sign-in.
+      if (!pca.isInitialized) {
+        await pca.init();
+      }
+      const result = await pca.acquireToken({
+        scopes: SIGN_IN_SCOPES
+      });
+      setAccount(result.account);
+      getAppLogger().identifyUser({
+        objectId: result.account.identifier,
+        tenantId: result.account.tenantId
+      });
+      // Register the signed-in account with Intune MAM so the SDK can apply
+      // app protection policies (PIN, wipe, copy-paste restriction, etc.).
+      // Only triggered in release builds (intuneEnabled=true by default).
+      // Skipped for the dev client (intuneEnabled=false by default).
+      if (intuneEnabled) {
+        try {
+          await registerAndEnrollAccount({
+            upn: result.account.username,
+            aadId: result.account.identifier,
+            tenantId: result.account.tenantId
+          });
+          getAppLogger().trackActivityEvent(HostOperationNames.AuthIntuneEnroll);
+        } catch (intuneErr) {
+          // Log but don't block the user — enrollment failures surface via
+          // Intune Conditional Access on the next token acquisition.
+          debugWarn('[AuthProvider] Intune enrollment failed:', intuneErr);
+          getAppLogger().trackErrorEvent(HostOperationNames.AuthIntuneEnroll, {
+            errorName: getSafeErrorName(intuneErr)
+          });
+        }
+      }
+      signInScenario.complete();
+    } catch (e) {
+      setError(e instanceof Error ? e : new Error(String(e)));
+      signInScenario.fail(undefined, {
+        errorName: getSafeErrorName(e)
+      });
+    } finally {
+      setIsLoading(false);
+    }
+  }, [intuneEnabled, useBroker]);
+  const acquireToken = useCallback(async scopes => {
+    const pca = pcaRef.current;
+    if (!pca || !account) return null;
+    try {
+      const result = await pca.acquireTokenSilent({
+        scopes,
+        account
+      });
+      return result.accessToken;
+    } catch (e) {
+      // Silent acquisition failed — do NOT fall back to interactive here.
+      // Interactive sign-in is handled exclusively by signIn(). Falling back
+      // to interactive from acquireToken triggers an unexpected login webview
+      // whenever a connector needs a token the cache doesn't hold yet.
+      debugWarn('[AuthContext] acquireTokenSilent failed for scopes:', scopes, e);
+      getAppLogger().trackErrorEvent(HostOperationNames.AuthAcquireTokenSilentFailed, {
+        scopeCount: scopes.length,
+        errorName: getSafeErrorName(e)
+      });
+      return null;
+    }
+  }, [account]);
+  const signOut = useCallback(async () => {
+    const pca = pcaRef.current;
+    if (!pca || !account) return;
+    setIsLoading(true);
+    const signOutScenario = getAppLogger().trackScenario(HostOperationNames.AuthSignOut);
+    try {
+      if (intuneEnabled) {
+        try {
+          await deRegisterAndUnenrollAccount(account.username);
+          getAppLogger().trackActivityEvent(HostOperationNames.AuthIntuneUnenroll);
+        } catch (intuneErr) {
+          debugWarn('[AuthProvider] Intune unenroll failed:', intuneErr);
+          getAppLogger().trackErrorEvent(HostOperationNames.AuthIntuneUnenroll, {
+            errorName: getSafeErrorName(intuneErr)
+          });
+        }
+      }
+      await pca.signOut({
+        account
+      });
+      setAccount(null);
+      signOutScenario.complete();
+    } finally {
+      setIsLoading(false);
+    }
+  }, [account, intuneEnabled]);
+  return /*#__PURE__*/_jsx(AuthContext.Provider, {
+    value: {
+      isLoading,
+      isAuthReady,
+      isSignedIn: noAuthMode || account !== null,
+      hasRealAccount: account !== null,
+      error,
+      acquireToken,
+      signIn,
+      signOut
+    },
+    children: children
+  });
+}
+
+/**
+ * Returns the current auth state from the nearest <AuthProvider>.
+ * Must be called within the AuthProvider tree.
+ */
+export function useAuth() {
+  const ctx = useContext(AuthContext);
+  if (!ctx) throw new Error('useAuth must be used within <AuthProvider>');
+  return ctx;
+}

package/lib/module/bridge/NativePowerAppsBridge.js

@@ -0,0 +1,273 @@
+"use strict";
+
+/*!
+ * power-apps-native-host — NativePowerAppsBridge
+ *
+ * A PowerAppsBridge implementation for React Native that handles all plugin
+ * calls in-process: auth tokens are supplied by the host app via callbacks,
+ * and HTTP is performed with the global `fetch` (built into RN 0.60+).
+ *
+ * This file mirrors the bridge in the SDK but lives here so the package can
+ * be used without patching the published @microsoft/power-apps tarball.
+ */
+
+import { debugLog, debugWarn } from "../logger.js";
+import { getAppLogger, HostOperationNames } from "../telemetry/index.js";
+import { sanitizeUrl } from '@microsoft/power-apps-native-common';
+function getSafeErrorName(error) {
+  return error instanceof Error ? error.constructor.name : typeof error;
+}
+
+/**
+ * Per-connection-reference data keyed by data source name
+ * (e.g. "commondataserviceforapps", "office365users").
+ * Returned to the SDK for AppPowerAppsClientPlugin.loadAppConnectionsAsync_v2
+ * and AppPowerAppsClientPlugin.loadNonCompositeConnectionsAsync.
+ */
+
+/** @deprecated Use AppConnectionReference */
+
+/**
+ * Build a connection-references map (keyed by data source name) from the
+ * `connectionReferences` section of power.config.json.
+ *
+ * Each entry from power.config.json looks like:
+ *   { id: "/providers/Microsoft.PowerApps/apis/shared_XXX", dataSources: ["XXX"], ... }
+ *
+ * The resulting map shape is what the SDK expects for loadAppConnectionsAsync_v2:
+ *   { XXX: { apiId, runtimeUrl, connectionName, datasetName } }
+ *
+ * `runtimeUrl` and `connectionName` default to empty strings — they must be
+ * populated at runtime from the Power Platform connections API for the SDK to
+ * make actual connector API calls.
+ *
+ * @param powerConfigConnectionReferences - The `connectionReferences` object
+ *   from power.config.json.
+ */
+export function buildConnectionReferences(powerConfigConnectionReferences) {
+  const result = {};
+  for (const ref of Object.values(powerConfigConnectionReferences)) {
+    const entry = {
+      apiId: ref.id,
+      runtimeUrl: '',
+      connectionName: '',
+      datasetName: ''
+    };
+    for (const dsName of ref.dataSources) {
+      result[dsName] = entry;
+    }
+  }
+  return result;
+}
+/**
+ * The Power Apps web SDK annotates HTTP requests with internal auth schemes:
+ *   - `paauth <token>`    — connector/APIM calls
+ *   - `dynamicauth <token>` — Dataverse OData calls
+ *
+ * Both are gateway-internal protocols. Native endpoints require the standard
+ * `Bearer` scheme, so rewrite either prefix before the request is sent.
+ */
+function rewriteAuthHeaders(headers) {
+  if (!headers) return headers;
+  const auth = headers['Authorization'] ?? headers['authorization'];
+  if (auth?.startsWith('paauth ')) {
+    return {
+      ...headers,
+      Authorization: `Bearer ${auth.slice('paauth '.length)}`
+    };
+  }
+  if (auth?.startsWith('dynamicauth ')) {
+    return {
+      ...headers,
+      Authorization: `Bearer ${auth.slice('dynamicauth '.length)}`
+    };
+  }
+  return headers;
+}
+function normalizeJsonBodyHeaders(headers, body) {
+  const hasContentType = Object.keys(headers ?? {}).some(key => key.toLowerCase() === 'content-type');
+  const isJsonBody = typeof body === 'string' && /^[\s]*[\[{]/.test(body);
+  if (!isJsonBody || hasContentType) {
+    return headers;
+  }
+  return {
+    ...headers,
+    'Content-Type': 'application/json'
+  };
+}
+function arrayBufferViewToArrayBuffer(view) {
+  const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+  const copy = new Uint8Array(bytes.byteLength);
+  copy.set(bytes);
+  return copy.buffer;
+}
+export class NativePowerAppsBridge {
+  constructor(_options) {
+    this._options = _options;
+  }
+
+  /**
+   * Updates the bridge's options in-place.
+   *
+   * Call this when connection references or data sources change (e.g. after
+   * a new connection is created) without recreating the bridge. The SDK caches
+   * the bridge instance after the first data operation, so replacing the bridge
+   * via globalThis would have no effect — mutating options is the correct path.
+   */
+  updateOptions(options) {
+    this._options = options;
+  }
+  async initialize() {
+    // No handshake required for the native path.
+  }
+
+  /**
+   * Hermes-safe body construction. Returns the raw body value so that
+   * _sendHttpAsync can pass it directly to fetch without any Blob wrapping.
+   *
+   * The web-player's RuntimeDataClient wraps all bodies in `new Blob([...])`,
+   * which Hermes does not support for ArrayBuffer / TypedArray inputs.
+   * Implementing this hook on the bridge bypasses that wrapping entirely.
+   */
+  createRequestBody(config) {
+    const body = config.body;
+    if (ArrayBuffer.isView(body)) {
+      return arrayBufferViewToArrayBuffer(body);
+    }
+    return body ?? '';
+  }
+  async executePluginAsync(pluginName, pluginAction, params) {
+    const key = `${pluginName}.${pluginAction}`;
+    // Only log in dev-player — silenced in release APK builds.
+    debugLog(`[bridge] executePluginAsync: "${key}"`);
+    getAppLogger().trackVerboseEvent(HostOperationNames.BridgeUnhandledPlugin, {
+      pluginKey: key
+    });
+    switch (key) {
+      case 'AppIdentityServicePlugin.getAppAccessTokenAsync':
+        return this._options.getConnectorToken(params[0]);
+      case 'AppIdentityServicePlugin.getAppDynamicResourceAccessTokenAsync':
+        return this._options.getDataverseToken(params[0]);
+      case 'AppHttpClientPlugin.sendHttpAsync':
+        return this._sendHttpAsync(params);
+      case 'AppPowerAppsClientPlugin.getAppCdsDataSourceConfigsAsync':
+        return this._options.dataSources;
+      case 'AppPowerAppsClientPlugin.loadAppConnectionsAsync_v2':
+        return this._options.connections;
+
+      // Newer SDK versions split connection loading into two phases:
+      // loadNonCompositeConnectionsAsync (individual connections) and
+      // resolveCompositeConnectionsAsync (aggregated/composite connections).
+      // The return values are not used by the SDK caller (loadConnections())
+      // so we return the connections for the first phase and null for the second.
+      case 'AppPowerAppsClientPlugin.loadNonCompositeConnectionsAsync':
+        return this._options.connections;
+      case 'AppPowerAppsClientPlugin.resolveCompositeConnectionsAsync':
+        return null;
+
+      // Telemetry calls from the SDK are fire-and-forget — silently no-op them.
+      // The SDK reports these failures separately, which is noisy but safe.
+      case 'PublishedAppTelemetry.trackEvent':
+      case 'PublishedAppTelemetry.trackException':
+      case 'PublishedAppTelemetry.trackMetric':
+      case 'PublishedAppTelemetry.startScenario':
+      case 'PublishedAppTelemetry.endScenario':
+      case 'PublishedAppTelemetry.setDefaultProperties':
+        return undefined;
+      default:
+        // Warn instead of throw so unknown calls don't crash the app.
+        // Log the key only — params may contain auth tokens.
+        debugWarn(`[bridge] unhandled plugin call "${key}"`);
+        getAppLogger().trackErrorEvent(HostOperationNames.BridgeUnhandledPlugin, {
+          pluginKey: key
+        });
+        return undefined;
+    }
+  }
+
+  /**
+   * Calls fetch and returns the result in the exact shape expected by
+   * RuntimeDataClient._executeRequest:
+   *   [{ status: number; headers: Record<string, string> }, ArrayBuffer]
+   */
+  async _sendHttpAsync(params) {
+    const requestConfig = params[0];
+    const bodyParam = params[1];
+    const {
+      url,
+      method
+    } = requestConfig;
+    const urlLabel = sanitizeUrl(url.replace(/^https?:\/\/[^/]+/, '').slice(0, 100));
+    const scenario = getAppLogger().trackScenario(HostOperationNames.BridgeHttpRequest, {
+      httpMethod: method,
+      url: urlLabel
+    });
+    const isBlob = bodyParam instanceof Blob;
+
+    // The SDK builds Authorization headers with the "paauth" scheme (its web-player
+    // convention). Native endpoints (APIM token exchange, connector runtime) expect
+    // standard "Bearer" tokens, so rewrite the scheme here before sending.
+    let headers = rewriteAuthHeaders(requestConfig.headers);
+    let bodyInit = null;
+    if (isBlob && bodyParam.size > 0) {
+      // The RN Blob polyfill does not implement arrayBuffer()/text() but RN's
+      // native fetch handles its own Blob type directly via internal blobId.
+      // Pass the Blob straight through — no conversion needed.
+      bodyInit = bodyParam;
+    } else if (typeof bodyParam === 'string' && bodyParam.length > 0) {
+      bodyInit = bodyParam;
+    } else if (bodyParam instanceof ArrayBuffer) {
+      bodyInit = bodyParam;
+    } else if (ArrayBuffer.isView(bodyParam)) {
+      // Binary buffer (e.g. file upload) — RN fetch is most reliable when the
+      // body is a standalone ArrayBuffer rather than a TypedArray view.
+      bodyInit = arrayBufferViewToArrayBuffer(bodyParam);
+    } else if (!isBlob && typeof bodyParam === 'object' && bodyParam !== null) {
+      // SDK passed a plain object — JSON-stringify it as a fallback
+      bodyInit = JSON.stringify(bodyParam);
+    }
+    headers = normalizeJsonBodyHeaders(headers, bodyInit);
+    debugLog(`[bridge] → ${method} ${urlLabel}`);
+    let response;
+    try {
+      response = await fetch(url, {
+        method,
+        headers: headers,
+        body: bodyInit
+      });
+    } catch (fetchErr) {
+      debugWarn(`[bridge] fetch THREW for ${method} ${urlLabel}:`, fetchErr);
+      debugLog(`[bridge] fetch THREW for ${method} ${urlLabel} | req body: ${typeof bodyInit === 'string' ? bodyInit.slice(0, 500) : bodyInit != null ? '<non-string body>' : '<no body>'}`);
+      scenario.fail(undefined, {
+        errorName: getSafeErrorName(fetchErr)
+      });
+      throw fetchErr;
+    }
+    const responseHeaders = {};
+    response.headers.forEach((value, key) => {
+      // fetch() normalises all header names to lowercase, but the SDK reads
+      // 'Content-Type' with title-case to decide how to parse the body.
+      // Map it back so the SDK doesn't see `undefined` and silently return no data.
+      const sdkKey = key === 'content-type' ? 'Content-Type' : key;
+      responseHeaders[sdkKey] = value;
+    });
+    const buffer = await response.arrayBuffer();
+    debugLog(`[bridge] ${method} ${urlLabel} → ${response.status}`);
+    if (!response.ok) {
+      const bodyText = new TextDecoder().decode(buffer).slice(0, 1000);
+      debugWarn(`[bridge] HTTP ${response.status} for ${method} ${urlLabel} | res: ${bodyText}`);
+      debugLog(`[bridge] HTTP ${response.status} for ${method} ${urlLabel} | req: ${typeof bodyInit === 'string' ? bodyInit.slice(0, 500) : bodyInit != null ? '<non-string body>' : '<no body>'} | res: ${bodyText}`);
+      scenario.completeWithError({
+        httpStatus: response.status
+      });
+    } else {
+      scenario.complete({
+        httpStatus: response.status
+      });
+    }
+    return [{
+      status: response.status,
+      headers: responseHeaders
+    }, buffer];
+  }
+}