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

package/lib/module/connections/types.js

@@ -21,6 +21,97 @@ export let ConnectionStatus = /*#__PURE__*/function (ConnectionStatus) {
   ConnectionStatus["NotConnected"] = "NotConnected";
   return ConnectionStatus;
 }({});
+export function normalizeApiId(apiId) {
+  const connectorId = apiId.split('/').filter(Boolean).pop() ?? apiId;
+  return `/providers/Microsoft.PowerApps/apis/${connectorId.toLowerCase()}`;
+}
+export function getConnectorId(apiId) {
+  return (apiId.split('/').filter(Boolean).pop() ?? apiId).toLowerCase();
+}
+export function getConnectionDatasetName(reference) {
+  const datasetNames = Object.keys(reference.dataSets ?? {});
+  return datasetNames.length === 1 ? datasetNames[0] : '';
+}
+export 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 : '');
+}
+export 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];
+}
+export 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
+    };
+  });
+}
+export function isCompositeConnectionApiId(apiId) {
+  const connectorId = getConnectorId(apiId);
+  return connectorId === 'shared_excel' || connectorId === 'shared_logicflows';
+}
+export 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];
+}
+export 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)));
+}
+export 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. */
 

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

@@ -35,13 +35,14 @@
 
 import { useState, useEffect, useRef } from 'react';
 import { isDevPlayer } from "../utils/isDevPlayer.js";
-import { powerPlatformScope } from "./PowerPlatformEnvironmentApi.js";
-import { ConnectionStatus } from "../connections/types.js";
-import { fetchAppLaunchData } from "./PowerPlatformConnectionApi.js";
+import { powerPlatformScope } from "../platform/PowerPlatformEnvironmentApi.js";
+import { AppLaunchAccessDeniedError, fetchAppLaunchData } from "./PowerPlatformConnectionApi.js";
 import { applyAclGrants, resolveViaStaticRefs } from "./resolveConnections.js";
+import { applyRegisteredConnectionUsages, getConnectionNamesRequiringAclGrant, invalidateFailedAclGrants, selectLaunchConnection } from "./connectionState.js";
 import { debugLog, debugWarn } from "../logger.js";
 import { getAppLogger, HostOperationNames } from "../telemetry/index.js";
 import { buildConnectionReferences } from "../bridge/NativePowerAppsBridge.js";
+import { buildConnectionResolutionKey } from "./types.js";
 
 // Re-exported for backward compatibility with consumers that import ConnectorSchema
 // from this module (e.g. via the package index).
@@ -51,17 +52,10 @@ import { buildConnectionReferences } from "../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.
  */
 export function useConnectionRefs({
   isSignedIn,
@@ -78,31 +72,37 @@ export function useConnectionRefs({
   const [connectionRefs, setConnectionRefs] = useState({});
   const [isReady, setIsReady] = useState(false);
   const [error, setError] = useState(null);
+  const [errorKind, setErrorKind] = useState(null);
   const [missingConnectors, setMissingConnectors] = useState([]);
+  const [missingConnectionReferences, setMissingConnectionReferences] = useState([]);
+  const [connectionRequirements, setConnectionRequirements] = useState([]);
+  const [resourceConsents, setResourceConsents] = useState([]);
+  const [configurationErrors, setConfigurationErrors] = useState([]);
+  const [requiresConnectionConsent, setRequiresConnectionConsent] = useState(false);
+  const [resolvedConfigKey, setResolvedConfigKey] = useState(null);
   const [dataverseOrgUrl, setDataverseOrgUrl] = useState('');
+  const [databaseReferences, setDatabaseReferences] = 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] = useState(0);
   const tokenRetryCountRef = 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 = useRef(false);
   const MAX_TOKEN_RETRIES = 5;
   const TOKEN_RETRY_DELAY_MS = 2000;
+  const currentConfigKey = buildConnectionResolutionKey(appId, environmentId, isDevPlayer ? connectionReferences : {});
   useEffect(() => {
     if (!isSignedIn) {
       tokenRetryCountRef.current = 0;
       isBackgroundRetryRef.current = false;
       return;
     }
+    if (!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.
@@ -120,6 +120,7 @@ export 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 && !hasConnectionRefs && !environmentId) {
+      setResolvedConfigKey(currentConfigKey);
       setIsReady(true);
       return;
     }
@@ -128,50 +129,63 @@ export 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 = getAppLogger().trackScenario(HostOperationNames.PlatformResolveConnectionRefs, {
+      mode: 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([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(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) {
+          setConnectionRefs(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;
               setRetryTick(t => t + 1);
             }
           }, TOKEN_RETRY_DELAY_MS);
+        } else if (!isDevPlayer) {
+          setErrorKind('generic');
+          setError('Unable to authenticate with Power Platform to load this app. Sign in again and retry.');
+          setIsReady(true);
         }
         return;
       }
@@ -185,28 +199,47 @@ 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] ?? [];
+            if (candidates.length < 2) continue;
+            const selectedId = await onDisambiguationNeeded({
+              localRefId: requirement.localRefId,
+              apiId: requirement.apiId,
+              candidates
+            });
+            if (selectedId) {
+              selectLaunchConnection(result, requirement.localRefId, selectedId);
+            }
+          }
+        }
         if (result && isvClientId) {
-          await applyAclGrants(result.connectionRefs, environmentId, isvClientId, acquireToken);
-        } else {
-          debugWarn('[useConnectionRefs] could not verify connection ACLs; treating existing connections as setup-required');
+          const failedConnectionNames = await applyAclGrants(result.connectionRefs, result.connectionRequirements, environmentId, region, acquireToken);
+          invalidateFailedAclGrants(result, failedConnectionNames);
+        } else if (result) {
+          debugWarn('[useConnectionRefs] could not grant user-selected connections; treating them as setup-required');
           getAppLogger().trackErrorEvent(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 === ConnectionStatus.Connected) {
-                r.status = ConnectionStatus.NeedsAclGrant;
-              }
-            }
-          }
+          const unresolved = new Set(getConnectionNamesRequiringAclGrant(result.connectionRefs, result.connectionRequirements));
+          invalidateFailedAclGrants(result, unresolved);
+        }
+        if (result) {
+          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) {
+          throw new Error('Unable to load the production app from the Power Platform launch endpoint.');
+        }
         result = await resolveViaStaticRefs({
           connectionReferences,
           schemaMap,
@@ -219,7 +252,12 @@ export 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) {
@@ -228,8 +266,20 @@ export 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 => {
@@ -240,6 +290,9 @@ export function useConnectionRefs({
         // production without raising a __DEV__ LogBox redbox over the
         // otherwise-working UI. We still recover via setIsReady below.
         debugLog('[useConnectionRefs] Failed to load connections:', e);
+        resolutionScenario.fail(undefined, {
+          errorName: e instanceof Error ? e.name : 'UnknownError'
+        });
         getAppLogger().trackErrorEvent(HostOperationNames.PlatformLoadConnectionsFailed, {
           error: String(e),
           hasAppId: Boolean(appId),
@@ -247,7 +300,9 @@ export function useConnectionRefs({
           connectionReferenceCount: Object.keys(connectionReferences).length,
           runningInDevPlayer: isDevPlayer
         });
-        setError(String(e));
+        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.');
         setIsReady(true);
       }
     });
@@ -256,12 +311,20 @@ export 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
   };
 }