@microsoft/power-apps-native-host 0.2.22

package/lib/module/bridge/setupNativeHost.js

@@ -0,0 +1,62 @@
+"use strict";
+
+/*!
+ * power-apps-native-host — setupNativeHost
+ *
+ * Registers a NativePowerAppsBridge on the JS global (globalThis.powerAppsBridge)
+ * so the @microsoft/power-apps SDK picks it up automatically on the first data
+ * operation. The SDK reads globalThis.powerAppsBridge in getBridge() before
+ * falling back to the web DefaultPowerAppsBridge.
+ *
+ * Call this once at app root before any data operations. Re-calling with updated
+ * options (e.g. when connections change) is safe — it updates the existing bridge
+ * in-place without resetting the SDK's cached bridge promise.
+ */
+
+import { NativePowerAppsBridge } from "./NativePowerAppsBridge.js";
+import { debugLog } from "../logger.js";
+
+/** The single bridge instance for the lifetime of the app. */
+let _bridge;
+
+/**
+ * Registers a NativePowerAppsBridge for all @microsoft/power-apps SDK calls.
+ *
+ * On first call, creates a NativePowerAppsBridge and injects it into
+ * `globalThis.powerAppsBridge`. Subsequent calls update the bridge's options
+ * in-place so connection references and data sources can change without
+ * rebuilding the bridge (important because the SDK caches the bridge instance
+ * after first use).
+ *
+ * Idempotent with the same options reference — no-op if nothing changed.
+ *
+ * @example
+ * ```ts
+ * // App.tsx (root)
+ * import { setupNativeHost } from '@microsoft/power-apps-native-host';
+ *
+ * setupNativeHost({
+ *   getConnectorToken: (apiId) => msalClient.acquireToken({ resource: apiId }),
+ *   getDataverseToken: (datasetName) => msalClient.acquireToken({ resource: datasetName }),
+ *   dataSources: appManifest.dataSources,
+ *   connections: appManifest.connections,
+ * });
+ * ```
+ */
+export function setupNativeHost(options) {
+  if (_bridge) {
+    // Bridge already created — update options in-place. The SDK caches the
+    // bridge instance via bridgePromise, so replacing globalThis.powerAppsBridge
+    // would have no effect after the first data operation.
+    debugLog('[bridge] setupNativeHost: updating existing bridge options');
+    _bridge.updateOptions(options);
+  } else {
+    debugLog('[bridge] setupNativeHost: creating NativePowerAppsBridge and injecting into globalThis');
+    _bridge = new NativePowerAppsBridge(options);
+    // Inject into the JS global so the SDK finds it in getBridge().
+    // In browsers, globalThis === window, so window.powerAppsBridge also resolves.
+    // In React Native, globalThis is the Hermes global object.
+    globalThis.powerAppsBridge = _bridge;
+    debugLog('[bridge] setupNativeHost: bridge ready');
+  }
+}

package/lib/module/connections/ConnectionSetupScreen.js

