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

package/lib/commonjs/connections/types.js

@@ -4,6 +4,16 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.ConnectionStatus = void 0;
+exports.buildConnectionRequirements = buildConnectionRequirements;
+exports.buildConnectionResolutionKey = buildConnectionResolutionKey;
+exports.findConnectionDataSourceConflicts = findConnectionDataSourceConflicts;
+exports.getConnectionDatasetName = getConnectionDatasetName;
+exports.getConnectorId = getConnectorId;
+exports.getFlowConnectionName = getFlowConnectionName;
+exports.getFlowDataSourceNames = getFlowDataSourceNames;
+exports.hasCompleteStaticConnectionConfig = hasCompleteStaticConnectionConfig;
+exports.isCompositeConnectionApiId = isCompositeConnectionApiId;
+exports.normalizeApiId = normalizeApiId;
 /*!
  * power-apps-native-host — connection disambiguation types
  *
@@ -24,7 +34,100 @@ let ConnectionStatus = exports.ConnectionStatus = /*#__PURE__*/function (Connect
   ConnectionStatus["NotConnected"] = "NotConnected";
   return ConnectionStatus;
 }({});
+function normalizeApiId(apiId) {
+  const connectorId = apiId.split('/').filter(Boolean).pop() ?? apiId;
+  return `/providers/Microsoft.PowerApps/apis/${connectorId.toLowerCase()}`;
+}
+function getConnectorId(apiId) {
+  return (apiId.split('/').filter(Boolean).pop() ?? apiId).toLowerCase();
+}
+function getConnectionDatasetName(reference) {
+  const datasetNames = Object.keys(reference.dataSets ?? {});
+  return datasetNames.length === 1 ? datasetNames[0] : '';
+}
+function getFlowConnectionName(reference) {
+  const workflowNameHint = reference.parameterHintsV2?.workflowName?.value;
+  const workflowEntityIdHint = reference.parameterHintsV2?.workflowEntityId?.value;
+  return reference.workflowDetails?.workflowName ?? (typeof workflowNameHint === 'string' ? workflowNameHint : undefined) ?? reference.workflowDetails?.workflowEntityId ?? (typeof workflowEntityIdHint === 'string' ? workflowEntityIdHint : '');
+}
+function getFlowDataSourceNames(reference) {
+  const names = new Set(reference.dataSources);
+  const workflowDisplayNameHint = reference.parameterHintsV2?.workflowDisplayName?.value;
+  const displayName = reference.workflowDetails?.workflowDisplayName ?? (typeof workflowDisplayNameHint === 'string' ? workflowDisplayNameHint : undefined);
+  if (displayName) names.add(`${displayName.charAt(0).toLowerCase()}${displayName.slice(1)}`);
+  return [...names];
+}
+function buildConnectionRequirements(connectionReferences, scopesByApiId = {}) {
+  return Object.entries(connectionReferences).filter(([, reference]) => !isCompositeConnectionApiId(reference.id)).map(([localRefId, reference]) => {
+    const appActions = new Set(reference.appActions ?? []);
+    let isFlowDependent = false;
+    for (const dependentId of reference.dependents ?? []) {
+      const dependent = connectionReferences[dependentId];
+      if (!dependent || getConnectorId(dependent.id) !== 'shared_logicflows') continue;
+      isFlowDependent = true;
+      for (const action of dependent.nestedActions ?? []) {
+        const hint = action.flowConnectionRef ? dependent.parameterHintsV2?.[action.flowConnectionRef] : undefined;
+        if (hint?.value === localRefId && action.actionName) appActions.add(action.actionName);
+      }
+    }
+    const apiId = normalizeApiId(reference.id);
+    return {
+      localRefId,
+      apiId,
+      connectorId: getConnectorId(reference.id),
+      dataSources: reference.dataSources,
+      displayName: reference.displayName,
+      iconUri: reference.iconUri,
+      appActions: [...appActions],
+      sharedConnectionId: reference.sharedConnectionId,
+      gatewayObjectIdHint: reference.gatewayObjectIdHint,
+      authenticationType: reference.authenticationType,
+      parameterSetName: reference.parameterSetName,
+      apiScopes: scopesByApiId[apiId] ?? {
+        will: [],
+        wont: []
+      },
+      isFlowDependent
+    };
+  });
+}
+function isCompositeConnectionApiId(apiId) {
+  const connectorId = getConnectorId(apiId);
+  return connectorId === 'shared_excel' || connectorId === 'shared_logicflows';
+}
+function findConnectionDataSourceConflicts(requirements) {
+  const owners = new Map();
+  const conflicts = new Set();
+  for (const requirement of requirements) {
+    for (const dataSource of requirement.dataSources) {
+      const owner = owners.get(dataSource);
+      if (owner && owner !== requirement.localRefId) conflicts.add(dataSource);else owners.set(dataSource, requirement.localRefId);
+    }
+  }
+  return [...conflicts];
+}
+function hasCompleteStaticConnectionConfig(connectionReferences, schemaMap) {
+  const references = Object.values(connectionReferences);
+  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) {
+  const references = Object.entries(connectionReferences).sort(([left], [right]) => left.localeCompare(right)).map(([localRefId, reference]) => ({
+    localRefId,
+    id: reference.id,
+    dataSources: [...reference.dataSources].sort(),
+    sharedConnectionId: reference.sharedConnectionId ?? '',
+    parameterSetName: reference.parameterSetName ?? ''
+  }));
+  return JSON.stringify({
+    appId: appId ?? '',
+    environmentId,
+    references
+  });
+}
+
 /** A single connection instance returned by the Power Platform connectivity API. */
