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

package/lib/commonjs/connections/PowerPlatformConnectionApi.js

@@ -23,8 +23,10 @@ var _connectionMetadata = require("./connectionMetadata.js");
 var _disambiguate = require("../connections/disambiguate.js");
 var _connectionState = require("./connectionState.js");
 var _index = require("../telemetry/index.js");
+var _powerAppsNativeCommon = require("@microsoft/power-apps-native-common");
 var _http = require("@microsoft/power-apps-native-common/http");
 var _logger = require("../logger.js");
+var _errors = require("../target/errors.js");
 /*!
  * power-apps-native-host — PowerPlatformConnectionApi
  *
@@ -135,8 +137,7 @@ async function fetchConnectionsForConnector(connectorId, environmentId, region,
       }
     });
     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 => {
@@ -157,7 +158,7 @@ async function fetchConnectionsForConnector(connectorId, environmentId, region,
     });
   } 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');
   }
 }
 
@@ -245,10 +246,9 @@ async function createConnection(connectorId, environmentId, region, token, displ
       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
@@ -281,14 +281,13 @@ async function createConnection(connectorId, environmentId, region, token, displ
       body: JSON.stringify((0, _connectionMetadata.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();
@@ -317,7 +316,7 @@ async function createConnection(connectorId, environmentId, region, token, displ
     });
     return {
       status: 'error',
-      message: String(e)
+      message: 'Unable to create the connection.'
     };
   }
 }
@@ -345,14 +344,13 @@ async function repairConnection(connectorId, connectionName, environmentId, regi
         })
       });
       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) {
@@ -371,7 +369,7 @@ async function repairConnection(connectorId, connectionName, environmentId, regi
       });
       return {
         status: 'error',
-        message: `Unable to update the connection: ${String(error)}`
+        message: 'Unable to update the connection.'
       };
     }
   }
@@ -396,14 +394,13 @@ async function repairConnection(connectorId, connectionName, environmentId, regi
       body: JSON.stringify((0, _connectionMetadata.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();
@@ -432,7 +429,7 @@ async function repairConnection(connectorId, connectionName, environmentId, regi
     });
     return {
       status: 'error',
-      message: `Unable to repair connector consent: ${String(error)}`
+      message: 'Unable to repair connector consent.'
     };
   }
 }
@@ -602,8 +599,7 @@ async function fetchAppConnectionUsages(appId, environmentId, region, token) {
     }
   });
   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 => ({
@@ -625,8 +621,7 @@ async function postConnectionUsage(appId, usage, environmentId, region, token) {
     body: JSON.stringify((0, _connectionMetadata.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})`);
   }
 }
 async function reportScopeConsents(appId, usages, environmentId, region, token) {
@@ -641,8 +636,7 @@ async function reportScopeConsents(appId, usages, environmentId, region, token)
     body: JSON.stringify((0, _connectionMetadata.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})`);
   }
 }
 
@@ -667,7 +661,7 @@ async function reportScopeConsents(appId, usages, environmentId, region, token)
  * @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.
  */
 async function fetchAppLaunchData(appId, environmentId, region, token) {
   const base = (0, _PowerPlatformEnvironmentApi.buildEnvironmentEndpoint)(environmentId, region);
@@ -683,16 +677,17 @@ 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 _errors.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 ((0, _connectionMetadata.isAppLaunchAccessDenied)(res.status, responseText)) {
-      throw new AppLaunchAccessDeniedError();
+      throw new _errors.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 = (0, _connectionMetadata.getAppLaunchFailureMessage)(res.status, res.statusText, responseText);
-    if (!failureMessage) return null;
-    throw new Error(failureMessage);
+    if (!(0, _connectionMetadata.getAppLaunchFailureMessage)(res.status, res.statusText, responseText)) {
+      throw new _errors.TargetRuntimeError('app-not-found', 'launch', false, 'The configured app is missing from the selected environment.');
+    }
+    throw new _errors.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();
@@ -857,9 +852,11 @@ async function fetchAppLaunchData(appId, environmentId, region, token) {
       }
     }
     const conflictingDataSources = (0, _types2.findConnectionDataSourceConflicts)(connectionRequirements);
+    const telemetryLocation = (0, _powerAppsNativeCommon.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,
@@ -895,7 +892,7 @@ 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/commonjs/connections/connectionMetadata.js

@@ -60,9 +60,9 @@ function hasOAuthParameter(parameters) {
 function buildConnectionUserConsentUrl(environmentEndpoint, connectorId, connectionId) {
   return `${environmentEndpoint}/connectivity/connectors/${encodeURIComponent((0, _types.getConnectorId)(connectorId))}` + `/connections/${encodeURIComponent(connectionId)}/userConsent?api-version=1`;
 }
-function getAppLaunchFailureMessage(status, statusText, responseText) {
+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})`;
 }
 function isAppLaunchAccessDenied(status, responseText) {
   if (status !== 403) return false;

package/lib/commonjs/connections/resolveConnections.js

@@ -100,8 +100,12 @@ async function resolveViaStaticRefs({
     Authorization: `Bearer ${token}`
   };
 
-  // Fetch the Dataverse instanceUrl only when the app uses Dataverse.
-  const [instanceUrl, ...connResults] = await Promise.all([hasDataverse ? (0, _DataverseGlobalDiscoveryApi.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([(0, _DataverseGlobalDiscoveryApi.fetchInstanceMetadata)(environmentId, region, acquireToken, token).catch(error => {
+    if (hasDataverse) throw error;
+    return undefined;
+  }), ...Object.entries(directConnectionReferences).map(async ([localRefId, ref]) => {
     const apiId = (0, _types.normalizeApiId)(ref.id);
     const schema = schemaByApiId[apiId];
     if (!schema) {
@@ -257,7 +261,7 @@ async function resolveViaStaticRefs({
       unresolvedApiIds.push((0, _types.normalizeApiId)(dr.apiId));
     }
   }
-  const dataverseOrgUrl = (instanceUrl ?? '').replace(/\/$/, '');
+  const dataverseOrgUrl = (instanceMetadata?.instanceUrl ?? '').replace(/\/$/, '');
 
   // Build the final AppConnectionReference map.
   const connectionRefs = {};
@@ -300,6 +304,7 @@ async function resolveViaStaticRefs({
   return {
     connectionRefs,
     dataverseOrgUrl,
+    telemetryLocation: instanceMetadata?.telemetryLocation,
     databaseReferences: {},
     missingConnectors: [...new Set(unresolvedApiIds)],
     missingConnectionReferences,

package/lib/commonjs/connections/types.js

@@ -111,7 +111,7 @@ function hasCompleteStaticConnectionConfig(connectionReferences, schemaMap) {
   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)));
 }
-function buildConnectionResolutionKey(appId, environmentId, connectionReferences) {
+function buildConnectionResolutionKey(appId, environmentId, connectionReferences, targetIdentity) {
   const references = Object.entries(connectionReferences).sort(([left], [right]) => left.localeCompare(right)).map(([localRefId, reference]) => ({
     localRefId,
     id: reference.id,
@@ -122,7 +122,14 @@ function buildConnectionResolutionKey(appId, environmentId, connectionReferences
   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/commonjs/connections/useConnectionRefs.js

@@ -8,6 +8,7 @@ var _react = require("react");
 var _isDevPlayer = require("../utils/isDevPlayer.js");
 var _PowerPlatformEnvironmentApi = require("../platform/PowerPlatformEnvironmentApi.js");
 var _PowerPlatformConnectionApi = require("./PowerPlatformConnectionApi.js");
+var _errors = require("../target/errors.js");
 var _resolveConnections = require("./resolveConnections.js");
 var _connectionState = require("./connectionState.js");
 var _logger = require("../logger.js");
@@ -71,7 +72,9 @@ function useConnectionRefs({
   schemaMap,
   onDisambiguationNeeded,
   onMissingConnection,
-  isvClientId
+  isvClientId,
+  onTelemetryLocationResolved,
+  targetIdentity
 }) {
   const [connectionRefs, setConnectionRefs] = (0, _react.useState)({});
   const [isReady, setIsReady] = (0, _react.useState)(false);
@@ -94,7 +97,10 @@ function useConnectionRefs({
   const isBackgroundRetryRef = (0, _react.useRef)(false);
   const MAX_TOKEN_RETRIES = 5;
   const TOKEN_RETRY_DELAY_MS = 2000;
-  const currentConfigKey = (0, _types.buildConnectionResolutionKey)(appId, environmentId, _isDevPlayer.isDevPlayer ? connectionReferences : {});
+  const currentConfigKey = (0, _types.buildConnectionResolutionKey)(appId, environmentId, _isDevPlayer.isDevPlayer ? connectionReferences : {}, targetIdentity ? {
+    ...targetIdentity,
+    region
+  } : undefined);
   (0, _react.useEffect)(() => {
     if (!isSignedIn) {
       tokenRetryCountRef.current = 0;
@@ -203,9 +209,6 @@ function useConnectionRefs({
       let result = null;
       if (appId && environmentId && !_isDevPlayer.isDevPlayer) {
         result = await (0, _PowerPlatformConnectionApi.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] ?? [];
@@ -263,6 +266,9 @@ function useConnectionRefs({
         });
         return;
       }
+      if (result.telemetryLocation) {
+        onTelemetryLocationResolved?.(result.telemetryLocation);
+      }
 
       // Pre-warm the Dataverse token while the user waits.
       if (result.dataverseOrgUrl) {
@@ -299,15 +305,18 @@ function useConnectionRefs({
           errorName: e instanceof Error ? e.name : 'UnknownError'
         });
         (0, _index.getAppLogger)().trackErrorEvent(_index.HostOperationNames.PlatformLoadConnectionsFailed, {
-          error: String(e),
+          errorName: e instanceof Error ? e.name : 'UnknownError',
+          errorCode: e instanceof _errors.TargetRuntimeError ? e.code : undefined,
           hasAppId: Boolean(appId),
           hasEnvironmentId: Boolean(environmentId),
           connectionReferenceCount: Object.keys(connectionReferences).length,
           runningInDevPlayer: _isDevPlayer.isDevPlayer
         });
-        const accessDenied = e instanceof _PowerPlatformConnectionApi.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 _errors.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);
       }
     });
@@ -316,7 +325,7 @@ 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/commonjs/index.js

@@ -63,6 +63,12 @@ Object.defineProperty(exports, "PowerAppsProvider", {
     return _PowerAppsProvider.PowerAppsProvider;
   }
 });
+Object.defineProperty(exports, "PowerAppsRuntimeGate", {
+  enumerable: true,
+  get: function () {
+    return _PowerAppsExperience.PowerAppsRuntimeGate;
+  }
+});
 Object.defineProperty(exports, "PowerPagesBridge", {
   enumerable: true,
   get: function () {
@@ -87,6 +93,12 @@ Object.defineProperty(exports, "base64ToUint8Array", {
     return _dataverseUtils.base64ToUint8Array;
   }
 });
+Object.defineProperty(exports, "buildCanvasAppResolutionUrl", {
+  enumerable: true,
+  get: function () {
+    return _CanvasAppResolution.buildCanvasAppResolutionUrl;
+  }
+});
 Object.defineProperty(exports, "buildCdsDataSources", {
   enumerable: true,
   get: function () {
@@ -159,6 +171,12 @@ Object.defineProperty(exports, "buildScopeConsentUrl", {
     return _connectionMetadata.buildScopeConsentUrl;
   }
 });
+Object.defineProperty(exports, "canonicalizeDataverseOrigin", {
+  enumerable: true,
+  get: function () {
+    return _CanvasAppResolution.canonicalizeDataverseOrigin;
+  }
+});
 Object.defineProperty(exports, "completePowerAppsAuthSession", {
   enumerable: true,
   get: function () {
@@ -279,6 +297,12 @@ Object.defineProperty(exports, "hasOAuthParameter", {
     return _connectionMetadata.hasOAuthParameter;
   }
 });
+Object.defineProperty(exports, "invalidateNativeHostRuntime", {
+  enumerable: true,
+  get: function () {
+    return _setupNativeHost.invalidateNativeHostRuntime;
+  }
+});
 Object.defineProperty(exports, "isCompositeConnectionApiId", {
   enumerable: true,
   get: function () {
@@ -333,6 +357,12 @@ Object.defineProperty(exports, "reportScopeConsents", {
     return _PowerPlatformConnectionApi.reportScopeConsents;
   }
 });
+Object.defineProperty(exports, "resolveCanvasApp", {
+  enumerable: true,
+  get: function () {
+    return _CanvasAppResolutionApi.resolveCanvasApp;
+  }
+});
 Object.defineProperty(exports, "serializeConnectionParameters", {
   enumerable: true,
   get: function () {
@@ -387,6 +417,12 @@ Object.defineProperty(exports, "useConnectionSetup", {
     return _useConnectionSetup.useConnectionSetup;
   }
 });
+Object.defineProperty(exports, "usePowerAppsExperience", {
+  enumerable: true,
+  get: function () {
+    return _PowerAppsExperience.usePowerAppsExperience;
+  }
+});
 Object.defineProperty(exports, "useThemeControl", {
   enumerable: true,
   get: function () {
@@ -408,8 +444,11 @@ var _AuthContext = require("./auth/AuthContext");
 var _completePowerAppsAuthSession = require("./auth/completePowerAppsAuthSession.js");
 var _PowerAppsHostProvider = require("./provider/PowerAppsHostProvider");
 var _PowerAppsProvider = require("./provider/PowerAppsProvider.js");
+var _PowerAppsExperience = require("./target/PowerAppsExperience.js");
 var _PowerPlatformEnvironmentApi = require("./platform/PowerPlatformEnvironmentApi.js");
 var _DataverseGlobalDiscoveryApi = require("./platform/DataverseGlobalDiscoveryApi.js");
+var _CanvasAppResolution = require("./platform/CanvasAppResolution.js");
+var _CanvasAppResolutionApi = require("./platform/CanvasAppResolutionApi.js");
 var _DataverseDataSources = require("./platform/DataverseDataSources.js");
 var _useConnectionRefs = require("./connections/useConnectionRefs.js");
 var _PowerPlatformConnectionApi = require("./connections/PowerPlatformConnectionApi.js");

package/lib/commonjs/platform/CanvasAppResolution.js

@@ -0,0 +1,33 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.areDataverseOriginAliases = areDataverseOriginAliases;
+exports.buildCanvasAppResolutionUrl = buildCanvasAppResolutionUrl;
+exports.canonicalizeDataverseOrigin = canonicalizeDataverseOrigin;
+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();
+}
+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);
+}
+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/commonjs/platform/CanvasAppResolutionApi.js

@@ -0,0 +1,69 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.resolveCanvasApp = resolveCanvasApp;
+var _http = require("@microsoft/power-apps-native-common/http");
+var _index = require("../telemetry/index.js");
+var _errors = require("../target/errors.js");
+var _CanvasAppResolution = require("./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;
+async function resolveCanvasApp(target, dataverseApiUrl, acquireToken, generation) {
+  const assertCurrent = () => {
+    if (generation && !generation.isCurrent(generation.value)) {
+      throw new _errors.TargetRuntimeError('stale-operation', 'app-resolution', false, 'The selected environment changed before app resolution completed.', target.id);
+    }
+  };
+  const origin = (0, _CanvasAppResolution.canonicalizeDataverseOrigin)(dataverseApiUrl);
+  const scenario = (0, _index.getAppLogger)().trackScenario(_index.HostOperationNames.PlatformFetchInstanceUrl, {
+    targetId: target.id,
+    generation: generation?.value
+  });
+  try {
+    const token = await acquireToken([`${origin}/user_impersonation`]);
+    assertCurrent();
+    if (!token) {
+      throw new _errors.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 _index.platformHttpClient.request((0, _CanvasAppResolution.buildCanvasAppResolutionUrl)(origin, target.appName), {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: 'application/json'
+      }
+    });
+    assertCurrent();
+    if (response.status === 401 || response.status === 403) {
+      throw new _errors.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 _errors.TargetRuntimeError('app-metadata-missing', 'app-resolution', false, 'The configured app is missing from the selected environment.', target.id);
+    }
+    if (rows.length !== 1) {
+      throw new _errors.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 _errors.TargetRuntimeError('app-metadata-missing', 'app-resolution', false, 'The configured app metadata is invalid in the selected environment.', target.id);
+    }
+    scenario.complete({
+      ...(0, _http.getHttpCorrelationProperties)(response.headers)
+    });
+    return {
+      ...target,
+      appId,
+      dataverseApiUrl: origin
+    };
+  } catch (error) {
+    scenario.fail(undefined, {
+      errorCode: error instanceof _errors.TargetRuntimeError ? error.code : 'service-unavailable'
+    });
+    if (error instanceof _errors.TargetRuntimeError) throw error;
+    throw new _errors.TargetRuntimeError('service-unavailable', 'app-resolution', true, 'App metadata is temporarily unavailable. Try again.', target.id, error);
+  }
+}