@@ -0,0 +1,526 @@
+"use strict";
+
+/*!
+ * power-apps-native-host — ConnectionSetupScreen
+ *
+ * A ready-made React Native screen that drives the "create missing connections"
+ * flow before the Power Apps player is shown.
+ *
+ * Intended usage in an expo-router layout:
+ *
+ *   // app/(app)/_layout.tsx
+ *   import { ConnectionSetupScreen } from '@microsoft/power-apps-native-host';
+ *
+ *   if (missingConnectors.length > 0) {
+ *     return (
+ *       <ConnectionSetupScreen
+ *         missingConnectors={missingConnectors}    // from useConnectionRefs
+ *         schemaMap={schemaMap}
+ *         environmentId={powerConfig.environmentId}
+ *         region={powerConfig.region}
+ *         acquireToken={acquireToken}
+ *         onAllConnected={(resolvedIds) => {
+ *           // resolvedIds: Record<apiId, connectionId>
+ *           // Store them, then set missingConnectors = [] to unmount this screen.
+ *         }}
+ *         onSkip={() => { ... }}   // optional — hide skip button if not provided
+ *       />
+ *     );
+ *   }
+ *
+ * What the screen does for each missing connector, in order:
+ *   1. Shows connector name / description (fetched from API).
+ *   2. "Connect" button → calls createConnection → shows an in-app WebView
+ *      with the OAuth consent URL.
+ *   3. "Done" button in WebView header → calls checkNow() to confirm status.
+ *   4. On Connected → advances to the next missing connector.
+ *   5. When all connectors are resolved → calls onAllConnected.
+ *
+ * The component has zero production dependencies beyond react-native.
+ * It purposely does NOT depend on expo-router or any navigation library —
+ * the consuming app decides how to render it (full-screen, modal, etc.).
+ */
+
+import React, { useState, useEffect, useCallback } from 'react';
+import { View, Text, TouchableOpacity, ActivityIndicator, StyleSheet, ScrollView } from 'react-native';
+import * as WebBrowser from 'expo-web-browser';
+import * as Linking from 'expo-linking';
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { useConnectionSetup } from "../connections/useConnectionSetup.js";
+import { fetchConnectorMetadata, fetchConnectionsForConnector } from "../platform/PowerPlatformConnectionApi.js";
+import { powerPlatformScope } from "../platform/PowerPlatformEnvironmentApi.js";
+import { ConnectionStatus } from "../connections/types.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Internal helper: ConnectorSetupStep
+// Sets up a single connector and reports back via onConnected.
+// ---------------------------------------------------------------------------
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+function ConnectorSetupStep({
+  connectorId,
+  apiId,
+  environmentId,
+  region,
+  acquireToken,
+  isvClientId,
+  onConnected,
+  renderOAuthWebView
+}) {
+  // Derive the OAuth redirect URL from the app's registered scheme at runtime.
+  // expo-linking.createURL resolves to e.g. "myapp://oauth-callback" using
+  // whatever scheme the host app has registered — works universally without
+  // any configuration by the consuming app.
+  const oauthRedirectUrl = Linking.createURL('oauth-callback');
+
+  // Local UI state for the metadata-loading phase. Kept here (not in
+  // useConnectionSetup) so the hook stays focused on connection flow only.
+  const [isLoadingMetadata, setIsLoadingMetadata] = useState(true);
+  const [metadata, setMetadata] = useState(null);
+  const [showOAuthModal, setShowOAuthModal] = useState(false);
+  // Track if there's already a connected instance the user can reuse.
+  const [existingConnected, setExistingConnected] = useState(null);
+  const setup = useConnectionSetup({
+    connectorId,
+    environmentId,
+    region,
+    acquireToken,
+    isvClientId,
+    onConnected: instance => {
+      setShowOAuthModal(false);
+      onConnected(apiId, instance);
+    },
+    oauthRedirectUrl,
+    polling: {
+      intervalMs: 2000,
+      timeoutMs: 120_000
+    }
+  });
+
+  // Fetch connector metadata and check for existing non-connected connections.
+  useEffect(() => {
+    let cancelled = false;
+    async function load() {
+      const token = await acquireToken([powerPlatformScope(region)]);
+      if (!token || cancelled) {
+        if (!cancelled) {
+          setMetadata({
+            displayName: connectorId,
+            iconUri: '',
+            description: ''
+          });
+          setIsLoadingMetadata(false);
+        }
+        return;
+      }
+      const [meta, instances] = await Promise.all([fetchConnectorMetadata(connectorId, environmentId, region, token), fetchConnectionsForConnector(connectorId, environmentId, region, token)]);
+      if (cancelled) return;
+      setMetadata(meta ?? {
+        displayName: connectorId,
+        iconUri: '',
+        description: ''
+      });
+
+      // If there's already a Connected instance the disambiguation didn't pick
+      // (e.g., appeared after the initial load), use it directly.
+      const connected = instances.find(i => i.status === ConnectionStatus.Connected);
+      if (connected) setExistingConnected(connected);
+      setIsLoadingMetadata(false);
+    }
+    void load();
+    return () => {
+      cancelled = true;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [connectorId]);
+  const handleUseExisting = useCallback(() => {
+    if (existingConnected) {
+      onConnected(apiId, existingConnected);
+    }
+  }, [existingConnected, apiId, onConnected]);
+  const handleConnect = useCallback(async () => {
+    await setup.startCreate();
+  }, [setup]);
+
+  // Open OAuth UI when consentUrl becomes available (set by startCreate in the hook).
+  useEffect(() => {
+    if (setup.phase === 'oauth' && setup.consentUrl) {
+      if (renderOAuthWebView) {
+        setShowOAuthModal(true);
+      } else {
+        // Default: open an in-app browser session.
+        // openAuthSessionAsync auto-dismisses when the OS intercepts the
+        // custom-scheme redirect (e.g. expo-app://oauth-callback).
+        void (async () => {
+          const result = await WebBrowser.openAuthSessionAsync(setup.consentUrl, oauthRedirectUrl);
+          // Extract a CommitTokenCode from the redirect URL if present.
+          let code;
+          if (result.type === 'success' && result.url) {
+            const params = new URL(result.url).searchParams;
+            const raw = params.get('code') ?? '';
+            // CommitTokenCode is a 32-char lowercase hex string.
+            if (/^[0-9a-f]{32}$/i.test(raw)) {
+              code = raw;
+            }
+          }
+          await setup.completeConsent(code);
+        })();
+      }
+    }
+  }, [setup.phase, setup.consentUrl, renderOAuthWebView, oauthRedirectUrl]);
+  const handleWebViewDismiss = useCallback(async () => {
+    setShowOAuthModal(false);
+    await setup.checkNow();
+  }, [setup]);
+  const displayName = metadata?.displayName ?? connectorId;
+  const description = metadata?.description ?? '';
+  if (isLoadingMetadata) {
+    return /*#__PURE__*/_jsx(View, {
+      style: styles.connectorCard,
+      children: /*#__PURE__*/_jsx(View, {
+        style: styles.metadataLoading,
+        children: /*#__PURE__*/_jsx(ActivityIndicator, {
+          size: "small"
+        })
+      })
+    });
+  }
+  return /*#__PURE__*/_jsxs(View, {
+    style: styles.connectorCard,
+    children: [/*#__PURE__*/_jsx(Text, {
+      style: styles.connectorName,
+      children: displayName
+    }), description ? /*#__PURE__*/_jsx(Text, {
+      style: styles.connectorDescription,
+      children: description
+    }) : null, setup.phase === 'idle' && /*#__PURE__*/_jsx(_Fragment, {
+      children: existingConnected ? /*#__PURE__*/_jsxs(View, {
+        style: styles.buttonRow,
+        children: [/*#__PURE__*/_jsx(TouchableOpacity, {
+          style: [styles.button, styles.buttonSecondary],
+          onPress: handleUseExisting,
+          children: /*#__PURE__*/_jsx(Text, {
+            style: styles.buttonTextSecondary,
+            children: "Use existing"
+          })
+        }), /*#__PURE__*/_jsx(TouchableOpacity, {
+          style: styles.button,
+          onPress: handleConnect,
+          children: /*#__PURE__*/_jsx(Text, {
+            style: styles.buttonText,
+            children: "Create new"
+          })
+        })]
+      }) : /*#__PURE__*/_jsx(TouchableOpacity, {
+        style: styles.button,
+        onPress: handleConnect,
+        children: /*#__PURE__*/_jsx(Text, {
+          style: styles.buttonText,
+          children: "Connect"
+        })
+      })
+    }), (setup.phase === 'creating' || setup.phase === 'confirming') && /*#__PURE__*/_jsxs(View, {
+      style: styles.statusRow,
+      children: [/*#__PURE__*/_jsx(ActivityIndicator, {
+        size: "small",
+        color: "#0078D4"
+      }), /*#__PURE__*/_jsx(Text, {
+        style: styles.statusText,
+        children: setup.phase === 'creating' ? 'Creating connection…' : 'Confirming…'
+      })]
+    }), setup.phase === 'oauth' && /*#__PURE__*/_jsxs(View, {
+      style: styles.statusRow,
+      children: [/*#__PURE__*/_jsx(ActivityIndicator, {
+        size: "small",
+        color: "#0078D4"
+      }), /*#__PURE__*/_jsx(Text, {
+        style: styles.statusText,
+        children: "Waiting for sign-in\u2026"
+      }), /*#__PURE__*/_jsx(TouchableOpacity, {
+        onPress: handleWebViewDismiss,
+        children: /*#__PURE__*/_jsx(Text, {
+          style: styles.linkText,
+          children: "Done"
+        })
+      })]
+    }), setup.phase === 'connected' && /*#__PURE__*/_jsx(View, {
+      style: styles.statusRow,
+      children: /*#__PURE__*/_jsx(Text, {
+        style: styles.successText,
+        children: "\u2713 Connected"
+      })
+    }), setup.phase === 'error' && /*#__PURE__*/_jsxs(View, {
+      children: [/*#__PURE__*/_jsx(Text, {
+        style: styles.errorText,
+        children: setup.errorMessage ?? 'Connection failed'
+      }), /*#__PURE__*/_jsx(TouchableOpacity, {
+        style: [styles.button, styles.buttonDanger],
+        onPress: setup.reset,
+        children: /*#__PURE__*/_jsx(Text, {
+          style: styles.buttonText,
+          children: "Retry"
+        })
+      })]
+    }), showOAuthModal && setup.consentUrl && renderOAuthWebView ? renderOAuthWebView(setup.consentUrl, handleWebViewDismiss) : null]
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main screen component
+// ---------------------------------------------------------------------------
+
+/**
+ * Full-screen component that steps the user through creating each missing
+ * connection before the Power Apps player is launched.
+ *
+ * The screen works through missing connectors sequentially.  Once all are
+ * resolved `onAllConnected` fires and the parent app should unmount this
+ * component and proceed to launch the app.
+ */
+export function ConnectionSetupScreen({
+  missingConnectors,
+  schemaMap,
+  environmentId,
+  region = 'prod',
+  acquireToken,
+  isvClientId,
+  onAllConnected,
+  onSkip,
+  renderOAuthWebView,
+  title = 'Set up connections'
+}) {
+  // resolvedIds accumulates as each connector is connected.
+  const [resolvedIds, setResolvedIds] = useState({});
+  const insets = useSafeAreaInsets();
+
+  // Build connectorId (short name) for each missing entry from the schemaMap.
+  // schemaMap keys are data source names; we need to find the ConnectorSchema
+  // whose apiId matches each missing connector's apiId.
+  const connectorIdByApiId = React.useMemo(() => {
+    const map = {};
+    for (const schema of Object.values(schemaMap)) {
+      // The schemaMap doesn't directly store apiId — we reconstruct it.
+      // Convention: connectorId = schema.name (e.g. "shared_office365users")
+      // apiId = "/providers/Microsoft.PowerApps/apis/shared_office365users"
+      const derivedApiId = `/providers/Microsoft.PowerApps/apis/${schema.name}`;
+      map[derivedApiId] = schema.name;
+    }
+    return map;
+  }, [schemaMap]);
+  const handleConnected = useCallback((apiId, instance) => {
+    setResolvedIds(prev => ({
+      ...prev,
+      [apiId]: instance.id
+    }));
+  }, []);
+
+  // Fire onAllConnected once every connector has been resolved.
+  // Done in an effect so it never runs inside a state updater (which would
+  // trigger the "Cannot update a component while rendering" React error).
+  useEffect(() => {
+    if (missingConnectors.length === 0) return;
+    const allResolved = missingConnectors.every(mc => resolvedIds[mc.apiId] !== undefined);
+    if (allResolved) {
+      onAllConnected(resolvedIds);
+    }
+  }, [resolvedIds, missingConnectors, onAllConnected]);
+  const resolvedCount = Object.keys(resolvedIds).length;
+  const total = missingConnectors.length;
+  return /*#__PURE__*/_jsxs(View, {
+    style: [styles.container, {
+      paddingTop: insets.top,
+      paddingBottom: insets.bottom
+    }],
+    children: [/*#__PURE__*/_jsxs(ScrollView, {
+      contentContainerStyle: styles.scrollContent,
+      children: [/*#__PURE__*/_jsx(Text, {
+        style: styles.title,
+        children: title
+      }), /*#__PURE__*/_jsxs(Text, {
+        style: styles.subtitle,
+        children: ["This app needs ", total === 1 ? 'a connection' : `${total} connections`, " to work. Sign in to each service below to continue."]
+      }), resolvedCount > 0 && /*#__PURE__*/_jsxs(Text, {
+        style: styles.progressText,
+        children: [resolvedCount, " of ", total, " connected"]
+      }), missingConnectors.map(mc => {
+        const connectorId = connectorIdByApiId[mc.apiId];
+        if (!connectorId) {
+          // Unknown connector — skip rendering.
+          return null;
+        }
+        const isResolved = resolvedIds[mc.apiId] !== undefined;
+        if (isResolved) {
+          return /*#__PURE__*/_jsx(View, {
+            style: [styles.connectorCard, styles.connectorCardResolved],
+            children: /*#__PURE__*/_jsxs(Text, {
+              style: styles.successText,
+              children: ["\u2713 ", connectorId.replace('shared_', '')]
+            })
+          }, mc.apiId);
+        }
+        return /*#__PURE__*/_jsx(ConnectorSetupStep, {
+          connectorId: connectorId,
+          apiId: mc.apiId,
+          environmentId: environmentId,
+          region: region,
+          acquireToken: acquireToken,
+          isvClientId: isvClientId,
+          onConnected: handleConnected,
+          renderOAuthWebView: renderOAuthWebView
+        }, mc.apiId);
+      })]
+    }), onSkip ? /*#__PURE__*/_jsx(View, {
+      style: styles.footer,
+      children: /*#__PURE__*/_jsx(TouchableOpacity, {
+        onPress: onSkip,
+        style: styles.skipButton,
+        children: /*#__PURE__*/_jsx(Text, {
+          style: styles.skipText,
+          children: "Skip for now"
+        })
+      })
+    }) : null]
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Styles
+// ---------------------------------------------------------------------------
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    backgroundColor: '#F8F8F8'
+  },
+  scrollContent: {
+    padding: 20,
+    paddingBottom: 40
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: '700',
+    color: '#1A1A1A',
+    marginBottom: 8
+  },
+  subtitle: {
+    fontSize: 15,
+    color: '#555',
+    marginBottom: 24,
+    lineHeight: 22
+  },
+  progressText: {
+    fontSize: 13,
+    color: '#0078D4',
+    fontWeight: '600',
+    marginBottom: 16
+  },
+  connectorCard: {
+    backgroundColor: '#FFF',
+    borderRadius: 12,
+    padding: 16,
+    marginBottom: 12,
+    minHeight: 80,
+    shadowColor: '#000',
+    shadowOffset: {
+      width: 0,
+      height: 1
+    },
+    shadowOpacity: 0.06,
+    shadowRadius: 4,
+    elevation: 2
+  },
+  connectorCardResolved: {
+    backgroundColor: '#F0FFF4',
+    borderColor: '#34A853',
+    borderWidth: 1
+  },
+  connectorName: {
+    fontSize: 16,
+    fontWeight: '600',
+    color: '#1A1A1A',
+    marginBottom: 4
+  },
+  connectorDescription: {
+    fontSize: 13,
+    color: '#666',
+    marginBottom: 12,
+    lineHeight: 18
+  },
+  buttonRow: {
+    flexDirection: 'row',
+    gap: 8
+  },
+  button: {
+    flex: 1,
+    backgroundColor: '#0078D4',
+    borderRadius: 8,
+    paddingVertical: 10,
+    alignItems: 'center',
+    marginTop: 8
+  },
+  buttonSecondary: {
+    backgroundColor: '#EFF6FC'
+  },
+  buttonDanger: {
+    backgroundColor: '#C4262E'
+  },
+  buttonText: {
+    color: '#FFF',
+    fontWeight: '600',
+    fontSize: 14
+  },
+  buttonTextSecondary: {
+    color: '#0078D4',
+    fontWeight: '600',
+    fontSize: 14
+  },
+  statusRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 8,
+    marginTop: 8
+  },
+  statusText: {
+    fontSize: 14,
+    color: '#555',
+    flex: 1
+  },
+  linkText: {
+    fontSize: 14,
+    color: '#0078D4',
+    fontWeight: '600'
+  },
+  successText: {
+    fontSize: 14,
+    color: '#34A853',
+    fontWeight: '600'
+  },
+  errorText: {
+    fontSize: 13,
+    color: '#C4262E',
+    marginBottom: 8
+  },
+  footer: {
+    padding: 16,
+    borderTopWidth: StyleSheet.hairlineWidth,
+    borderTopColor: '#E0E0E0',
+    backgroundColor: '#FFF'
+  },
+  skipButton: {
+    alignItems: 'center',
+    paddingVertical: 12
+  },
+  skipText: {
+    fontSize: 15,
+    color: '#888'
+  },
+  metadataLoading: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+    minHeight: 48
+  }
+});

package/lib/module/connections/disambiguate.js

@@ -0,0 +1,83 @@
+"use strict";
+
+/*!
+ * power-apps-native-host — connection disambiguation logic
+ *
+ * Pure function that matches power.config.json connectionReferences to the
+ * connection instances available in the user's Power Platform environment.
+ *
+ * Mirrors the core of ConnectionPipeline.matchConnectionsToUsages in the web
+ * host but is self-contained — it does not require IConnectionService or any
+ * other web-host dependency.
+ */
+
+import { ConnectionStatus } from "./types.js";
+/**
+ * Disambiguate a set of connection references against the user's available
+ * connection instances.
+ *
+ * Rules (in priority order):
+ *  1. If exactly one `Connected` connection matches the reference apiId → resolved.
+ *  2. If zero connections match (or none are Connected) → missing.
+ *  3. If multiple Connected connections match → ambiguous (needs user pick).
+ *
+ * @param connectionReferences  The `connectionReferences` object from power.config.json,
+ *                              keyed by local reference ID.
+ * @param allConnectionsByApiId All connection instances fetched from the
+ *                              Power Platform connectivity API, keyed by
+ *                              connector apiId.
+ */
+export function disambiguateConnections(connectionReferences, allConnectionsByApiId) {
+  const resolutions = [];
+  for (const [localRefId, ref] of Object.entries(connectionReferences)) {
+    const apiId = ref.id;
+    const all = allConnectionsByApiId[apiId] ?? [];
+    const connected = all.filter(c => c.status === ConnectionStatus.Connected);
+    let result;
+    if (connected.length === 1) {
+      result = {
+        kind: 'resolved',
+        connectionId: connected[0].id
+      };
+    } else if (connected.length === 0) {
+      result = {
+        kind: 'missing'
+      };
+    } else {
+      // Multiple Connected connections — needs user pick.
+      result = {
+        kind: 'ambiguous',
+        candidates: connected
+      };
+    }
+    resolutions.push({
+      localRefId,
+      apiId,
+      dataSources: ref.dataSources,
+      result
+    });
+  }
+  return resolutions;
+}
+
+/**
+ * Extract the connection UUID from a raw connection name returned by the API.
+ *
+ * The API returns names like:
+ *   "shared_office365users/abc12345def6789012345678901234ab"  (connector-prefixed)
+ *   "abc12345def6789012345678901234ab"                        (bare UUID, no dashes)
+ *   "abc12345-def6-7890-1234-5678901234ab"                   (UUID with dashes)
+ *
+ * Returns the 32-char hex ID (dashes stripped) or the raw string if no UUID
+ * pattern is found.
+ */
+export function extractConnectionId(rawName) {
+  // Match a standard UUID (with or without dashes) at the end of the string.
+  const match = rawName.match(/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i);
+  if (match) {
+    return match[1].replace(/-/g, '');
+  }
+  // Some connections use a 32-char hex ID without dashes, after a slash.
+  const slashIdx = rawName.lastIndexOf('/');
+  return slashIdx >= 0 ? rawName.slice(slashIdx + 1) : rawName;
+}