@microsoft/power-apps-native-host 0.2.25 → 0.3.3

package/lib/module/connections/useConnectionSetup.js

@@ -20,10 +20,12 @@
  *   // Call setup.checkNow() to re-poll after WebView finishes
  */
 
-import { useState, useCallback, useRef } from 'react';
-import { createConnection, pollConnectionStatus, confirmConsentCode, addAadAppToConnectionAcl, parseJwtOid, SERVICE_POWERAPPS_SCOPE } from "../platform/PowerPlatformConnectionApi.js";
-import { powerPlatformScope } from "../platform/PowerPlatformEnvironmentApi.js";
+import { useState, useCallback, useEffect, useRef } from 'react';
+import { createConnection, repairConnection, pollConnectionStatus, confirmConsentCode, grantConnectionUserConsent } from "./PowerPlatformConnectionApi.js";
+import { connectionUserConsentScope, powerPlatformScope } from "../platform/PowerPlatformEnvironmentApi.js";
 import { extractConnectionId } from "../connections/disambiguate.js";
+import { shouldGrantConnectionUserConsent } from "./connectionState.js";
+import { isDevPlayer } from "../utils/isDevPlayer.js";
 import { debugWarn } from "../logger.js";
 import { getAppLogger, HostOperationNames } from "../telemetry/index.js";
 