+
 /**
  * Result of attempting to match a single connection reference to an instance.
  *
@@ -32,10 +135,12 @@ let ConnectionStatus = exports.ConnectionStatus = /*#__PURE__*/function (Connect
  * - `missing`   — no connections found for this connector in the user's environment.
  * - `ambiguous` — multiple Connected connections found; the app must pick one.
  */
+
 /**
  * Disambiguation result for a single connection reference (one apiId, possibly
  * mapped to multiple data source names in the final connections map).
  */
+
 /**
  * Callback invoked when a connection reference has multiple Connected candidate
  * connections.  The consuming app should present a native picker UI (e.g. a
@@ -48,6 +153,7 @@ let ConnectionStatus = exports.ConnectionStatus = /*#__PURE__*/function (Connect
  * @param context.apiId       — connector API identifier
  * @param context.candidates  — list of Connected connection instances to choose from
  */
+
 /**
  * Callback invoked when the user has no connection for a required connector.
  *

package/lib/commonjs/{platform → connections}/useConnectionRefs.js

@@ -6,13 +6,14 @@ Object.defineProperty(exports, "__esModule", {
 exports.useConnectionRefs = useConnectionRefs;
 var _react = require("react");
 var _isDevPlayer = require("../utils/isDevPlayer.js");
-var _PowerPlatformEnvironmentApi = require("./PowerPlatformEnvironmentApi.js");
-var _types = require("../connections/types.js");
+var _PowerPlatformEnvironmentApi = require("../platform/PowerPlatformEnvironmentApi.js");
 var _PowerPlatformConnectionApi = require("./PowerPlatformConnectionApi.js");
 var _resolveConnections = require("./resolveConnections.js");
+var _connectionState = require("./connectionState.js");
 var _logger = require("../logger.js");
 var _index = require("../telemetry/index.js");
 var _NativePowerAppsBridge = require("../bridge/NativePowerAppsBridge.js");
+var _types = require("./types.js");
 /*!
  * power-apps-native-host — useConnectionRefs
  *
@@ -54,17 +55,10 @@ var _NativePowerAppsBridge = require("../bridge/NativePowerAppsBridge.js");
  * disambiguation support for environments where multiple connections exist for
  * the same connector.
  *
- * On sign-in this hook:
- *  1. If `appId` is set (production template), fetches connection references
- *     from the PowerApps RP `/apps/{appId}/launch` endpoint and uses those
- *     in place of the static `connectionReferences` from power.config.json.
- *  2. Acquires a Power Platform API token.
- *  3. In parallel: fetches the Dataverse instanceUrl and ALL connections for
- *     each configured connector.
- *  4. Runs disambiguation: resolves single matches, invokes `onDisambiguationNeeded`
- *     for multiple matches, and invokes `onMissingConnection` for absent ones.
- *  5. Pre-warms the Dataverse token in the MSAL cache.
- *  6. Sets isReady=true with the fully-populated connections map.
+ * Outside Dev Player, the published app launch endpoint is authoritative.
+ * Dev Player resolves unpublished local references through per-connector APIs.
+ * Both paths disambiguate candidates, pre-warm Dataverse authentication, and
+ * return a fully populated bridge configuration.
  */
 function useConnectionRefs({
   isSignedIn,
@@ -81,31 +75,37 @@ function useConnectionRefs({
   const [connectionRefs, setConnectionRefs] = (0, _react.useState)({});
   const [isReady, setIsReady] = (0, _react.useState)(false);
   const [error, setError] = (0, _react.useState)(null);
+  const [errorKind, setErrorKind] = (0, _react.useState)(null);
   const [missingConnectors, setMissingConnectors] = (0, _react.useState)([]);
+  const [missingConnectionReferences, setMissingConnectionReferences] = (0, _react.useState)([]);
+  const [connectionRequirements, setConnectionRequirements] = (0, _react.useState)([]);
+  const [resourceConsents, setResourceConsents] = (0, _react.useState)([]);
+  const [configurationErrors, setConfigurationErrors] = (0, _react.useState)([]);
+  const [requiresConnectionConsent, setRequiresConnectionConsent] = (0, _react.useState)(false);
+  const [resolvedConfigKey, setResolvedConfigKey] = (0, _react.useState)(null);
   const [dataverseOrgUrl, setDataverseOrgUrl] = (0, _react.useState)('');
+  const [databaseReferences, setDatabaseReferences] = (0, _react.useState)({});
 
-  // Bounded re-resolution for the transient null-token case. A null token at
-  // cold boot is usually a silent-auth miss (the account exists, but MSAL hasn't
-  // produced a token yet); without a retry the effect — keyed on isSignedIn —
-  // would never re-resolve once a token becomes available, leaving the bridge on
-  // the static fallback refs (no runtimeUrl) for the whole session. retryTick
-  // re-runs the effect; tokenRetryCountRef caps the attempts so it can never loop.
+  // Bounded re-resolution for transient silent-token misses.
   const [retryTick, setRetryTick] = (0, _react.useState)(0);
   const tokenRetryCountRef = (0, _react.useRef)(0);
-  // True only when this effect run was triggered by the bounded background
-  // retry below (not an initial resolution or a sign-in). Used to avoid
-  // clobbering an already-ready UI: a retry must re-resolve in the background
-  // without dropping isReady, which would otherwise unmount the whole signed-in
-  // subtree (spinner) on every tick.
+  // Dev Player retries in the background without dropping its locally ready UI.
   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 : {});
   (0, _react.useEffect)(() => {
     if (!isSignedIn) {
       tokenRetryCountRef.current = 0;
       isBackgroundRetryRef.current = false;
       return;
     }
+    if (!_isDevPlayer.isDevPlayer && (!appId || !environmentId)) {
+      setErrorKind('generic');
+      setError('The production app requires both an app ID and an environment ID before it can load from Power Platform.');
+      setIsReady(true);
+      return;
+    }
 
     // Consume the background-retry flag once per run so a later initial run or
     // sign-in can never inherit a stale value.
@@ -123,6 +123,7 @@ function useConnectionRefs({
     // an online (offline-disabled) played app never resolves its instanceUrl in
     // the Dev Player and every Dataverse read fails with "No instanceUrl found".
     if (_isDevPlayer.isDevPlayer && !hasConnectionRefs && !environmentId) {
+      setResolvedConfigKey(currentConfigKey);
       setIsReady(true);
       return;
     }
@@ -131,50 +132,63 @@ function useConnectionRefs({
     // (and no appId to fetch from the launch API).
     // Mark ready immediately so the bridge can initialise without any network calls.
     if (!environmentId && !appId) {
+      setResolvedConfigKey(currentConfigKey);
       setIsReady(true);
       return;
     }
     let cancelled = false;
     let retryTimer;
-    // Skip the reset on a background-retry run: the UI is already mounted with
-    // static fallback refs, so re-resolution must happen in the background. The
-    // full-resolution path below still sets missingConnectors/error from the
-    // real result. Resetting here would drop isReady → unmount the subtree.
+    const resolutionScenario = (0, _index.getAppLogger)().trackScenario(_index.HostOperationNames.PlatformResolveConnectionRefs, {
+      mode: _isDevPlayer.isDevPlayer ? 'devPlayer' : 'publishedApp',
+      hasAppId: Boolean(appId),
+      connectionReferenceCount: Object.keys(connectionReferences).length
+    });
+    // Preserve the locally ready Dev Player UI during a background retry.
     if (!isBackgroundRetry) {
       setIsReady(false);
       setError(null);
+      setErrorKind(null);
       setMissingConnectors([]);
+      setMissingConnectionReferences([]);
+      setConnectionRequirements([]);
+      setResourceConsents([]);
+      setConfigurationErrors([]);
+      setRequiresConnectionConsent(false);
+      setResolvedConfigKey(null);
+      setDataverseOrgUrl('');
+      setDatabaseReferences({});
     }
     async function loadConnections() {
       const token = await acquireToken([(0, _PowerPlatformEnvironmentApi.powerPlatformScope)(region)]);
-      if (cancelled) return;
+      if (cancelled) {
+        resolutionScenario.complete({
+          result: 'cancelled'
+        });
+        return;
+      }
       if (!token) {
-        // Cold boot before an auth token is available (e.g. silent-token miss or
-        // offline launch). The per-user runtimeUrl/connectionName can't be
-        // resolved yet, but seed the bridge with whatever static apiId entries can
-        // be derived from connectionReferences so the runtime fields populate on
-        // the next resolution. NOTE: when connectionReferences is empty (the
-        // appId-only fast path) this seed is itself empty, so the bridge starts
-        // with no connections until the bounded retry below resolves a token.
-        // That gap is transient as long as a retry succeeds within
-        // MAX_TOKEN_RETRIES; if the budget is exhausted the bridge stays seeded
-        // with the empty map until the next sign-out/in resets the retry count.
-        // Still mark ready so the host mounts the UI (the offline SDK serves local
-        // SQLite without a token) instead of gating on !isReady forever.
-        setConnectionRefs((0, _NativePowerAppsBridge.buildConnectionReferences)(connectionReferences));
-        setIsReady(true);
-        // Schedule a bounded re-resolution so a transient silent-auth miss
-        // recovers once a token is available, instead of staying on the static
-        // fallback refs for the rest of the session. Capped by MAX_TOKEN_RETRIES
-        // so it can never spin.
+        resolutionScenario.completeWithError({
+          reason: 'tokenUnavailable'
+        });
+        // Dev Player can render local metadata while token recovery continues;
+        // standalone apps stay blocked because production has no static fallback.
+        if (_isDevPlayer.isDevPlayer) {
+          setConnectionRefs((0, _NativePowerAppsBridge.buildConnectionReferences)(connectionReferences));
+          setIsReady(true);
+          setResolvedConfigKey(currentConfigKey);
+        }
         if (tokenRetryCountRef.current < MAX_TOKEN_RETRIES) {
           tokenRetryCountRef.current += 1;
           retryTimer = setTimeout(() => {
             if (!cancelled) {
-              isBackgroundRetryRef.current = true;
+              isBackgroundRetryRef.current = _isDevPlayer.isDevPlayer;
               setRetryTick(t => t + 1);
             }
           }, TOKEN_RETRY_DELAY_MS);
+        } else if (!_isDevPlayer.isDevPlayer) {
+          setErrorKind('generic');
+          setError('Unable to authenticate with Power Platform to load this app. Sign in again and retry.');
+          setIsReady(true);
         }
         return;
       }
@@ -188,28 +202,47 @@ 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] ?? [];
+            if (candidates.length < 2) continue;
+            const selectedId = await onDisambiguationNeeded({
+              localRefId: requirement.localRefId,
+              apiId: requirement.apiId,
+              candidates
+            });
+            if (selectedId) {
+              (0, _connectionState.selectLaunchConnection)(result, requirement.localRefId, selectedId);
+            }
+          }
+        }
         if (result && isvClientId) {
-          await (0, _resolveConnections.applyAclGrants)(result.connectionRefs, environmentId, isvClientId, acquireToken);
-        } else {
-          (0, _logger.debugWarn)('[useConnectionRefs] could not verify connection ACLs; treating existing connections as setup-required');
+          const failedConnectionNames = await (0, _resolveConnections.applyAclGrants)(result.connectionRefs, result.connectionRequirements, environmentId, region, acquireToken);
+          (0, _connectionState.invalidateFailedAclGrants)(result, failedConnectionNames);
+        } else if (result) {
+          (0, _logger.debugWarn)('[useConnectionRefs] could not grant user-selected connections; treating them as setup-required');
           (0, _index.getAppLogger)().trackErrorEvent(_index.HostOperationNames.PlatformConnectionAclGrant, {
             phase: 'launchAclVerify',
-            reason: result ? 'missingIsvClientId' : 'launchDataUnavailable',
-            connectionRefCount: result ? Object.keys(result.connectionRefs).length : 0
+            reason: 'missingIsvClientId',
+            connectionRefCount: Object.keys(result.connectionRefs).length
           });
-          for (const r of result ? Object.values(result.connectionRefs) : []) {
-            for (const inst of r.instances || []) {
-              if (r.status === _types.ConnectionStatus.Connected) {
-                r.status = _types.ConnectionStatus.NeedsAclGrant;
-              }
-            }
-          }
+          const unresolved = new Set((0, _connectionState.getConnectionNamesRequiringAclGrant)(result.connectionRefs, result.connectionRequirements));
+          (0, _connectionState.invalidateFailedAclGrants)(result, unresolved);
+        }
+        if (result) {
+          (0, _connectionState.applyRegisteredConnectionUsages)(result, result.registeredConnectionUsages);
         }
       }
 
       // Slow path: per-connector resolution.
-      // Used when: running in Dev Player, no appId (local dev), or launch API failed.
+      // Used only in Dev Player, where unpublished local app metadata is expected.
       if (!result) {
+        if (!_isDevPlayer.isDevPlayer) {
+          throw new Error('Unable to load the production app from the Power Platform launch endpoint.');
+        }
         result = await (0, _resolveConnections.resolveViaStaticRefs)({
           connectionReferences,
           schemaMap,
@@ -222,7 +255,12 @@ function useConnectionRefs({
           onMissingConnection
         });
       }
-      if (cancelled) return;
+      if (cancelled) {
+        resolutionScenario.complete({
+          result: 'cancelled'
+        });
+        return;
+      }
 
       // Pre-warm the Dataverse token while the user waits.
       if (result.dataverseOrgUrl) {
@@ -231,8 +269,20 @@ function useConnectionRefs({
       if (!cancelled) {
         setConnectionRefs(result.connectionRefs);
         setMissingConnectors(result.missingConnectors);
+        setMissingConnectionReferences(result.missingConnectionReferences);
+        setConnectionRequirements(result.connectionRequirements);
+        setResourceConsents(result.resourceConsents);
+        setConfigurationErrors(result.configurationErrors);
+        setRequiresConnectionConsent(result.requiresConnectionConsent);
         setDataverseOrgUrl(result.dataverseOrgUrl);
+        setDatabaseReferences(result.databaseReferences);
+        setResolvedConfigKey(currentConfigKey);
         setIsReady(true);
+        resolutionScenario.complete({
+          result: 'resolved',
+          missingConnectionReferenceCount: result.missingConnectionReferences.length,
+          configurationErrorCount: result.configurationErrors.length
+        });
       }
     }
     loadConnections().catch(e => {
@@ -243,6 +293,9 @@ function useConnectionRefs({
         // production without raising a __DEV__ LogBox redbox over the
         // otherwise-working UI. We still recover via setIsReady below.
         (0, _logger.debugLog)('[useConnectionRefs] Failed to load connections:', e);
+        resolutionScenario.fail(undefined, {
+          errorName: e instanceof Error ? e.name : 'UnknownError'
+        });
         (0, _index.getAppLogger)().trackErrorEvent(_index.HostOperationNames.PlatformLoadConnectionsFailed, {
           error: String(e),
           hasAppId: Boolean(appId),
@@ -250,7 +303,9 @@ function useConnectionRefs({
           connectionReferenceCount: Object.keys(connectionReferences).length,
           runningInDevPlayer: _isDevPlayer.isDevPlayer
         });
-        setError(String(e));
+        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.');
         setIsReady(true);
       }
     });
@@ -259,12 +314,20 @@ function useConnectionRefs({
       if (retryTimer) clearTimeout(retryTimer);
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [isSignedIn, retryTick]);
+  }, [isSignedIn, retryTick, appId, environmentId, region, connectionReferences, schemaMap, isvClientId]);
   return {
     connectionRefs,
     isReady,
     error,
+    errorKind,
     missingConnectors,
-    dataverseOrgUrl
+    missingConnectionReferences,
+    connectionRequirements,
+    resourceConsents,
+    configurationErrors,
+    requiresConnectionConsent,
+    resolvedConfigKey,
+    dataverseOrgUrl,
+    databaseReferences
   };
 }