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

package/lib/module/connections/PowerPlatformConnectionApi.js

@@ -19,8 +19,10 @@ import { connectionIdsEqual, extractConnectionId } from "../connections/disambig
 import { applyRegisteredConnectionUsages, getUnregisteredConnectionRequirements, isTransientConnectionConsentStatus } from "./connectionState.js";
 import { getConnectionDatasetName } from "./types.js";
 import { getAppLogger, HostOperationNames, platformHttpClient } from "../telemetry/index.js";
+import { tryResolveTelemetryLocationFromEnvironment } from '@microsoft/power-apps-native-common';
 import { getHttpCorrelationProperties } from '@microsoft/power-apps-native-common/http';
 import { debugLog, debugWarn } from "../logger.js";
+import { TargetRuntimeError } from "../target/errors.js";
 
 // Power Platform connectivity API version used across all calls here.
 const API_VERSION = '1';
@@ -121,8 +123,7 @@ export async function fetchConnectionsForConnector(connectorId, environmentId, r
       }
     });
     if (!res.ok) {
-      const errorText = await res.text().catch(() => res.statusText);
-      throw new Error(`Unable to list connector connections (HTTP ${res.status}): ${errorText}`);
+      throw new Error(`Unable to list connector connections (HTTP ${res.status})`);
     }
     const body = await res.json();
     return (body.value ?? []).map(c => {
@@ -143,7 +144,7 @@ export async function fetchConnectionsForConnector(connectorId, environmentId, r
     });
   } catch (error) {
     if (error instanceof Error) throw error;
-    throw new Error(`Unable to list connector connections: ${String(error)}`);
+    throw new Error('Unable to list connector connections');
   }
 }
 
@@ -231,10 +232,9 @@ export async function createConnection(connectorId, environmentId, region, token
       body: JSON.stringify(body)
     });
     if (!res.ok) {
-      const errText = await res.text().catch(() => res.statusText);
       const result = {
         status: 'error',
-        message: `HTTP ${res.status}: ${errText}`
+        message: `Unable to create the connection (HTTP ${res.status})`
       };
       scenario.completeWithError({
         httpStatus: res.status
@@ -267,14 +267,13 @@ export async function createConnection(connectorId, environmentId, region, token
       body: JSON.stringify(buildConsentLinkDefinition(oauthRedirectUrl))
     });
     if (!consentRes.ok) {
-      const errorText = await consentRes.text().catch(() => consentRes.statusText);
       scenario.completeWithError({
         httpStatus: consentRes.status,
         phase: 'getConsentLink'
       });
       return {
         status: 'error',
-        message: `Unable to start connector consent (HTTP ${consentRes.status}): ${errorText}`
+        message: `Unable to start connector consent (HTTP ${consentRes.status})`
       };
     }
     const consentData = await consentRes.json();
@@ -303,7 +302,7 @@ export async function createConnection(connectorId, environmentId, region, token
     });
     return {
       status: 'error',
-      message: String(e)
+      message: 'Unable to create the connection.'
     };
   }
 }
@@ -331,14 +330,13 @@ export async function repairConnection(connectorId, connectionName, environmentI
         })
       });
       if (!updateResponse.ok) {
-        const errorText = await updateResponse.text().catch(() => updateResponse.statusText);
         scenario.completeWithError({
           httpStatus: updateResponse.status,
           phase: 'update'
         });
         return {
           status: 'error',
-          message: `Unable to update the connection (HTTP ${updateResponse.status}): ${errorText}`
+          message: `Unable to update the connection (HTTP ${updateResponse.status})`
         };
       }
       if (!requiresApiConsent) {
@@ -357,7 +355,7 @@ export async function repairConnection(connectorId, connectionName, environmentI
       });
       return {
         status: 'error',
-        message: `Unable to update the connection: ${String(error)}`
+        message: 'Unable to update the connection.'
       };
     }
   }