@@ -52,7 +54,7 @@ export function useConnectionSetup({
   region = 'prod',
   acquireToken,
   onConnected,
-  isvClientId,
+  sharedConnectionId,
   oauthRedirectUrl,
   polling
 }) {
@@ -64,44 +66,53 @@ export function useConnectionSetup({
   const connectionNameRef = useRef(null);
   // Prevent concurrent startCreate / checkNow calls.
   const inFlightRef = useRef(false);
+  const operationRef = useRef(null);
+  const beginOperation = useCallback(() => {
+    operationRef.current?.abort();
+    const controller = new AbortController();
+    operationRef.current = controller;
+    return controller;
+  }, []);
+  useEffect(() => () => operationRef.current?.abort(), []);
   const handleConnected = useCallback(async instance => {
     setPhase('connected');
     setConsentUrl(null);
+    if (!shouldGrantConnectionUserConsent({
+      sharedConnectionId
+    }, isDevPlayer)) {
+      onConnected?.(instance);
+      return;
+    }
 
-    // The RP auto-writes the user as Owner when a connection is created.
-    // However, APIM also checks that the requesting appid is present in the
-    // ACE's AppIds list. For third-party ISV tokens this is never populated
-    // automatically — we must explicitly add the ISV's client ID to the
-    // connection ACL so that APIM accepts tokens bearing that appid at runtime.
-    if (isvClientId) {
-      const paToken = await acquireToken([SERVICE_POWERAPPS_SCOPE]);
-      const userOid = paToken ? parseJwtOid(paToken) : null;
-      if (!paToken || !userOid) {
-        setPhase('error');
-        setErrorMessage('Connection was created, but access could not be granted to this app. Please try again.');
-        debugWarn('[useConnectionSetup] could not grant connection ACL: missing Power Apps token or user OID');
-        getAppLogger().trackErrorEvent(HostOperationNames.PlatformConnectionAclGrant, {
-          phase: 'setupConnectionAcl',
-          reason: !paToken ? 'missingPowerAppsToken' : 'missingUserOid'
-        });
-        return;
-      }
-      const aclGranted = await addAadAppToConnectionAcl(connectorId, instance.id, environmentId, isvClientId, userOid, paToken);
-      if (!aclGranted) {
-        setPhase('error');
-        setErrorMessage('Connection was created, but access could not be granted to this app. Please try again.');
-        getAppLogger().trackErrorEvent(HostOperationNames.PlatformConnectionAclGrant, {
-          phase: 'setupConnectionAcl',
-          reason: 'aclGrantRejected'
-        });
-        return;
-      }
+    // APIM checks the requesting appid against the user's effective ACL.
+    // User consent lets RP select the applicable direct, group, or tenant ACL.
+    const consentToken = await acquireToken([connectionUserConsentScope(region)]);
+    if (!consentToken) {
+      setPhase('error');
+      setErrorMessage('Connection was created, but access could not be granted to this app. Please try again.');
+      debugWarn('[useConnectionSetup] could not grant connection consent: missing Power Platform token');
+      getAppLogger().trackErrorEvent(HostOperationNames.PlatformConnectionAclGrant, {
+        phase: 'setupConnectionAcl',
+        reason: 'missingPowerPlatformToken'
+      });
+      return;
+    }
+    const aclGranted = await grantConnectionUserConsent(connectorId, instance.id, environmentId, region, consentToken);
+    if (!aclGranted) {
+      setPhase('error');
+      setErrorMessage('Connection was created, but access could not be granted to this app. Please try again.');
+      getAppLogger().trackErrorEvent(HostOperationNames.PlatformConnectionAclGrant, {
+        phase: 'setupConnectionAcl',
+        reason: 'aclGrantRejected'
+      });
+      return;
     }
     onConnected?.(instance);
-  }, [onConnected, acquireToken, connectorId, environmentId, isvClientId]);
-  const startCreate = useCallback(async () => {
+  }, [onConnected, acquireToken, connectorId, environmentId, region, sharedConnectionId]);
+  const startCreate = useCallback(async input => {
     if (inFlightRef.current) return;
     inFlightRef.current = true;
+    const operation = beginOperation();
     setPhase('creating');
     setErrorMessage(null);
     setConsentUrl(null);
@@ -113,7 +124,7 @@ export function useConnectionSetup({
         setErrorMessage('Failed to acquire authentication token');
         return;
       }
-      const result = await createConnection(connectorId, environmentId, region, token, undefined, oauthRedirectUrl);
+      const result = await createConnection(connectorId, environmentId, region, token, undefined, oauthRedirectUrl, input);
       if (result.status === 'error') {
         setPhase('error');
         setErrorMessage(result.message);
@@ -124,10 +135,11 @@ export function useConnectionSetup({
         // Connection is already Connected — poll once to get the full instance.
         const instance = await pollConnectionStatus(connectorId, result.connectionName, environmentId, region, acquireToken, {
           timeoutMs: 10_000,
-          ...polling
+          ...polling,
+          signal: operation.signal
         });
         if (instance) {
-          handleConnected(instance);
+          await handleConnected(instance);
         } else {
           // Already created but not Connected yet — treat as oauth phase without a URL.
           setPhase('oauth');
@@ -138,36 +150,77 @@ export function useConnectionSetup({
       // status === 'pending': show the OAuth URL in a WebView.
       setConsentUrl(result.consentLink);
       setPhase('oauth');
-
-      // Start background polling immediately — the user may finish OAuth quickly.
-      const instance = await pollConnectionStatus(connectorId, result.connectionName, environmentId, region, acquireToken, polling);
-
-      // If the phase changed while we were polling (e.g., user dismissed WebView
-      // and checkNow already resolved it), don't override.
-      if (instance && phase !== 'connected') {
-        handleConnected(instance);
-      } else if (!instance && phase !== 'connected') {
+    } finally {
+      inFlightRef.current = false;
+    }
+  }, [connectorId, environmentId, region, acquireToken, polling, handleConnected, beginOperation]);
+  const startRepair = useCallback(async (instance, input, requiresApiConsent = true) => {
+    if (inFlightRef.current) return;
+    inFlightRef.current = true;
+    const operation = beginOperation();
+    setPhase('creating');
+    setErrorMessage(null);
+    setConsentUrl(null);
+    connectionNameRef.current = instance.name;
+    try {
+      const token = await acquireToken([powerPlatformScope(region)]);
+      if (!token) {
+        setPhase('error');
+        setErrorMessage('Failed to acquire authentication token');
+        return;
+      }
+      const result = await repairConnection(connectorId, instance.name, environmentId, region, token, oauthRedirectUrl, input, requiresApiConsent);
+      if (result.status === 'error') {
         setPhase('error');
-        setErrorMessage('Connection setup timed out. Please try again.');
+        setErrorMessage(result.message);
+        return;
+      }
+      connectionNameRef.current = result.connectionName;
+      if (result.status === 'pending') {
+        setConsentUrl(result.consentLink);
+        setPhase('oauth');
+      } else {
+        const repaired = await pollConnectionStatus(connectorId, result.connectionName, environmentId, region, acquireToken, {
+          timeoutMs: 10_000,
+          ...polling,
+          signal: operation.signal
+        });
+        if (repaired) await handleConnected(repaired);else {
+          setPhase('error');
+          setErrorMessage('The connection was updated but did not become active.');
+        }
       }
     } finally {
       inFlightRef.current = false;
     }
-  }, [connectorId, environmentId, region, acquireToken, polling, handleConnected, phase]);
+  }, [acquireToken, beginOperation, connectorId, environmentId, handleConnected, oauthRedirectUrl, polling, region]);
+  const useExisting = useCallback(async instance => {
+    if (inFlightRef.current) return;
+    inFlightRef.current = true;
+    setPhase('confirming');
+    setErrorMessage(null);
+    try {
+      await handleConnected(instance);
+    } finally {
+      inFlightRef.current = false;
+    }
+  }, [handleConnected]);
   const checkNow = useCallback(async () => {
     const name = connectionNameRef.current;
     if (!name || inFlightRef.current) return;
     if (phase !== 'oauth' && phase !== 'confirming') return;
     inFlightRef.current = true;
+    const operation = beginOperation();
     setPhase('confirming');
     try {
       const instance = await pollConnectionStatus(connectorId, name, environmentId, region, acquireToken, {
         intervalMs: 1000,
         timeoutMs: 30_000,
-        ...polling
+        ...polling,
+        signal: operation.signal
       });
       if (instance) {
-        handleConnected(instance);
+        await handleConnected(instance);
       } else {
         // Not yet connected — go back to oauth so the user can retry.
         setPhase('oauth');
@@ -176,8 +229,10 @@ export function useConnectionSetup({
     } finally {
       inFlightRef.current = false;
     }
-  }, [phase, environmentId, region, acquireToken, polling, handleConnected]);
+  }, [phase, connectorId, environmentId, region, acquireToken, polling, handleConnected, beginOperation]);
   const reset = useCallback(() => {
+    operationRef.current?.abort();
+    operationRef.current = null;
     inFlightRef.current = false;
     connectionNameRef.current = null;
     setPhase('idle');
@@ -197,6 +252,7 @@ export function useConnectionSetup({
     const name = connectionNameRef.current;
     if (!name || inFlightRef.current) return;
     inFlightRef.current = true;
+    const operation = beginOperation();
     setPhase('confirming');
     try {
       if (code) {
@@ -209,10 +265,11 @@ export function useConnectionSetup({
       const instance = await pollConnectionStatus(connectorId, name, environmentId, region, acquireToken, {
         intervalMs: 1000,
         timeoutMs: 30_000,
-        ...polling
+        ...polling,
+        signal: operation.signal
       });
       if (instance) {
-        handleConnected(instance);
+        await handleConnected(instance);
       } else {
         setPhase('oauth');
         setErrorMessage('Connection is not yet active. Complete the sign-in and try again.');
@@ -220,12 +277,14 @@ export function useConnectionSetup({
     } finally {
       inFlightRef.current = false;
     }
-  }, [connectorId, environmentId, region, acquireToken, polling, handleConnected]);
+  }, [connectorId, environmentId, region, acquireToken, polling, handleConnected, beginOperation]);
   return {
     phase,
     consentUrl,
     errorMessage,
     startCreate,
+    startRepair,
+    useExisting,
     checkNow,
     completeConsent,
     reset

package/lib/module/controls/FilePicker.js

@@ -19,6 +19,9 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 export function FilePicker({
   label,
+  testID,
+  fileRowTestID,
+  pickButtonTestID,
   fileName,
   onDownload,
   shareTitle,
@@ -85,6 +88,7 @@ export function FilePicker({
     }
   };
   return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
     style: [styles.container, containerStyle],
     children: [label ? /*#__PURE__*/_jsx(Text, {
       style: [styles.label, {
@@ -92,6 +96,7 @@ export function FilePicker({
       }, labelStyle],
       children: label
     }) : null, displayName ? /*#__PURE__*/_jsxs(TouchableOpacity, {
+      testID: fileRowTestID,
       style: [styles.fileRow, fileRowStyle],
       onPress: onDownload ? download : undefined,
       activeOpacity: onDownload ? 0.7 : 1,
@@ -115,6 +120,7 @@ export function FilePicker({
         color: accent
       }))]
     }) : null, onChange ? /*#__PURE__*/_jsxs(TouchableOpacity, {
+      testID: pickButtonTestID,
       style: [styles.button, {
         borderColor: accent,
         backgroundColor: bg

package/lib/module/controls/ImagePicker.js

@@ -17,6 +17,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 export function ImagePicker({
   label = 'Image',
+  testID,
+  cameraButtonTestID,
+  selectButtonTestID,
+  previewTestID,
   initialBase64,
   onChange,
   containerStyle,
@@ -131,6 +135,7 @@ export function ImagePicker({
     }
   };
   return /*#__PURE__*/_jsxs(View, {
+    testID: testID,
     style: [styles.container, containerStyle],
     children: [label ? /*#__PURE__*/_jsx(Text, {
       style: [styles.label, {
@@ -140,6 +145,7 @@ export function ImagePicker({
     }) : null, /*#__PURE__*/_jsxs(View, {
       style: [styles.buttonRow, buttonRowStyle],
       children: [/*#__PURE__*/_jsxs(TouchableOpacity, {
+        testID: cameraButtonTestID,
         style: [styles.button, {
           borderColor: accentColor_resolved,
           backgroundColor: bg
@@ -161,6 +167,7 @@ export function ImagePicker({
           children: reading ? readingLabel : cameraButtonLabel
         })]
       }), /*#__PURE__*/_jsxs(TouchableOpacity, {
+        testID: selectButtonTestID,
         style: [styles.button, {
           borderColor: accentColor_resolved,
           backgroundColor: bg
@@ -183,6 +190,7 @@ export function ImagePicker({
         })]
       })]
     }), previewUri ? /*#__PURE__*/_jsx(Image, {
+      testID: previewTestID,
       source: {
         uri: previewUri
       },

package/lib/module/index.js

@@ -6,20 +6,30 @@
  * 
  */
 
+// Side-effect: installs the wrap-injected customer asset resolver before any
+// screen renders. No-op on web/dev and in any base app without the native
+// module, so importing the package root is always safe.
+import '@microsoft/power-apps-native-assets';
 export { NativePowerAppsBridge } from "./bridge/NativePowerAppsBridge.js";
 export { PowerPagesBridge, setupPowerPagesHost } from "./bridge/PowerPagesBridge.js";
 export { buildConnectionReferences } from "./bridge/NativePowerAppsBridge.js";
 export { setupNativeHost } from "./bridge/setupNativeHost.js";
+export { updateBridgeOptionsInPlace } from "./bridge/bridgeState.js";
 export { AuthProvider, useAuth } from './auth/AuthContext';
 export { completePowerAppsAuthSession } from "./auth/completePowerAppsAuthSession.js";
 export { PowerAppsHostProvider } from './provider/PowerAppsHostProvider';
 export { PowerAppsProvider } from "./provider/PowerAppsProvider.js";
-export { fetchInstanceUrl, buildCdsDataSources, buildEnvironmentEndpoint, POWER_PLATFORM_API_SCOPE } from "./platform/PowerPlatformEnvironmentApi.js";
-export { useConnectionRefs } from "./platform/useConnectionRefs.js";
+export { buildEnvironmentEndpoint, POWER_PLATFORM_API_SCOPE } from "./platform/PowerPlatformEnvironmentApi.js";
+export { fetchInstanceUrl } from "./platform/DataverseGlobalDiscoveryApi.js";
+export { buildCdsDataSources } from "./platform/DataverseDataSources.js";
+export { useConnectionRefs } from "./connections/useConnectionRefs.js";
 // Connection creation & OAuth flow
-export { fetchConnectorMetadata, fetchConnectionsForConnector, createConnection, pollConnectionStatus, confirmConsentCode, fetchAppLaunchData } from "./platform/PowerPlatformConnectionApi.js";
+export { fetchConnectorMetadata, fetchConnectionsForConnector, deleteConnection, createConnection, pollConnectionStatus, confirmConsentCode, repairConnection, fetchAppLaunchData, fetchAppConnectionUsages, postConnectionUsage, reportScopeConsents } from "./connections/PowerPlatformConnectionApi.js";
 // Connection disambiguation
 export { disambiguateConnections, extractConnectionId } from "./connections/disambiguate.js";
+export { shouldPersistConnectionUsages, shouldShowConnectionReview } from "./connections/connectionState.js";
+export { buildConnectionRequirements, buildConnectionResolutionKey, findConnectionDataSourceConflicts, hasCompleteStaticConnectionConfig, isCompositeConnectionApiId, getConnectorId, normalizeApiId } from "./connections/types.js";
+export { buildConnectionUserConsentUrl, buildConsentLinkDefinition, buildConnectionParameterSets, buildConnectionUsageRequest, buildConnectionUsageUrl, buildScopeConsentRequest, buildScopeConsentUrl, hasOAuthParameter, parseConnectionParameters, serializeConnectionParameters } from "./connections/connectionMetadata.js";
 // Connection setup hook
 export { useConnectionSetup } from "./connections/useConnectionSetup.js";
 // Ready-made connection setup screen
@@ -38,6 +48,6 @@ export { isDevPlayer } from "./utils/isDevPlayer.js";
 export { base64ToDataverseUploadFile, base64ToUint8Array, createDataverseUploadFile } from "./utils/dataverseUtils.js";
 
 // ── Telemetry ─────────────────────────────────────────────────────────────────
-export { getAppLogger, configureAppLogger, HostOperationNames } from "./telemetry/index.js";
+export { getAppLogger, configureAppLogger, getCustomerTelemetryLogger, HostOperationNames } from "./telemetry/index.js";
 // ── Error boundary ────────────────────────────────────────────────────────────
 export { ErrorBoundary } from "./ErrorBoundary.js";

package/lib/module/logger.js

@@ -3,20 +3,22 @@
 /**
  * Conditional debug logger for power-apps-native-host.
  *
- * Debug logs (debugLog / debugWarn) are only emitted when the JS bundle
- * is running inside the Power Apps Dev Player (detected via
- * `Constants.expoConfig.extra.isDevPlayer`).  They are silenced in release
- * APKs generated from the template so the production log stream stays clean.
+ * Debug logs (debugLog / debugWarn) are emitted in development bundles or when
+ * running inside Power Apps Dev Player. They remain silent in wrapped release
+ * apps so the production log stream stays clean.
  */
 
 import { isDevPlayer } from "./utils/isDevPlayer.js";
+export function isDebugLoggingEnabled() {
+  return __DEV__ || isDevPlayer;
+}
 export function debugLog(...args) {
-  if (isDevPlayer) {
+  if (isDebugLoggingEnabled()) {
     console.log(...args);
   }
 }
 export function debugWarn(...args) {
-  if (isDevPlayer) {
+  if (isDebugLoggingEnabled()) {
     console.warn(...args);
   }
 }

package/lib/module/offline/createOfflineHostActivationCallbacks.js

@@ -0,0 +1,55 @@
+"use strict";
+
+import { QueryClient } from '@tanstack/react-query';
+function setNetworkMode(queryClient, networkMode) {
+  const current = queryClient.getDefaultOptions();
+  queryClient.setDefaultOptions({
+    ...current,
+    queries: {
+      ...current.queries,
+      staleTime: 60_000,
+      retry: 2,
+      networkMode
+    },
+    mutations: {
+      ...current.mutations,
+      retry: 0,
+      networkMode
+    }
+  });
+}
+export function createHostQueryClient() {
+  return new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60_000,
+        retry: 2
+      },
+      mutations: {
+        retry: 0
+      }
+    }
+  });
+}
+export function createOfflineHostActivationCallbacks(queryClient) {
+  return {
+    prepareForOfflineActivation: () => queryClient.cancelQueries(),
+    completeOfflineActivation: async () => {
+      setNetworkMode(queryClient, 'always');
+      await queryClient.invalidateQueries();
+    },
+    rollbackOfflineActivation: async () => {
+      setNetworkMode(queryClient, undefined);
+      await queryClient.invalidateQueries();
+    }
+  };
+}
+export function resolveSdkMountDecision(value) {
+  return typeof value === 'boolean' ? {
+    shouldMountChildren: value,
+    contractSupported: true
+  } : {
+    shouldMountChildren: true,
+    contractSupported: false
+  };
+}

package/lib/module/offline/useOfflineIntegrationWithStartupGate.js

@@ -0,0 +1,44 @@
+"use strict";
+
+import { useCallback, useEffect, useMemo } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+import { getAppLogger } from '@microsoft/power-apps-native-common';
+import { fetchInstanceUrl } from "../platform/DataverseGlobalDiscoveryApi.js";
+import { hasDataverseDatabaseReferences } from "../platform/DataverseDataSources.js";
+import { HostOperationNames } from "../telemetry/index.js";
+import { createOfflineHostActivationCallbacks, resolveSdkMountDecision } from "./createOfflineHostActivationCallbacks.js";
+import { useOfflineIntegration } from './useOfflineIntegration';
+export function useOfflineIntegrationWithStartupGate({
+  powerConfig,
+  offlineProfile,
+  acquireToken,
+  hasRealAccount,
+  isAuthReady
+}) {
+  const queryClient = useQueryClient();
+  const hasDataverse = hasDataverseDatabaseReferences(powerConfig.databaseReferences);
+  const resolveInstanceUrl = useCallback(async (environmentId, region, acqToken) => hasDataverse ? (await fetchInstanceUrl(environmentId, region, acqToken)) ?? null : null, [hasDataverse]);
+  const hostActivationCallbacks = useMemo(() => createOfflineHostActivationCallbacks(queryClient), [queryClient]);
+  const offline = useOfflineIntegration({
+    powerConfig,
+    offlineProfile,
+    acquireToken,
+    isSignedIn: hasRealAccount,
+    authState: isAuthReady ? hasRealAccount ? 'authenticated' : 'signed-out' : 'hydrating',
+    fetchInstanceUrl: resolveInstanceUrl,
+    hostActivationCallbacks
+  });
+  const mountDecision = resolveSdkMountDecision(offline.shouldMountChildren);
+  useEffect(() => {
+    if (!mountDecision.contractSupported) {
+      getAppLogger().trackErrorEvent(HostOperationNames.OfflineRoutingContractUnsupported, {
+        fallbackRoute: 'online'
+      });
+    }
+  }, [mountDecision.contractSupported]);
+  return {
+    isEnabled: offline.isEnabled,
+    StatusOverlay: offline.StatusOverlay,
+    shouldMountChildren: mountDecision.shouldMountChildren
+  };
+}

package/lib/module/offline/useOfflineIntegrationWithStartupGate.web.js

@@ -0,0 +1,9 @@
+"use strict";
+
+export function useOfflineIntegrationWithStartupGate(_options) {
+  return {
+    isEnabled: false,
+    StatusOverlay: null,
+    shouldMountChildren: true
+  };
+}

package/lib/module/platform/DataverseDataSources.js

@@ -0,0 +1,13 @@
+"use strict";
+
+export function hasDataverseDatabaseReferences(databaseReferences) {
+  return Object.keys(databaseReferences ?? {}).length > 0;
+}
+export function buildCdsDataSources(databaseReferences, dataverseOrgUrl) {
+  return Object.values(databaseReferences).flatMap(databaseReference => Object.values(databaseReference.dataSources ?? {}).map(dataSource => ({
+    runtimeUrl: dataverseOrgUrl ? `${dataverseOrgUrl}/api/data/v9.0/` : '',
+    entitySetName: dataSource.entitySetName ?? '',
+    logicalName: dataSource.logicalName ?? '',
+    version: '9.2'
+  })));
+}

package/lib/module/platform/DataverseGlobalDiscoveryApi.js

@@ -0,0 +1,89 @@
+"use strict";
+
+import { getHttpCorrelationProperties } from '@microsoft/power-apps-native-common/http';
+import * as SecureStore from 'expo-secure-store';
+import { getAppLogger, HostOperationNames, platformHttpClient } from "../telemetry/index.js";
+import { buildGlobalDiscoveryUrl, globalDiscoveryScope } from "./GlobalDiscovery.js";
+const INSTANCE_URL_CACHE_KEY_PREFIX = 'microsoft.power-apps-native-host.instance-url.v1';
+const INSTANCE_URL_CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+function getInstanceUrlCacheKey(environmentId, region) {
+  return `${INSTANCE_URL_CACHE_KEY_PREFIX}.${region.toLowerCase()}.${environmentId.toLowerCase()}`;
+}
+async function getCachedInstanceUrl(environmentId, region) {
+  try {
+    const cachedValue = await SecureStore.getItemAsync(getInstanceUrlCacheKey(environmentId, region));
+    if (!cachedValue) {
+      return null;
+    }
+    const entry = JSON.parse(cachedValue);
+    if (typeof entry.instanceUrl !== 'string' || typeof entry.expiresAt !== 'number' || entry.expiresAt <= Date.now()) {
+      return null;
+    }
+    return entry.instanceUrl;
+  } catch {
+    return null;
+  }
+}
+async function cacheInstanceUrl(environmentId, region, instanceUrl) {
+  try {
+    const entry = {
+      instanceUrl,
+      expiresAt: Date.now() + INSTANCE_URL_CACHE_TTL_MS
+    };
+    await SecureStore.setItemAsync(getInstanceUrlCacheKey(environmentId, region), JSON.stringify(entry));
+  } catch {
+    // SecureStore may be unavailable (for example, on web); discovery still succeeds.
+  }
+}
+function getSafeErrorName(error) {
+  return error instanceof Error ? error.constructor.name : typeof error;
+}
+
+/** Fetch the Dataverse instance URL from the Dataverse Global Discovery Service. */
+export async function fetchInstanceUrl(environmentId, region, acquireToken, _bearerToken) {
+  const scenario = getAppLogger().trackScenario(HostOperationNames.PlatformFetchInstanceUrl, {
+    environmentId,
+    region
+  });
+  try {
+    const cachedInstanceUrl = await getCachedInstanceUrl(environmentId, region);
+    if (cachedInstanceUrl) {
+      scenario.complete({
+        hasInstanceUrl: true,
+        cacheHit: true
+      });
+      return cachedInstanceUrl;
+    }
+    const url = buildGlobalDiscoveryUrl(environmentId, region);
+    const token = await acquireToken([globalDiscoveryScope(region)]);
+    if (!token) {
+      throw new Error('fetchInstanceUrl: failed to acquire Dataverse Global Discovery token');
+    }
+    const response = await platformHttpClient.request(url, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json'
+      }
+    });
+    if (!response.ok) {
+      throw new Error(`fetchInstanceUrl: Global Discovery returned ${response.status} ${response.statusText}`);
+    }
+    const result = await response.json();
+    const instanceUrl = result.value?.find(instance => instance.EnvironmentId?.toLowerCase() === environmentId.toLowerCase())?.ApiUrl;
+    if (instanceUrl) {
+      await cacheInstanceUrl(environmentId, region, instanceUrl);
+    }
+    scenario.complete({
+      hasInstanceUrl: instanceUrl !== undefined,
+      cacheHit: false,
+      ...getHttpCorrelationProperties(response.headers)
+    });
+    return instanceUrl;
+  } catch (error) {
+    scenario.fail(undefined, {
+      errorName: getSafeErrorName(error)
+    });
+    throw error;
+  }
+}