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

package/lib/commonjs/connections/PowerPlatformConnectionApi.js

@@ -0,0 +1,946 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.AppLaunchAccessDeniedError = void 0;
+exports.confirmConsentCode = confirmConsentCode;
+exports.createConnection = createConnection;
+exports.deleteConnection = deleteConnection;
+exports.fetchAppConnectionUsages = fetchAppConnectionUsages;
+exports.fetchAppLaunchData = fetchAppLaunchData;
+exports.fetchConnectionsForConnector = fetchConnectionsForConnector;
+exports.fetchConnectorMetadata = fetchConnectorMetadata;
+exports.grantConnectionUserConsent = grantConnectionUserConsent;
+exports.pollConnectionStatus = pollConnectionStatus;
+exports.postConnectionUsage = postConnectionUsage;
+exports.repairConnection = repairConnection;
+exports.reportScopeConsents = reportScopeConsents;
+var _PowerPlatformEnvironmentApi = require("../platform/PowerPlatformEnvironmentApi.js");
+var _types = require("../connections/types.js");
+var _types2 = require("./types.js");
+var _connectionMetadata = require("./connectionMetadata.js");
+var _disambiguate = require("../connections/disambiguate.js");
+var _connectionState = require("./connectionState.js");
+var _index = require("../telemetry/index.js");
+var _http = require("@microsoft/power-apps-native-common/http");
+var _logger = require("../logger.js");
+/*!
+ * power-apps-native-host — PowerPlatformConnectionApi
+ *
+ * Typed wrappers around the Power Platform environment-scoped connectivity API
+ * for connection CRUD operations and connector metadata retrieval.
+ *
+ * These mirror the endpoints used by ConnectorsApi in @microsoft/power-apps-common
+ * but are implemented as plain async functions so they have no external dependencies.
+ */
+
+// Power Platform connectivity API version used across all calls here.
+const API_VERSION = '1';
+class AppLaunchAccessDeniedError extends Error {
+  constructor() {
+    super('The signed-in user does not have access to this Power App.');
+    this.name = 'AppLaunchAccessDeniedError';
+  }
+}
+exports.AppLaunchAccessDeniedError = AppLaunchAccessDeniedError;
+function normalizeResourceConsentId(resourceId) {
+  return resourceId.replace(/\/$/, '').toLowerCase();
+}
+function getSafeErrorName(error) {
+  return error instanceof Error ? error.constructor.name : typeof error;
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate a random connection ID as a 32-char lowercase hex string (UUID v4
+ * without dashes), matching the format Power Platform uses for connection
+ * resource names (e.g. "326561a0849744d5ae75c9bcaca1e5f1").
+ */
+function generateConnectionId() {
+  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+    return crypto.randomUUID().replace(/-/g, '');
+  }
+  // Fallback: manual UUID v4 bit pattern, returned as 32 hex chars.
+  return 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'.replace(/[xy]/g, c => {
+    const r = Math.random() * 16 | 0;
+    return (c === 'x' ? r : r & 0x3 | 0x8).toString(16);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Connector metadata
+// ---------------------------------------------------------------------------
+
+/** Subset of connector metadata returned by the Power Platform API. */
+
+/**
+ * Fetch metadata for a single connector from the Power Platform API.
+ *
+ * @param connectorId  - Connector short name (e.g. "shared_office365users")
+ *                       or full API path suffix.
+ * @param environmentId - Environment GUID.
+ * @param region        - Cluster region string (default "prod").
+ * @param token         - Pre-acquired Power Platform API bearer token.
+ */
+async function fetchConnectorMetadata(connectorId, environmentId, region, token) {
+  const base = (0, _PowerPlatformEnvironmentApi.buildEnvironmentEndpoint)(environmentId, region);
+  const url = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}` + `?$filter=environment eq '${environmentId}'&api-version=${API_VERSION}`;
+  try {
+    const res = await _index.platformHttpClient.request(url, {
+      headers: {
+        Authorization: `Bearer ${token}`
+      }
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const parameterSetDefinitions = body.properties?.connectionParameterSets?.values ?? [];
+    const parameterSets = (0, _connectionMetadata.buildConnectionParameterSets)(body.properties?.connectionParameters, parameterSetDefinitions);
+    return {
+      name: body.name ?? connectorId,
+      displayName: body.properties?.displayName ?? connectorId,
+      iconUri: body.properties?.iconUri ?? '',
+      description: body.properties?.description ?? '',
+      primaryRuntimeUrl: body.properties?.primaryRuntimeUrl ?? '',
+      scopes: {
+        will: body.properties?.scopes?.will ?? [],
+        wont: body.properties?.scopes?.wont ?? []
+      },
+      hasOAuthParameter: (0, _connectionMetadata.hasOAuthParameter)(body.properties?.connectionParameters) || parameterSetDefinitions.some(item => (0, _connectionMetadata.hasOAuthParameter)(item.connectionParameters ?? item.parameters)),
+      parameterSets
+    };
+  } catch {
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Connection listing
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch all connections for a given connector in the environment.
+ * Returns only the `NativeConnectionInstance` shape used by the disambiguation layer.
+ */
+async function fetchConnectionsForConnector(connectorId, environmentId, region, token) {
+  const base = (0, _PowerPlatformEnvironmentApi.buildEnvironmentEndpoint)(environmentId, region);
+  const url = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}/connections` + `?$filter=environment eq '${environmentId}'&api-version=${API_VERSION}`;
+  try {
+    const res = await _index.platformHttpClient.request(url, {
+      headers: {
+        Authorization: `Bearer ${token}`
+      }
+    });
+    if (!res.ok) {
+      const errorText = await res.text().catch(() => res.statusText);
+      throw new Error(`Unable to list connector connections (HTTP ${res.status}): ${errorText}`);
+    }
+    const body = await res.json();
+    return (body.value ?? []).map(c => {
+      const rawStatus = c.properties?.statuses?.[0];
+      const connected = rawStatus?.status === 'Connected';
+      return {
+        id: (0, _disambiguate.extractConnectionId)(c.name),
+        name: c.name,
+        apiId: `/providers/Microsoft.PowerApps/apis/${connectorId}`,
+        ownerId: c.properties?.createdBy?.id,
+        status: connected ? _types.ConnectionStatus.Connected : _types.ConnectionStatus.NotConnected,
+        displayName: c.properties?.displayName,
+        accountName: c.properties?.accountName,
+        parameterSetName: c.properties?.connectionParametersSet?.name,
+        isAuthenticated: connected,
+        statusErrorCode: rawStatus?.error?.code
+      };
+    });
+  } catch (error) {
+    if (error instanceof Error) throw error;
+    throw new Error(`Unable to list connector connections: ${String(error)}`);
+  }
+}
+
+/** Delete a single connection instance from the user's environment. */
+async function deleteConnection(connectorId, connectionId, environmentId, region, token) {
+  const base = (0, _PowerPlatformEnvironmentApi.buildEnvironmentEndpoint)(environmentId, region);
+  const url = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}/connections/${encodeURIComponent(connectionId)}` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'`;
+  try {
+    const response = await _index.platformHttpClient.request(url, {
+      method: 'DELETE',
+      headers: {
+        Authorization: `Bearer ${token}`
+      }
+    });
+    return response.ok || response.status === 404;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Connection creation (implicit OAuth)
+// ---------------------------------------------------------------------------
+
+/**
+ * Result of initiating an OAuth connection creation.
+ *
+ * `pending` — the connection has been created but is not yet authenticated.
+ *   The `consentLink` URL must be opened (in a WebView or browser) so the
+ *   user can complete the OAuth consent flow. Poll `pollConnectionStatus`
+ *   until the status changes to "Connected".
+ *
+ * `connected` — the connection resource was created in Connected state.
+ *
+ * `error` — creation failed; `message` contains the error description.
+ */
+
+/**
+ * Create a new connection for a connector in the user's environment.
+ *
+ * Calls:
+ *   PUT {envBase}/connectivity/connectors/{connectorId}/connections/{connectionId}
+ *
+ * If the response contains a `consentLink`, the connection needs OAuth
+ * completion (caller should open the URL and then poll `pollConnectionStatus`).
+ * If the connection status is already "Connected", returns `connected`.
+ *
+ * @param connectorId     - Connector short name (e.g. "shared_office365users").
+ * @param environmentId   - Environment GUID.
+ * @param region          - Cluster region.
+ * @param token           - Power Platform API bearer token.
+ * @param displayName     - Optional display name for the new connection.
+ * @param oauthRedirectUrl - Redirect URL sent to getConsentLink. The OAuth provider
+ *                           will redirect the user here after consent. Defaults to
+ *                           the standard native-client redirect accepted by Power Platform.
+ */
+async function createConnection(connectorId, environmentId, region, token, displayName, oauthRedirectUrl = 'https://login.microsoftonline.com/oauth2/nativeclient', input) {
+  const scenario = (0, _index.getAppLogger)().trackScenario(_index.HostOperationNames.PlatformCreateConnection, {
+    connectorId
+  });
+  try {
+    const base = (0, _PowerPlatformEnvironmentApi.buildEnvironmentEndpoint)(environmentId, region);
+    const connectionId = generateConnectionId();
+    const url = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}/connections/${connectionId}` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'`;
+    const body = {
+      properties: {
+        environment: {
+          name: environmentId
+        },
+        ...(0, _connectionMetadata.serializeConnectionParameters)(input),
+        consentInfo: {
+          redirectUrl: oauthRedirectUrl
+        },
+        ...(displayName ? {
+          displayName
+        } : {})
+      }
+    };
+    const res = await _index.platformHttpClient.request(url, {
+      method: 'PUT',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(body)
+    });
+    if (!res.ok) {
+      const errText = await res.text().catch(() => res.statusText);
+      const result = {
+        status: 'error',
+        message: `HTTP ${res.status}: ${errText}`
+      };
+      scenario.completeWithError({
+        httpStatus: res.status
+      });
+      return result;
+    }
+    const data = await res.json();
+    const connectionName = data.name ?? connectionId;
+    const connectionStatus = data.properties?.statuses?.[0]?.status ?? '';
+    if (connectionStatus === 'Connected') {
+      scenario.complete({
+        result: 'connected'
+      });
+      return {
+        status: 'connected',
+        connectionName
+      };
+    }
+
+    // Fetch the OAuth consent link from the dedicated endpoint.
+    // Use the pre-generated connectionId directly — not the full resource name —
+    // so the path segment is never double-encoded.
+    const consentUrl = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}` + `/connections/${connectionId}/getConsentLink` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'`;
+    const consentRes = await _index.platformHttpClient.request(consentUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json'
+      },
+      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}`
+      };
+    }
+    const consentData = await consentRes.json();
+    const browserFallbackUrl = consentData.consentLink ?? '';
+    if (browserFallbackUrl) {
+      scenario.complete({
+        result: 'pending_oauth'
+      });
+      return {
+        status: 'pending',
+        connectionName,
+        consentLink: browserFallbackUrl
+      };
+    }
+    scenario.completeWithError({
+      phase: 'getConsentLink',
+      reason: 'missingConsentPath'
+    });
+    return {
+      status: 'error',
+      message: 'The connector did not return a usable sign-in or consent URL.'
+    };
+  } catch (e) {
+    scenario.fail(undefined, {
+      errorName: getSafeErrorName(e)
+    });
+    return {
+      status: 'error',
+      message: String(e)
+    };
+  }
+}
+async function repairConnection(connectorId, connectionName, environmentId, region, token, oauthRedirectUrl = 'https://login.microsoftonline.com/oauth2/nativeclient', input, requiresApiConsent = true) {
+  const scenario = (0, _index.getAppLogger)().trackScenario(_index.HostOperationNames.PlatformRepairConnection, {
+    connectorId,
+    hasParameters: Boolean(input),
+    requiresApiConsent
+  });
+  const base = (0, _PowerPlatformEnvironmentApi.buildEnvironmentEndpoint)(environmentId, region);
+  const connectionId = (0, _disambiguate.extractConnectionId)(connectionName);
+  const connectionUrl = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}` + `/connections/${encodeURIComponent(connectionId)}` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'`;
+  if (input) {
+    try {
+      const updateResponse = await _index.platformHttpClient.request(connectionUrl, {
+        method: 'PATCH',
+        headers: {
+          Authorization: `Bearer ${token}`,
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          properties: {
+            ...(0, _connectionMetadata.serializeConnectionParameters)(input)
+          }
+        })
+      });
+      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}`
+        };
+      }
+      if (!requiresApiConsent) {
+        scenario.complete({
+          result: 'updated'
+        });
+        return {
+          status: 'connected',
+          connectionName
+        };
+      }
+    } catch (error) {
+      scenario.fail(undefined, {
+        phase: 'update',
+        errorName: getSafeErrorName(error)
+      });
+      return {
+        status: 'error',
+        message: `Unable to update the connection: ${String(error)}`
+      };
+    }
+  }
+  if (!requiresApiConsent) {
+    scenario.completeWithError({
+      phase: 'validate',
+      reason: 'missingParameters'
+    });
+    return {
+      status: 'error',
+      message: 'Connection parameters are required to repair this connection.'
+    };
+  }
+  const consentUrl = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}` + `/connections/${encodeURIComponent(connectionId)}/getConsentLink` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'`;
+  try {
+    const response = await _index.platformHttpClient.request(consentUrl, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json'
+      },
+      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}`
+      };
+    }
+    const data = await response.json();
+    if (!data.consentLink) {
+      scenario.completeWithError({
+        phase: 'getConsentLink',
+        reason: 'missingConsentPath'
+      });
+      return {
+        status: 'error',
+        message: 'The connector did not return a repair consent URL.'
+      };
+    }
+    scenario.complete({
+      result: 'pending_oauth'
+    });
+    return {
+      status: 'pending',
+      connectionName,
+      consentLink: data.consentLink
+    };
+  } catch (error) {
+    scenario.fail(undefined, {
+      phase: 'getConsentLink',
+      errorName: getSafeErrorName(error)
+    });
+    return {
+      status: 'error',
+      message: `Unable to repair connector consent: ${String(error)}`
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Connection status polling
+// ---------------------------------------------------------------------------
+
+/**
+ * Poll a connection's status until it is "Connected" or a timeout is reached.
+ *
+ * @param connectionName - The connection resource name (from createConnection result).
+ * @param environmentId  - Environment GUID.
+ * @param region         - Cluster region.
+ * @param token          - Power Platform API bearer token.
+ * @param options.intervalMs  - Polling interval in ms (default 2000).
+ * @param options.timeoutMs   - Maximum time to wait in ms (default 60000).
+ * @returns The resolved `NativeConnectionInstance` if Connected, or `null` if timed out.
+ */
+async function pollConnectionStatus(connectorId, connectionName, environmentId, region, acquireToken, options = {}) {
+  const scenario = (0, _index.getAppLogger)().trackScenario(_index.HostOperationNames.PlatformPollConnectionStatus, {
+    connectorId
+  });
+  const {
+    intervalMs = 2000,
+    timeoutMs = 60_000,
+    signal
+  } = options;
+  const deadline = Date.now() + timeoutMs;
+  try {
+    while (Date.now() < deadline) {
+      if (signal?.aborted) {
+        scenario.complete({
+          result: 'aborted'
+        });
+        return null;
+      }
+      const token = await acquireToken([(0, _PowerPlatformEnvironmentApi.powerPlatformScope)(region)]);
+      if (!token) {
+        scenario.completeWithError({
+          reason: 'tokenUnavailable'
+        });
+        return null;
+      }
+      const base = (0, _PowerPlatformEnvironmentApi.buildEnvironmentEndpoint)(environmentId, region);
+      const connectionId = (0, _disambiguate.extractConnectionId)(connectionName);
+      const url = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}/connections/${connectionId}` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'`;
+      try {
+        const res = await _index.platformHttpClient.request(url, {
+          headers: {
+            Authorization: `Bearer ${token}`
+          },
+          signal
+        });
+        if (res.ok) {
+          const data = await res.json();
+          const status = data.properties?.statuses?.[0]?.status ?? '';
+          if (status === 'Connected') {
+            scenario.complete({
+              result: 'connected'
+            });
+            return {
+              id: (0, _disambiguate.extractConnectionId)(data.name ?? connectionName),
+              name: data.name ?? connectionName,
+              apiId: data.properties?.apiId ?? '',
+              status: _types.ConnectionStatus.Connected,
+              displayName: data.properties?.displayName,
+              isAuthenticated: true
+            };
+          }
+        }
+      } catch {
+        // Transient network error — continue polling.
+      }
+      await new Promise(resolve => {
+        const finish = () => {
+          signal?.removeEventListener('abort', handleAbort);
+          resolve();
+        };
+        const timer = setTimeout(finish, intervalMs);
+        const handleAbort = () => {
+          clearTimeout(timer);
+          finish();
+        };
+        signal?.addEventListener('abort', handleAbort, {
+          once: true
+        });
+        // Allow GC to clean up the timer reference.
+        if (typeof timer === 'object' && timer !== null && 'unref' in timer) {
+          timer.unref();
+        }
+      });
+    }
+    scenario.complete({
+      result: 'timeout'
+    });
+    return null;
+  } catch (error) {
+    scenario.fail(undefined, {
+      errorName: getSafeErrorName(error)
+    });
+    throw error;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Consent code confirmation
+// ---------------------------------------------------------------------------
+
+/**
+ * Confirm a consent code returned by the APIM consent server in the OAuth
+ * redirect URL (`?code=<commitTokenCode>`).
+ *
+ * The consent server embeds a 32-char hex CommitTokenCode in the redirect URL
+ * when the OAuth exchange completes successfully. POSTing it here causes APIM
+ * to exchange it for the real OAuth tokens and activate the connection
+ * (status → Connected).
+ *
+ * When the redirect URL uses a custom scheme (e.g. `expo-app://oauth-callback`),
+ * the consent server may instead return `?error=no+code+returned` and activate
+ * the connection server-side. In that case this function is not called and the
+ * caller should poll `pollConnectionStatus` directly.
+ *
+ * @param connectorId   - Connector short name (e.g. "shared_office365users").
+ * @param connectionId  - Bare connection hex ID (no connector prefix).
+ * @param environmentId - Environment GUID.
+ * @param region        - Cluster region.
+ * @param token         - Power Platform API bearer token.
+ * @param code          - CommitTokenCode from the redirect URL `?code=` param.
+ * @returns `true` if the server accepted the code, `false` otherwise.
+ */
+async function confirmConsentCode(connectorId, connectionId, environmentId, region, token, code) {
+  const base = (0, _PowerPlatformEnvironmentApi.buildEnvironmentEndpoint)(environmentId, region);
+  const url = `${base}/connectivity/connectors/${encodeURIComponent(connectorId)}` + `/connections/${connectionId}/confirmConsentCode` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'`;
+  try {
+    const res = await _index.platformHttpClient.request(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({
+        code
+      })
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// PowerApps environment — fetch published app launch data
+// ---------------------------------------------------------------------------
+
+/**
+ * Processed result of the PowerApps app launch API call, ready to be applied
+ * directly to the NativePowerAppsBridge without further network calls.
+ */
+
+async function fetchAppConnectionUsages(appId, environmentId, region, token) {
+  const base = (0, _PowerPlatformEnvironmentApi.buildEnvironmentEndpoint)(environmentId, region);
+  const url = `${base}/powerapps/apps/${encodeURIComponent(appId.split('/').pop() ?? appId)}/connections` + `?api-version=${API_VERSION}&$filter=environment eq '${environmentId}'&$expand=api`;
+  const response = await _index.platformHttpClient.request(url, {
+    headers: {
+      Authorization: `Bearer ${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}`);
+  }
+  const data = await response.json();
+  return (data.value ?? []).filter(usage => Boolean(usage.name && usage.properties?.reference && usage.properties?.apiId)).map(usage => ({
+    reference: usage.properties.reference,
+    apiId: (0, _types2.normalizeApiId)(usage.properties.apiId),
+    connectionId: (0, _disambiguate.extractConnectionId)(usage.name),
+    appActions: usage.properties?.appActions ?? []
+  }));
+}
+async function postConnectionUsage(appId, usage, environmentId, region, token) {
+  const base = (0, _PowerPlatformEnvironmentApi.buildEnvironmentEndpoint)(environmentId, region);
+  const url = (0, _connectionMetadata.buildConnectionUsageUrl)(base, environmentId, usage);
+  const response = await _index.platformHttpClient.request(url, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json'
+    },
+    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}`);
+  }
+}
+async function reportScopeConsents(appId, usages, environmentId, region, token) {
+  if (usages.length === 0) return;
+  const base = (0, _PowerPlatformEnvironmentApi.buildEnvironmentEndpoint)(environmentId, region);
+  const response = await _index.platformHttpClient.request((0, _connectionMetadata.buildScopeConsentUrl)(base, appId), {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json'
+    },
+    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}`);
+  }
+}
+
+/**
+ * Fetch app launch data from the Power Platform environment-scoped launch
+ * endpoint and process it into the shape the NativePowerAppsBridge needs.
+ *
+ * A single call returns everything required to run the app:
+ *  - `app.properties.connectionReferences` — connectors the app requires
+ *  - `apis[]`                              — connector metadata (primaryRuntimeUrl)
+ *  - `connections[]`                       — the current user's resolved connections
+ *  - `app.properties.environment.properties.linkedEnvironmentMetadata.instanceUrl`
+ *                                          — Dataverse org URL
+ *
+ * Endpoint (environment-scoped, same base as all Power Platform API calls):
+ *   POST {envEndpoint}/powerapps/apps/{appId}/launch
+ *       ?api-version=2&lastKnownGoodPublishedVersion=true
+ *
+ * Authentication: bearer token for {@link powerPlatformScope}`(region)`.
+ *
+ * @param appId         - PowerApps app GUID (from `power.config.json` → `appId`).
+ * @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.
+ */
+async function fetchAppLaunchData(appId, environmentId, region, token) {
+  const base = (0, _PowerPlatformEnvironmentApi.buildEnvironmentEndpoint)(environmentId, region);
+  const url = `${base}/powerapps/apps/${encodeURIComponent(appId)}/launch` + `?api-version=2&lastKnownGoodPublishedVersion=true`;
+  let res;
+  try {
+    res = await _index.platformHttpClient.request(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json'
+      },
+      body: '{}'
+    });
+  } catch (error) {
+    throw new Error(`Unable to reach the Power Platform app launch endpoint: ${String(error)}`);
+  }
+  if (!res.ok) {
+    const responseText = await res.text().catch(() => res.statusText);
+    if ((0, _connectionMetadata.isAppLaunchAccessDenied)(res.status, responseText)) {
+      throw new AppLaunchAccessDeniedError();
+    }
+    const failureMessage = (0, _connectionMetadata.getAppLaunchFailureMessage)(res.status, res.statusText, responseText);
+    if (!failureMessage) return null;
+    throw new Error(failureMessage);
+  }
+  try {
+    const data = await res.json();
+    const connRefRaw = data.app?.properties?.connectionReferences ?? {};
+    const apisRaw = data.apis ?? [];
+    const connectionsRaw = data.connections ?? [];
+    const launchConnectionUsages = (data.appConnections ?? []).filter(usage => Boolean(usage.name && usage.properties?.reference && usage.properties?.apiId)).map(usage => ({
+      reference: usage.properties.reference,
+      apiId: (0, _types2.normalizeApiId)(usage.properties.apiId),
+      connectionId: (0, _disambiguate.extractConnectionId)(usage.name),
+      appActions: usage.properties?.appActions ?? []
+    }));
+    const hasCompleteLaunchUsages = launchConnectionUsages.length > 0 && data.appConnections?.every(usage => Array.isArray(usage.properties?.appActions));
+    let registeredConnectionUsages = launchConnectionUsages;
+    let fetchedConnectionUsages = false;
+    if (!hasCompleteLaunchUsages) {
+      try {
+        registeredConnectionUsages = await fetchAppConnectionUsages(appId, environmentId, region, token);
+        fetchedConnectionUsages = true;
+      } catch (usageError) {
+        (0, _logger.debugWarn)('[fetchAppLaunchData] appConnections incomplete and usage lookup failed:', usageError);
+      }
+    }
+
+    // Dataverse org URL from the embedded environment metadata.
+    const instanceUrl = data.app?.properties?.environment?.properties?.linkedEnvironmentMetadata?.instanceUrl;
+    const dataverseOrgUrl = (instanceUrl ?? '').replace(/\/$/, '');
+    const resourceConsents = new Map();
+    const approvedResources = new Set((data.app?.properties?.userAppResourceConsent ?? []).filter(consent => consent.type?.toLowerCase() === 'auth' && consent.consent?.toLowerCase() === 'yes' && Boolean(consent.name)).map(consent => normalizeResourceConsentId(consent.name)));
+    for (const authorization of data.app?.properties?.authorizationReferences ?? []) {
+      if (authorization.resourceId && !approvedResources.has(normalizeResourceConsentId(authorization.resourceId))) {
+        const key = normalizeResourceConsentId(authorization.resourceId);
+        resourceConsents.set(key, {
+          resourceId: authorization.resourceId,
+          displayName: authorization.resourceId
+        });
+      }
+    }
+    for (const reference of Object.values(data.app?.properties?.databaseReferences ?? {})) {
+      const metadata = reference.databaseDetails?.linkedEnvironmentMetadata;
+      const resourceId = metadata?.instanceUrl;
+      if (resourceId && normalizeResourceConsentId(resourceId) !== normalizeResourceConsentId(dataverseOrgUrl) && !approvedResources.has(normalizeResourceConsentId(resourceId))) {
+        resourceConsents.set(normalizeResourceConsentId(resourceId), {
+          resourceId,
+          displayName: metadata?.friendlyName ?? resourceId
+        });
+      }
+    }
+
+    // connectorShortName → primaryRuntimeUrl  (from apis[])
+    const runtimeUrlByConnector = {};
+    const scopesByConnector = {};
+    for (const api of apisRaw) {
+      const connectorName = (0, _types2.getConnectorId)(api.name ?? '');
+      if (connectorName) {
+        scopesByConnector[connectorName] = {
+          will: api.properties?.scopes?.will ?? [],
+          wont: api.properties?.scopes?.wont ?? []
+        };
+      }
+      if (connectorName && api.properties?.primaryRuntimeUrl) {
+        runtimeUrlByConnector[connectorName] = api.properties.primaryRuntimeUrl;
+      }
+    }
+    const requiredConnectorNames = [...new Set(Object.values(connRefRaw).map(reference => reference.id ?? '').filter(apiId => apiId && (0, _types2.getConnectorId)(apiId) !== 'shared_excel').map(_types2.getConnectorId).filter(Boolean))];
+    await Promise.all(requiredConnectorNames.map(async connectorName => {
+      if (runtimeUrlByConnector[connectorName]) return;
+      const metadata = await fetchConnectorMetadata(connectorName, environmentId, region, token);
+      if (!metadata) return;
+      if (metadata.primaryRuntimeUrl) {
+        runtimeUrlByConnector[connectorName] = metadata.primaryRuntimeUrl;
+      }
+      if (!scopesByConnector[connectorName]) {
+        scopesByConnector[connectorName] = metadata.scopes;
+      }
+    }));
+
+    // Keep every connected instance. Selection is per local reference, not per
+    // connector, because one app can bind the same connector to two accounts.
+    const connectedByConnector = {};
+    for (const conn of connectionsRaw) {
+      const rawApiId = conn.properties?.apiId ?? '';
+      const connectorName = (0, _types2.getConnectorId)(rawApiId);
+      if (!connectorName || !conn.name) continue;
+      const isConnected = conn.properties?.statuses?.[0]?.status === 'Connected';
+      if (!isConnected) continue;
+      const candidates = connectedByConnector[connectorName] ?? [];
+      candidates.push({
+        id: (0, _disambiguate.extractConnectionId)(conn.name),
+        name: conn.name,
+        apiId: (0, _types2.normalizeApiId)(rawApiId),
+        ownerId: conn.properties?.createdBy?.id,
+        status: _types.ConnectionStatus.Connected,
+        displayName: conn.properties?.displayName,
+        isAuthenticated: true
+      });
+      connectedByConnector[connectorName] = candidates;
+    }
+    const connectionRefs = {};
+    const missingConnectors = [];
+    const missingConnectionReferences = [];
+    const connectionRequirements = [];
+    const connectionCandidates = {};
+    const missingRuntimeConnectors = new Set();
+    const rawConnectionReferences = {};
+    for (const [localRefId, reference] of Object.entries(connRefRaw)) {
+      if (!reference.id) continue;
+      rawConnectionReferences[localRefId] = {
+        ...reference,
+        id: reference.id,
+        dataSources: reference.dataSources ?? []
+      };
+    }
+    const requirementsByLocalRefId = Object.fromEntries((0, _types2.buildConnectionRequirements)(rawConnectionReferences, Object.fromEntries(Object.entries(scopesByConnector).map(([connectorId, scopes]) => [(0, _types2.normalizeApiId)(connectorId), scopes]))).map(requirement => [requirement.localRefId, requirement]));
+    for (const [localRefId, ref] of Object.entries(connRefRaw)) {
+      const rawId = ref.id ?? '';
+      const connectorName = (0, _types2.getConnectorId)(rawId);
+      if (!connectorName) continue;
+      if (connectorName === 'shared_logicflows') {
+        const flowReference = rawConnectionReferences[localRefId];
+        const runtimeUrl = runtimeUrlByConnector[connectorName] ?? '';
+        const connectionName = (0, _types2.getFlowConnectionName)(flowReference);
+        if (!runtimeUrl) missingRuntimeConnectors.add(connectorName);
+        if (!connectionName) missingRuntimeConnectors.add(`${connectorName}:workflow`);
+        const entry = {
+          apiId: (0, _types2.normalizeApiId)(rawId),
+          runtimeUrl,
+          connectionName,
+          datasetName: ''
+        };
+        for (const dataSource of (0, _types2.getFlowDataSourceNames)(flowReference)) {
+          connectionRefs[dataSource] = entry;
+        }
+        continue;
+      }
+      if ((0, _types2.isCompositeConnectionApiId)(rawId)) continue;
+      const runtimeUrl = runtimeUrlByConnector[connectorName] ?? '';
+      if (!runtimeUrl) missingRuntimeConnectors.add(connectorName);
+      const apiId = (0, _types2.normalizeApiId)(rawId);
+      const candidates = connectedByConnector[connectorName] ?? [];
+      connectionCandidates[localRefId] = candidates;
+      const preferredId = ref.sharedConnectionId ? (0, _disambiguate.extractConnectionId)(String(ref.sharedConnectionId)) : null;
+      const selected = preferredId ? candidates.find(candidate => (0, _disambiguate.connectionIdsEqual)(candidate.id, preferredId)) : candidates.length === 1 ? candidates[0] : undefined;
+      const connectionName = selected?.id ?? '';
+      const isDataverse = connectorName.includes('commondataserviceforapps');
+      const dataSources = ref.dataSources ?? [];
+      const requirement = requirementsByLocalRefId[localRefId];
+      if (!requirement) continue;
+      connectionRequirements.push(requirement);
+      if (!connectionName) {
+        missingConnectors.push(apiId);
+        missingConnectionReferences.push(requirement);
+      }
+      const entry = {
+        apiId,
+        runtimeUrl,
+        connectionName,
+        datasetName: isDataverse ? dataverseOrgUrl : (0, _types2.getConnectionDatasetName)(ref)
+      };
+      for (const ds of dataSources) {
+        connectionRefs[ds] = entry;
+      }
+    }
+    const conflictingDataSources = (0, _types2.findConnectionDataSourceConflicts)(connectionRequirements);
+    const result = {
+      connectionRefs,
+      dataverseOrgUrl,
+      databaseReferences: data.app?.properties?.databaseReferences ?? {},
+      missingConnectors,
+      missingConnectionReferences,
+      connectionRequirements,
+      connectionCandidates,
+      resourceConsents: [...resourceConsents.values()],
+      configurationErrors: conflictingDataSources.map(dataSource => `Data source "${dataSource}" is assigned to multiple connection references.`).concat([...missingRuntimeConnectors].map(connectorName => connectorName.endsWith(':workflow') ? 'The Flow connection reference is missing its workflow identifier in Power Platform metadata.' : `Connector "${connectorName}" is missing its runtime URL in Power Platform metadata.`)),
+      registeredConnectionUsages,
+      requiresConnectionConsent: true
+    };
+    (0, _connectionState.applyRegisteredConnectionUsages)(result, registeredConnectionUsages);
+    if (result.requiresConnectionConsent && !fetchedConnectionUsages) {
+      try {
+        registeredConnectionUsages = await fetchAppConnectionUsages(appId, environmentId, region, token);
+        fetchedConnectionUsages = true;
+        (0, _connectionState.applyRegisteredConnectionUsages)(result, registeredConnectionUsages);
+      } catch (usageError) {
+        (0, _logger.debugWarn)('[fetchAppLaunchData] could not refresh unmatched app connections:', usageError);
+      }
+    }
+    const unmatchedRequirements = (0, _connectionState.getUnregisteredConnectionRequirements)(result);
+    (0, _logger.debugLog)('[fetchAppLaunchData] consent evaluation', JSON.stringify({
+      launchUsageCount: launchConnectionUsages.length,
+      persistedUsageCount: registeredConnectionUsages.length,
+      fetchedConnectionUsages,
+      unmatchedReferences: unmatchedRequirements.map(requirement => ({
+        reference: requirement.localRefId,
+        connectorId: requirement.connectorId,
+        requiredActions: requirement.appActions ?? [],
+        persistedActions: registeredConnectionUsages.filter(usage => usage.reference.toLowerCase() === requirement.localRefId.toLowerCase() && (0, _types2.normalizeApiId)(usage.apiId) === requirement.apiId).flatMap(usage => usage.appActions)
+      })),
+      pendingResourceConsentCount: result.resourceConsents.length
+    }));
+    return result;
+  } catch (error) {
+    throw new Error(`The Power Platform app launch response was invalid: ${String(error)}`);
+  }
+}
+
+/**
+ * Grant the calling application's delegated access to a connection for the
+ * signed-in user. The backend derives both identities from the token and
+ * selects the most specific applicable user, group, or tenant ACL.
+ */
+async function grantConnectionUserConsent(connectorId, connectionId, environmentId, region, token) {
+  const url = (0, _connectionMetadata.buildConnectionUserConsentUrl)((0, _PowerPlatformEnvironmentApi.buildEnvironmentEndpoint)(environmentId, region), connectorId, connectionId);
+  (0, _logger.debugLog)('[grantConnectionUserConsent] POST', url);
+  try {
+    const maxAttempts = 2;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+      const res = await _index.platformHttpClient.request(url, {
+        method: 'POST',
+        headers: {
+          Authorization: `Bearer ${token}`
+        }
+      });
+      const resText = await res.text().catch(() => '');
+      (0, _logger.debugLog)(`[grantConnectionUserConsent] HTTP ${res.status}`, resText);
+      if (res.ok) return true;
+      const isTransient = (0, _connectionState.isTransientConnectionConsentStatus)(res.status);
+      if (isTransient && attempt < maxAttempts) {
+        (0, _logger.debugLog)(`[grantConnectionUserConsent] transient HTTP ${res.status} for connection ${connectionId}; retrying`);
+        await new Promise(resolve => setTimeout(resolve, 500));
+        continue;
+      }
+      (0, _logger.debugWarn)(`[grantConnectionUserConsent] failed HTTP ${res.status} for connection ${connectionId}: ${resText}`);
+      (0, _index.getAppLogger)().trackErrorEvent(_index.HostOperationNames.PlatformConnectionAclGrant, {
+        phase: 'grantConnectionUserConsent',
+        reason: 'httpError',
+        httpStatus: res.status,
+        ...(0, _http.getHttpCorrelationProperties)(res.headers)
+      });
+      return false;
+    }
+    return false;
+  } catch (error) {
+    (0, _logger.debugWarn)('[grantConnectionUserConsent] error:', error);
+    (0, _index.getAppLogger)().trackErrorEvent(_index.HostOperationNames.PlatformConnectionAclGrant, {
+      phase: 'grantConnectionUserConsent',
+      reason: 'exception'
+    });
+    return false;
+  }
+}