@@ -382,14 +380,13 @@ export async function repairConnection(connectorId, connectionName, environmentI
       body: JSON.stringify(buildConsentLinkDefinition(oauthRedirectUrl))
     });
     if (!response.ok) {
-      const errorText = await response.text().catch(() => response.statusText);
       scenario.completeWithError({
         httpStatus: response.status,
         phase: 'getConsentLink'
       });
       return {
         status: 'error',
-        message: `Unable to repair connector consent (HTTP ${response.status}): ${errorText}`
+        message: `Unable to repair connector consent (HTTP ${response.status})`
       };
     }
     const data = await response.json();
@@ -418,7 +415,7 @@ export async function repairConnection(connectorId, connectionName, environmentI
     });
     return {
       status: 'error',
-      message: `Unable to repair connector consent: ${String(error)}`
+      message: 'Unable to repair connector consent.'
     };
   }
 }
@@ -588,8 +585,7 @@ export async function fetchAppConnectionUsages(appId, environmentId, region, tok
     }
   });
   if (!response.ok) {
-    const errorText = await response.text().catch(() => response.statusText);
-    throw new Error(`Unable to load app connection usages (HTTP ${response.status}): ${errorText}`);
+    throw new Error(`Unable to load app connection usages (HTTP ${response.status})`);
   }
   const data = await response.json();
   return (data.value ?? []).filter(usage => Boolean(usage.name && usage.properties?.reference && usage.properties?.apiId)).map(usage => ({
@@ -611,8 +607,7 @@ export async function postConnectionUsage(appId, usage, environmentId, region, t
     body: JSON.stringify(buildConnectionUsageRequest(appId, usage))
   });
   if (!response.ok) {
-    const errorText = await response.text().catch(() => response.statusText);
-    throw new Error(`Unable to register connection usage (HTTP ${response.status}): ${errorText}`);
+    throw new Error(`Unable to register connection usage (HTTP ${response.status})`);
   }
 }
 export async function reportScopeConsents(appId, usages, environmentId, region, token) {
@@ -627,8 +622,7 @@ export async function reportScopeConsents(appId, usages, environmentId, region,
     body: JSON.stringify(buildScopeConsentRequest(usages))
   });
   if (!response.ok) {
-    const errorText = await response.text().catch(() => response.statusText);
-    throw new Error(`Unable to register connection scope consent (HTTP ${response.status}): ${errorText}`);
+    throw new Error(`Unable to register connection scope consent (HTTP ${response.status})`);
   }
 }
 
@@ -653,7 +647,7 @@ export async function reportScopeConsents(appId, usages, environmentId, region,
  * @param environmentId - Environment GUID.
  * @param region        - Cluster region (default "prod").
  * @param token         - Bearer token for {@link powerPlatformScope}`(region)`.
- * @returns Processed launch data, or `null` when the app is not found.
+ * @returns Processed launch data. Missing or inaccessible apps throw a typed error.
  */
 export async function fetchAppLaunchData(appId, environmentId, region, token) {
   const base = buildEnvironmentEndpoint(environmentId, region);
@@ -669,16 +663,17 @@ export async function fetchAppLaunchData(appId, environmentId, region, token) {
       body: '{}'
     });
   } catch (error) {
-    throw new Error(`Unable to reach the Power Platform app launch endpoint: ${String(error)}`);
+    throw new TargetRuntimeError('service-unavailable', 'launch', true, 'The app launch service is temporarily unavailable. Try again.', undefined, error);
   }
   if (!res.ok) {
     const responseText = await res.text().catch(() => res.statusText);
     if (isAppLaunchAccessDenied(res.status, responseText)) {
-      throw new AppLaunchAccessDeniedError();
+      throw new TargetRuntimeError('app-access-denied', 'launch', false, 'You do not have access to this app. Ask the app owner or an administrator to share it with you.');
     }
-    const failureMessage = getAppLaunchFailureMessage(res.status, res.statusText, responseText);
-    if (!failureMessage) return null;
-    throw new Error(failureMessage);
+    if (!getAppLaunchFailureMessage(res.status, res.statusText, responseText)) {
+      throw new TargetRuntimeError('app-not-found', 'launch', false, 'The configured app is missing from the selected environment.');
+    }
+    throw new TargetRuntimeError('service-unavailable', 'launch', res.status === 429 || res.status >= 500, res.status === 429 || res.status >= 500 ? 'The app launch service is temporarily unavailable. Try again.' : 'The app could not be loaded from the selected environment.');
   }
   try {
     const data = await res.json();
@@ -843,9 +838,11 @@ export async function fetchAppLaunchData(appId, environmentId, region, token) {
       }
     }
     const conflictingDataSources = findConnectionDataSourceConflicts(connectionRequirements);
+    const telemetryLocation = tryResolveTelemetryLocationFromEnvironment(data.app?.properties?.environment?.properties?.location, data.app?.properties?.environment?.properties?.cluster?.geoShortName);
     const result = {
       connectionRefs,
       dataverseOrgUrl,
+      telemetryLocation,
       databaseReferences: data.app?.properties?.databaseReferences ?? {},
       missingConnectors,
       missingConnectionReferences,
@@ -881,7 +878,7 @@ export async function fetchAppLaunchData(appId, environmentId, region, token) {
     }));
     return result;
   } catch (error) {
-    throw new Error(`The Power Platform app launch response was invalid: ${String(error)}`);
+    throw new Error('The Power Platform app launch response was invalid');
   }
 }
 

package/lib/module/connections/connectionMetadata.js

@@ -45,9 +45,9 @@ export function hasOAuthParameter(parameters) {
 export function buildConnectionUserConsentUrl(environmentEndpoint, connectorId, connectionId) {
   return `${environmentEndpoint}/connectivity/connectors/${encodeURIComponent(getConnectorId(connectorId))}` + `/connections/${encodeURIComponent(connectionId)}/userConsent?api-version=1`;
 }
-export function getAppLaunchFailureMessage(status, statusText, responseText) {
+export function getAppLaunchFailureMessage(status, _statusText, _responseText) {
   if (status === 404) return null;
-  return `Unable to load the published app (HTTP ${status}): ${responseText || statusText}`;
+  return `Unable to load the published app (HTTP ${status})`;
 }
 export function isAppLaunchAccessDenied(status, responseText) {
   if (status !== 403) return false;

package/lib/module/connections/resolveConnections.js

@@ -21,7 +21,7 @@
 import { fetchConnectorMetadata, grantConnectionUserConsent } from "./PowerPlatformConnectionApi.js";
 import { getConnectionNamesRequiringAclGrant, shouldGrantConnectionUserConsent } from "./connectionState.js";
 import { connectionUserConsentScope, buildEnvironmentEndpoint } from "../platform/PowerPlatformEnvironmentApi.js";
-import { fetchInstanceUrl } from "../platform/DataverseGlobalDiscoveryApi.js";
+import { fetchInstanceMetadata } from "../platform/DataverseGlobalDiscoveryApi.js";
 import { connectionIdsEqual, disambiguateConnections, extractConnectionId } from "../connections/disambiguate.js";
 import { buildConnectionRequirements, ConnectionStatus, findConnectionDataSourceConflicts, getConnectionDatasetName, getFlowConnectionName, getFlowDataSourceNames, isCompositeConnectionApiId, getConnectorId, normalizeApiId } from "./types.js";
 import { platformHttpClient } from "../telemetry/index.js";
@@ -95,8 +95,12 @@ export async function resolveViaStaticRefs({
     Authorization: `Bearer ${token}`
   };
 
-  // Fetch the Dataverse instanceUrl only when the app uses Dataverse.
-  const [instanceUrl, ...connResults] = await Promise.all([hasDataverse ? fetchInstanceUrl(environmentId, region, acquireToken, token) : Promise.resolve(undefined), ...Object.entries(directConnectionReferences).map(async ([localRefId, ref]) => {
+  // GDS provides authoritative geography when the environment has Dataverse,
+  // even if this app does not use it. Only Dataverse apps require the lookup.
+  const [instanceMetadata, ...connResults] = await Promise.all([fetchInstanceMetadata(environmentId, region, acquireToken, token).catch(error => {
+    if (hasDataverse) throw error;
+    return undefined;
+  }), ...Object.entries(directConnectionReferences).map(async ([localRefId, ref]) => {
     const apiId = normalizeApiId(ref.id);
     const schema = schemaByApiId[apiId];
     if (!schema) {
@@ -252,7 +256,7 @@ export async function resolveViaStaticRefs({
       unresolvedApiIds.push(normalizeApiId(dr.apiId));
     }
   }
-  const dataverseOrgUrl = (instanceUrl ?? '').replace(/\/$/, '');
+  const dataverseOrgUrl = (instanceMetadata?.instanceUrl ?? '').replace(/\/$/, '');
 
   // Build the final AppConnectionReference map.
   const connectionRefs = {};
@@ -295,6 +299,7 @@ export async function resolveViaStaticRefs({
   return {
     connectionRefs,
     dataverseOrgUrl,
+    telemetryLocation: instanceMetadata?.telemetryLocation,
     databaseReferences: {},
     missingConnectors: [...new Set(unresolvedApiIds)],
     missingConnectionReferences,

package/lib/module/connections/types.js

@@ -98,7 +98,7 @@ export function hasCompleteStaticConnectionConfig(connectionReferences, schemaMa
   const directReferences = references.filter(reference => !isCompositeConnectionApiId(reference.id));
   return directReferences.length > 0 && directReferences.every(reference => Boolean(reference.id) && reference.dataSources.length > 0 && reference.dataSources.every(dataSource => Boolean(schemaMap[dataSource]?.name && schemaMap[dataSource]?.properties?.primaryRuntimeUrl)));
 }
-export function buildConnectionResolutionKey(appId, environmentId, connectionReferences) {
+export function buildConnectionResolutionKey(appId, environmentId, connectionReferences, targetIdentity) {
   const references = Object.entries(connectionReferences).sort(([left], [right]) => left.localeCompare(right)).map(([localRefId, reference]) => ({
     localRefId,
     id: reference.id,
@@ -109,7 +109,14 @@ export function buildConnectionResolutionKey(appId, environmentId, connectionRef
   return JSON.stringify({
     appId: appId ?? '',
     environmentId,
-    references
+    references,
+    ...(targetIdentity ? {
+      tenantId: targetIdentity.tenantId?.toLowerCase() ?? '',
+      appName: targetIdentity.appName ?? '',
+      region: targetIdentity.region?.toLowerCase() ?? '',
+      generation: targetIdentity.generation ?? 0,
+      accountIdentifier: targetIdentity.accountIdentifier ?? ''
+    } : {})
   });
 }
 

package/lib/module/connections/useConnectionRefs.js

@@ -36,7 +36,8 @@
 import { useState, useEffect, useRef } from 'react';
 import { isDevPlayer } from "../utils/isDevPlayer.js";
 import { powerPlatformScope } from "../platform/PowerPlatformEnvironmentApi.js";
-import { AppLaunchAccessDeniedError, fetchAppLaunchData } from "./PowerPlatformConnectionApi.js";
+import { fetchAppLaunchData } from "./PowerPlatformConnectionApi.js";
+import { TargetRuntimeError } from "../target/errors.js";
 import { applyAclGrants, resolveViaStaticRefs } from "./resolveConnections.js";
 import { applyRegisteredConnectionUsages, getConnectionNamesRequiringAclGrant, invalidateFailedAclGrants, selectLaunchConnection } from "./connectionState.js";
 import { debugLog, debugWarn } from "../logger.js";
@@ -68,7 +69,9 @@ export function useConnectionRefs({
   schemaMap,
   onDisambiguationNeeded,
   onMissingConnection,
-  isvClientId
+  isvClientId,
+  onTelemetryLocationResolved,
+  targetIdentity
 }) {
   const [connectionRefs, setConnectionRefs] = useState({});
   const [isReady, setIsReady] = useState(false);
@@ -91,7 +94,10 @@ export function useConnectionRefs({
   const isBackgroundRetryRef = useRef(false);
   const MAX_TOKEN_RETRIES = 5;
   const TOKEN_RETRY_DELAY_MS = 2000;
-  const currentConfigKey = buildConnectionResolutionKey(appId, environmentId, isDevPlayer ? connectionReferences : {});
+  const currentConfigKey = buildConnectionResolutionKey(appId, environmentId, isDevPlayer ? connectionReferences : {}, targetIdentity ? {
+    ...targetIdentity,
+    region
+  } : undefined);
   useEffect(() => {
     if (!isSignedIn) {
       tokenRetryCountRef.current = 0;
@@ -200,9 +206,6 @@ export function useConnectionRefs({
       let result = null;
       if (appId && environmentId && !isDevPlayer) {
         result = await fetchAppLaunchData(appId, environmentId, region, token);
-        if (!result) {
-          throw new Error(`App "${appId}" is not available in environment "${environmentId}". Push the mobile app to this environment and try again.`);
-        }
         if (result && onDisambiguationNeeded) {
           for (const requirement of [...result.missingConnectionReferences]) {
             const candidates = result.connectionCandidates[requirement.localRefId] ?? [];
@@ -260,6 +263,9 @@ export function useConnectionRefs({
         });
         return;
       }
+      if (result.telemetryLocation) {
+        onTelemetryLocationResolved?.(result.telemetryLocation);
+      }
 
       // Pre-warm the Dataverse token while the user waits.
       if (result.dataverseOrgUrl) {
@@ -296,15 +302,18 @@ export function useConnectionRefs({
           errorName: e instanceof Error ? e.name : 'UnknownError'
         });
         getAppLogger().trackErrorEvent(HostOperationNames.PlatformLoadConnectionsFailed, {
-          error: String(e),
+          errorName: e instanceof Error ? e.name : 'UnknownError',
+          errorCode: e instanceof TargetRuntimeError ? e.code : undefined,
           hasAppId: Boolean(appId),
           hasEnvironmentId: Boolean(environmentId),
           connectionReferenceCount: Object.keys(connectionReferences).length,
           runningInDevPlayer: isDevPlayer
         });
-        const accessDenied = e instanceof AppLaunchAccessDeniedError;
-        setErrorKind(accessDenied ? 'app-access-denied' : 'generic');
-        setError(accessDenied ? 'You don’t have access to this app. Ask the app owner or an administrator to share it with you, then try again.' : 'Unable to load this app from Power Platform. Try again later.');
+        const targetError = e instanceof TargetRuntimeError ? e : null;
+        const accessDenied = targetError?.code === 'app-access-denied';
+        const appNotFound = targetError?.code === 'app-not-found';
+        setErrorKind(accessDenied ? 'app-access-denied' : appNotFound ? 'app-not-found' : 'generic');
+        setError(targetError?.userMessage ?? (accessDenied ? 'You don’t have access to this app. Ask the app owner or an administrator to share it with you, then try again.' : 'Unable to load this app from Power Platform. Try again later.'));
         setIsReady(true);
       }
     });
@@ -313,7 +322,7 @@ export function useConnectionRefs({
       if (retryTimer) clearTimeout(retryTimer);
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [isSignedIn, retryTick, appId, environmentId, region, connectionReferences, hasDataverse, schemaMap, isvClientId]);
+  }, [isSignedIn, retryTick, appId, environmentId, region, connectionReferences, hasDataverse, schemaMap, isvClientId, onTelemetryLocationResolved, targetIdentity?.tenantId, targetIdentity?.appName, targetIdentity?.generation, targetIdentity?.accountIdentifier]);
   return {
     connectionRefs,
     isReady,

package/lib/module/index.js

@@ -13,14 +13,17 @@ 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 { invalidateNativeHostRuntime, 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 { PowerAppsRuntimeGate, usePowerAppsExperience } from "./target/PowerAppsExperience.js";
 export { buildEnvironmentEndpoint, POWER_PLATFORM_API_SCOPE } from "./platform/PowerPlatformEnvironmentApi.js";
 export { fetchInstanceUrl } from "./platform/DataverseGlobalDiscoveryApi.js";
+export { buildCanvasAppResolutionUrl, canonicalizeDataverseOrigin } from "./platform/CanvasAppResolution.js";
+export { resolveCanvasApp } from "./platform/CanvasAppResolutionApi.js";
 export { buildCdsDataSources } from "./platform/DataverseDataSources.js";
 export { useConnectionRefs } from "./connections/useConnectionRefs.js";
 // Connection creation & OAuth flow
@@ -48,6 +51,6 @@ export { isDevPlayer } from "./utils/isDevPlayer.js";
 export { base64ToDataverseUploadFile, base64ToUint8Array, createDataverseUploadFile } from "./utils/dataverseUtils.js";
 
 // ── Telemetry ─────────────────────────────────────────────────────────────────
-export { getAppLogger, configureAppLogger, getCustomerTelemetryLogger, HostOperationNames } from "./telemetry/index.js";
+export { getAppLogger, configureAppLogger, getCustomEventsLogger, HostOperationNames } from "./telemetry/index.js";
 // ── Error boundary ────────────────────────────────────────────────────────────
 export { ErrorBoundary } from "./ErrorBoundary.js";

package/lib/module/platform/CanvasAppResolution.js

@@ -0,0 +1,27 @@
+"use strict";
+
+export function canonicalizeDataverseOrigin(value) {
+  const url = new URL(value);
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== '' && url.pathname !== '/') {
+    throw new Error('Dataverse URL must be an HTTPS origin');
+  }
+  return url.origin.toLowerCase();
+}
+export function areDataverseOriginAliases(left, right) {
+  const normalizeHost = value => {
+    const url = new URL(canonicalizeDataverseOrigin(value));
+    const labels = url.hostname.split('.');
+    if (labels[1] === 'api') labels.splice(1, 1);
+    return `${labels.join('.')}:${url.port}`;
+  };
+  return normalizeHost(left) === normalizeHost(right);
+}
+export function buildCanvasAppResolutionUrl(dataverseApiUrl, appName) {
+  const origin = canonicalizeDataverseOrigin(dataverseApiUrl);
+  const query = new URLSearchParams({
+    '$select': 'name,uniquecanvasappid,canvasapptype,componentstate',
+    '$filter': 'name eq @appName and componentstate eq 0',
+    '@appName': `'${appName.replace(/'/g, "''")}'`
+  });
+  return `${origin}/api/data/v9.2/canvasapps?${query.toString()}`;
+}

package/lib/module/platform/CanvasAppResolutionApi.js

@@ -0,0 +1,65 @@
+"use strict";
+
+import { getHttpCorrelationProperties } from '@microsoft/power-apps-native-common/http';
+import { getAppLogger, HostOperationNames, platformHttpClient } from "../telemetry/index.js";
+import { TargetRuntimeError } from "../target/errors.js";
+import { buildCanvasAppResolutionUrl, canonicalizeDataverseOrigin } from "./CanvasAppResolution.js";
+const GUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+export async function resolveCanvasApp(target, dataverseApiUrl, acquireToken, generation) {
+  const assertCurrent = () => {
+    if (generation && !generation.isCurrent(generation.value)) {
+      throw new TargetRuntimeError('stale-operation', 'app-resolution', false, 'The selected environment changed before app resolution completed.', target.id);
+    }
+  };
+  const origin = canonicalizeDataverseOrigin(dataverseApiUrl);
+  const scenario = getAppLogger().trackScenario(HostOperationNames.PlatformFetchInstanceUrl, {
+    targetId: target.id,
+    generation: generation?.value
+  });
+  try {
+    const token = await acquireToken([`${origin}/user_impersonation`]);
+    assertCurrent();
+    if (!token) {
+      throw new TargetRuntimeError('app-metadata-access-denied', 'app-resolution', false, 'You do not have access to app metadata in the selected environment.', target.id);
+    }
+    const response = await platformHttpClient.request(buildCanvasAppResolutionUrl(origin, target.appName), {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json'
+      }
+    });
+    assertCurrent();
+    if (response.status === 401 || response.status === 403) {
+      throw new TargetRuntimeError('app-metadata-access-denied', 'app-resolution', false, 'You do not have access to app metadata in the selected environment.', target.id);
+    }
+    if (!response.ok) throw new Error(`Canvas App metadata request failed with status ${response.status}`);
+    const payload = await response.json();
+    assertCurrent();
+    const rows = payload.value ?? [];
+    if (rows.length === 0) {
+      throw new TargetRuntimeError('app-metadata-missing', 'app-resolution', false, 'The configured app is missing from the selected environment.', target.id);
+    }
+    if (rows.length !== 1) {
+      throw new TargetRuntimeError('app-metadata-ambiguous', 'app-resolution', false, 'More than one app matches the selected environment configuration.', target.id);
+    }
+    const row = rows[0];
+    const appId = row.uniquecanvasappid?.toLowerCase();
+    if (row.name !== target.appName || row.componentstate !== 0 || !appId || !GUID_PATTERN.test(appId)) {
+      throw new TargetRuntimeError('app-metadata-missing', 'app-resolution', false, 'The configured app metadata is invalid in the selected environment.', target.id);
+    }
+    scenario.complete({
+      ...getHttpCorrelationProperties(response.headers)
+    });
+    return {
+      ...target,
+      appId,
+      dataverseApiUrl: origin
+    };
+  } catch (error) {
+    scenario.fail(undefined, {
+      errorCode: error instanceof TargetRuntimeError ? error.code : 'service-unavailable'
+    });
+    if (error instanceof TargetRuntimeError) throw error;
+    throw new TargetRuntimeError('service-unavailable', 'app-resolution', true, 'App metadata is temporarily unavailable. Try again.', target.id, error);
+  }
+}

package/lib/module/platform/DataverseGlobalDiscoveryApi.js

@@ -1,33 +1,38 @@
 "use strict";
 
+import { tryResolveTelemetryLocationFromDataverseRegion } from '@microsoft/power-apps-native-common';
 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';
+import { buildGlobalDiscoveryListUrl, buildGlobalDiscoveryUrl, globalDiscoveryScope, parseDiscoveredEnvironments } from "./GlobalDiscovery.js";
+import { TargetRuntimeError } from "../target/errors.js";
+const INSTANCE_URL_CACHE_KEY_PREFIX = 'microsoft.power-apps-native-host.instance-url.v3';
 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));
+    const cacheKey = getInstanceUrlCacheKey(environmentId, region);
+    const cachedValue = await SecureStore.getItemAsync(cacheKey);
     if (!cachedValue) {
       return null;
     }
     const entry = JSON.parse(cachedValue);
-    if (typeof entry.instanceUrl !== 'string' || typeof entry.expiresAt !== 'number' || entry.expiresAt <= Date.now()) {
+    if (typeof entry.instanceUrl !== 'string' || entry.telemetryLocation !== undefined && entry.telemetryLocation !== 'eu' && entry.telemetryLocation !== 'global' || typeof entry.expiresAt !== 'number' || entry.expiresAt <= Date.now()) {
+      await SecureStore.deleteItemAsync(cacheKey);
       return null;
     }
-    return entry.instanceUrl;
+    return entry;
   } catch {
     return null;
   }
 }
-async function cacheInstanceUrl(environmentId, region, instanceUrl) {
+async function cacheInstanceUrl(environmentId, region, instanceUrl, telemetryLocation) {
   try {
     const entry = {
       instanceUrl,
+      telemetryLocation,
       expiresAt: Date.now() + INSTANCE_URL_CACHE_TTL_MS
     };
     await SecureStore.setItemAsync(getInstanceUrlCacheKey(environmentId, region), JSON.stringify(entry));
@@ -39,20 +44,40 @@ 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) {
+/** Enumerate enabled commercial-cloud Dataverse environments available to an authenticated tenant account. */
+export async function fetchAccessibleEnvironments(tenantId, appDisplayName, appName, acquireToken) {
+  try {
+    const region = 'prod';
+    const token = await acquireToken([globalDiscoveryScope(region)]);
+    if (!token) throw new Error('Global Discovery token is unavailable');
+    const response = await platformHttpClient.request(buildGlobalDiscoveryListUrl(region), {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json'
+      }
+    });
+    if (!response.ok) throw new Error(`Global Discovery returned ${response.status} ${response.statusText}`);
+    const result = await response.json();
+    return parseDiscoveredEnvironments(Array.isArray(result.value) ? result.value : [], tenantId, appDisplayName, appName);
+  } catch (error) {
+    throw new TargetRuntimeError('discovery-failed', 'discovery', true, 'Your environments could not be loaded. Try again.', undefined, error);
+  }
+}
+/** Fetch Dataverse environment metadata from the Global Discovery Service. */
+export async function fetchInstanceMetadata(environmentId, region, acquireToken, _bearerToken) {
   const scenario = getAppLogger().trackScenario(HostOperationNames.PlatformFetchInstanceUrl, {
     environmentId,
     region
   });
   try {
-    const cachedInstanceUrl = await getCachedInstanceUrl(environmentId, region);
-    if (cachedInstanceUrl) {
+    const cachedMetadata = await getCachedInstanceUrl(environmentId, region);
+    if (cachedMetadata) {
       scenario.complete({
         hasInstanceUrl: true,
         cacheHit: true
       });
-      return cachedInstanceUrl;
+      return cachedMetadata;
     }
     const url = buildGlobalDiscoveryUrl(environmentId, region);
     const token = await acquireToken([globalDiscoveryScope(region)]);
@@ -70,20 +95,30 @@ export async function fetchInstanceUrl(environmentId, region, acquireToken, _bea
       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;
+    const instance = result.value?.find(instance => instance.EnvironmentId?.toLowerCase() === environmentId.toLowerCase());
+    const instanceUrl = instance?.ApiUrl;
+    const telemetryLocation = tryResolveTelemetryLocationFromDataverseRegion(instance?.Region);
     if (instanceUrl) {
-      await cacheInstanceUrl(environmentId, region, instanceUrl);
+      await cacheInstanceUrl(environmentId, region, instanceUrl, telemetryLocation);
     }
     scenario.complete({
       hasInstanceUrl: instanceUrl !== undefined,
       cacheHit: false,
       ...getHttpCorrelationProperties(response.headers)
     });
-    return instanceUrl;
+    return instanceUrl ? {
+      instanceUrl,
+      telemetryLocation
+    } : undefined;
   } catch (error) {
     scenario.fail(undefined, {
       errorName: getSafeErrorName(error)
     });
     throw error;
   }
+}
+
+/** Fetch only the Dataverse instance URL for callers that do not need region metadata. */
+export async function fetchInstanceUrl(environmentId, region, acquireToken, bearerToken) {
+  return (await fetchInstanceMetadata(environmentId, region, acquireToken, bearerToken))?.instanceUrl;
 }