@microsoft/power-apps-native-host 0.2.22

package/lib/typescript/commonjs/controls/ImagePicker.d.ts

@@ -0,0 +1,76 @@
+import React from 'react';
+import { type StyleProp, type ViewStyle, type TextStyle, type ImageStyle } from 'react-native';
+import * as ExpoImagePicker from 'expo-image-picker';
+export interface PickedImageInfo {
+    uri: string;
+    name: string;
+    mimeType: string;
+    base64: string;
+    /** File-compatible object ready for generated Dataverse upload methods. */
+    file: File;
+    /** Raw bytes of the image, ready to pass to lower-level upload APIs. */
+    bytes: Uint8Array;
+}
+export interface ImagePickerProps {
+    label?: string;
+    /**
+     * Base64 string from Dataverse (the `cr_assetimage` thumbnail).
+     * The component builds the preview data URI internally.
+     * Pass `null` / `undefined` when there is no existing image.
+     */
+    initialBase64?: string | null;
+    /**
+     * Called when the user picks a new image.
+     * Receives the base64-encoded string, ready to include in a Dataverse PATCH body.
+     * Called with `null` if the user clears the image (future use).
+     */
+    onChange?: (base64: string | null) => void;
+    /** Called when the user picks a new image. Includes a generated-service-ready File object. */
+    onImageChange?: (image: PickedImageInfo | null) => void;
+    /** File name used when the selected image asset does not provide one. */
+    imageFileName?: string;
+    /** JPEG/PNG compression quality passed to expo-image-picker. Defaults to 0.8. */
+    quality?: number;
+    /** Enable the platform image editor after selecting or taking a photo. Defaults to false. */
+    allowsEditing?: boolean;
+    /** Android-only crop aspect ratio used when `allowsEditing` is true. */
+    aspect?: [number, number];
+    /** Android-only crop shape used when `allowsEditing` is true. */
+    cropShape?: ExpoImagePicker.CropShape;
+    /** Include EXIF metadata in the Expo picker asset. Defaults to false. */
+    exif?: boolean;
+    /** Use Android's legacy media picker. Defaults to false. */
+    legacy?: boolean;
+    /** Override the camera button label. */
+    cameraButtonLabel?: string;
+    /** Override the initial image-library button label. */
+    selectButtonLabel?: string;
+    /** Override the image-library button label after an image exists. */
+    changeButtonLabel?: string;
+    /** Override the button label while the picked image is being read. */
+    readingLabel?: string;
+    /** Override the outer container (adds margin below by default). */
+    containerStyle?: StyleProp<ViewStyle>;
+    /** Override the label text style. */
+    labelStyle?: StyleProp<TextStyle>;
+    /** Override the button row container. */
+    buttonRowStyle?: StyleProp<ViewStyle>;
+    /** Override each button container. */
+    buttonStyle?: StyleProp<ViewStyle>;
+    /** Override each button text. */
+    buttonTextStyle?: StyleProp<TextStyle>;
+    /** Override the image preview. */
+    previewStyle?: StyleProp<ImageStyle>;
+    /** Accent colour used for icons, borders and text. Defaults to `'#0078d4'`. */
+    accentColor?: string;
+}
+/**
+ * A self-contained image picker that shows a preview and lets the user
+ * choose a new image from the library. Works on Android and iOS.
+ *
+ * - Existing images are seeded from a Dataverse base64 string via `initialBase64`.
+ * - On pick, the image is returned as base64 for legacy callers and as a
+ *   File-compatible object for generated Dataverse upload methods.
+ */
+export declare function ImagePicker({ label, initialBase64, onChange, containerStyle, labelStyle, buttonRowStyle, buttonStyle, buttonTextStyle, previewStyle, accentColor, onImageChange, imageFileName, quality, allowsEditing, aspect, cropShape, exif, legacy, cameraButtonLabel, selectButtonLabel, changeButtonLabel, readingLabel, }: ImagePickerProps): React.JSX.Element;
+//# sourceMappingURL=ImagePicker.d.ts.map

package/lib/typescript/commonjs/index.d.ts

@@ -0,0 +1,42 @@
+/*!
+ * power-apps-native-host
+ * React Native host integration for @microsoft/power-apps
+ *
+ */
+export { NativePowerAppsBridge } from './bridge/NativePowerAppsBridge';
+export type { NativeBridgeOptions, CdsDataSourceConfig, AppConnection, AppConnectionReference } from './bridge/NativePowerAppsBridge';
+export { buildConnectionReferences } from './bridge/NativePowerAppsBridge';
+export { setupNativeHost } from './bridge/setupNativeHost';
+export { AuthProvider, useAuth } from './auth/AuthContext';
+export type { AuthState, AuthProviderProps } from './auth/AuthContext';
+export type { AuthConfig, MsalAuthConfig, IntuneConfig } from '@microsoft/power-apps-native-auth';
+export { PowerAppsHostProvider } from './provider/PowerAppsHostProvider';
+export type { PowerAppsHostProviderProps } from './provider/PowerAppsHostProvider';
+export { PowerAppsProvider } from './provider/PowerAppsProvider';
+export type { PowerAppsProviderProps, PowerConfig } from './provider/PowerAppsProvider';
+export { fetchInstanceUrl, buildCdsDataSources, buildEnvironmentEndpoint, POWER_PLATFORM_API_SCOPE } from './platform/PowerPlatformEnvironmentApi';
+export type { LinkedEnvironmentMetadata, DatabaseReference, DatabaseReferenceDataSource } from './platform/PowerPlatformEnvironmentApi';
+export { useConnectionRefs } from './platform/useConnectionRefs';
+export type { UseConnectionRefsOptions, UseConnectionRefsResult, ConnectorSchema } from './platform/useConnectionRefs';
+export { fetchConnectorMetadata, fetchConnectionsForConnector, createConnection, pollConnectionStatus, confirmConsentCode, fetchAppLaunchData, } from './platform/PowerPlatformConnectionApi';
+export type { ConnectorMetadata, CreateConnectionResult, AppLaunchResult, } from './platform/PowerPlatformConnectionApi';
+export { disambiguateConnections, extractConnectionId } from './connections/disambiguate';
+export type { NativeConnectionInstance, NativeConnectionResolution, NativeDisambiguationResult, OnDisambiguationNeeded, OnMissingConnection, } from './connections/types';
+export { useConnectionSetup } from './connections/useConnectionSetup';
+export type { ConnectionSetupPhase, UseConnectionSetupOptions, UseConnectionSetupResult, } from './connections/useConnectionSetup';
+export { ConnectionSetupScreen } from './connections/ConnectionSetupScreen';
+export type { MissingConnectorEntry, ConnectionSetupScreenProps, } from './connections/ConnectionSetupScreen';
+export { ThemeProvider, useThemeTokens, useThemeControl } from './theme/ThemeProvider';
+export type { ThemeProviderProps, ThemeControl } from './theme/ThemeProvider';
+export { lightTheme, darkTheme } from './theme/tokens';
+export type { ThemeTokens } from './theme/tokens';
+export { FilePicker } from './controls/FilePicker';
+export type { FilePickerProps, PickedFileInfo } from './controls/FilePicker';
+export { ImagePicker } from './controls/ImagePicker';
+export type { ImagePickerProps, PickedImageInfo } from './controls/ImagePicker';
+export { isDevPlayer } from './utils/isDevPlayer';
+export { base64ToDataverseUploadFile, base64ToUint8Array, createDataverseUploadFile, } from './utils/dataverseUtils';
+export { getAppLogger, configureAppLogger, HostOperationNames } from './telemetry';
+export type { ILogger } from '@microsoft/power-apps-native-common';
+export { ErrorBoundary } from './ErrorBoundary';
+//# sourceMappingURL=index.d.ts.map

package/lib/typescript/commonjs/logger.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Conditional debug logger for power-apps-native-host.
+ *
+ * Debug logs (debugLog / debugWarn) are only emitted when the JS bundle
+ * is running inside the Power Apps Dev Player (detected via
+ * `Constants.expoConfig.extra.isDevPlayer`).  They are silenced in release
+ * APKs generated from the template so the production log stream stays clean.
+ */
+export declare function debugLog(...args: unknown[]): void;
+export declare function debugWarn(...args: unknown[]): void;
+//# sourceMappingURL=logger.d.ts.map

package/lib/typescript/commonjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/lib/typescript/commonjs/platform/PowerPlatformConnectionApi.d.ts

@@ -0,0 +1,205 @@
+/*!
+ * 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.
+ */
+import type { NativeConnectionInstance } from '../connections/types';
+import type { AppConnectionReference } from '../bridge/NativePowerAppsBridge';
+/**
+ * Token scope for the Power Apps RP (api.powerapps.com).
+ * Required when calling modifyPermissions to register a service principal
+ * in the connection ACE so that APIM accepts third-party app tokens at runtime.
+ */
+export declare const SERVICE_POWERAPPS_SCOPE = "https://service.powerapps.com/.default";
+/** Subset of connector metadata returned by the Power Platform API. */
+export interface ConnectorMetadata {
+    /** Short connector name, e.g. "shared_office365users". */
+    name: string;
+    /** Connector display name, e.g. "Office 365 Users". */
+    displayName: string;
+    /** URL of the connector icon. */
+    iconUri: string;
+    /** Description text. */
+    description: string;
+    /** Whether this is a first-party (Microsoft-published) connector. */
+    isFirstParty: boolean;
+}
+/**
+ * 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.
+ */
+export declare function fetchConnectorMetadata(connectorId: string, environmentId: string, region: string, token: string): Promise<ConnectorMetadata | null>;
+/**
+ * Fetch all connections for a given connector in the environment.
+ * Returns only the `NativeConnectionInstance` shape used by the disambiguation layer.
+ */
+export declare function fetchConnectionsForConnector(connectorId: string, environmentId: string, region: string, token: string): Promise<NativeConnectionInstance[]>;
+/**
+ * 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 was created and is already Connected (e.g.,
+ *   first-party SSO connections that do not need explicit OAuth consent).
+ *
+ * `error` — creation failed; `message` contains the error description.
+ */
+export type CreateConnectionResult = {
+    status: 'pending';
+    connectionName: string;
+    consentLink: string;
+} | {
+    status: 'connected';
+    connectionName: string;
+} | {
+    status: 'error';
+    message: string;
+};
+/**
+ * Create a new connection for a connector in the user's environment.
+ *
+ * Calls:
+ *   POST {envBase}/connectivity/apis/{connectorId}/connections
+ *
+ * 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.
+ */
+export declare function createConnection(connectorId: string, environmentId: string, region: string, token: string, displayName?: string, oauthRedirectUrl?: string): Promise<CreateConnectionResult>;
+/**
+ * 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.
+ */
+export declare function pollConnectionStatus(connectorId: string, connectionName: string, environmentId: string, region: string, acquireToken: (scopes: string[]) => Promise<string | null>, options?: {
+    intervalMs?: number;
+    timeoutMs?: number;
+}): Promise<NativeConnectionInstance | null>;
+/**
+ * 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.
+ */
+export declare function confirmConsentCode(connectorId: string, connectionId: string, environmentId: string, region: string, token: string, code: string): Promise<boolean>;
+/**
+ * Processed result of the PowerApps app launch API call, ready to be applied
+ * directly to the NativePowerAppsBridge without further network calls.
+ */
+export interface AppLaunchResult {
+    /**
+     * AppConnectionReference map keyed by data source name.
+     * Passed directly to `setupNativeHost({ connections: ... })`.
+     */
+    connectionRefs: Record<string, AppConnectionReference>;
+    /**
+     * Dataverse org URL derived from the environment's
+     * `linkedEnvironmentMetadata.instanceUrl` (empty string if the environment
+     * has no linked Dataverse database).
+     */
+    dataverseOrgUrl: string;
+    /**
+     * Connector short-names (e.g. "shared_office365users") for which the
+     * launch API found no "Connected" connection instance for the signed-in
+     * user.  These connectors need the connection setup flow.
+     */
+    missingConnectors: string[];
+}
+/**
+ * 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):
+ *   GET {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` if the call fails.
+ */
+export declare function fetchAppLaunchData(appId: string, environmentId: string, region: string, token: string): Promise<AppLaunchResult | null>;
+/**
+ * Decode the `oid` (object ID) claim from a JWT access token.
+ *
+ * The oid claim is in the base64url-encoded payload section (middle part).
+ * Available in Hermes (React Native) via the global `atob`.
+ */
+export declare function parseJwtOid(jwtToken: string): string | null;
+/**
+ * Add the ISV's AAD application (client) ID to the connection's ACL AppIds
+ * list via the Power Apps RP `addAadAppToConnectionAcl` endpoint.
+ *
+ * The RP finds the user's existing ACE (identified by `userOid`) and appends
+ * `isvClientId` to its `AppIds` list. APIM's stage-2 token check verifies
+ * that the requesting token's `appid` is present in this list, so without
+ * this call APIM returns 403 "missing connection ACL" for third-party tokens.
+ *
+ * POST https://api.powerapps.com/providers/Microsoft.PowerApps/environments/{environmentId}
+ *      /apis/{connectorId}/connections/{connectionId}/addAadAppToConnectionAcl
+ *      ?api-version=2016-11-01
+ *
+ * Body: { "aadApplicationId": "<ISV client ID>", "objectId": "<user OID>" }
+ *
+ * @param connectorId   - Connector short name (e.g. "shared_office365users").
+ * @param connectionId  - Bare 32-char hex connection ID.
+ * @param environmentId - Environment GUID.
+ * @param isvClientId   - The ISV's AAD application (client) ID.
+ * @param userOid       - The signed-in user's AAD object ID (oid JWT claim).
+ * @param token         - Bearer token for `https://service.powerapps.com/.default`.
+ */
+export declare function addAadAppToConnectionAcl(connectorId: string, connectionId: string, environmentId: string, isvClientId: string, userOid: string, token: string): Promise<boolean>;
+//# sourceMappingURL=PowerPlatformConnectionApi.d.ts.map

package/lib/typescript/commonjs/platform/PowerPlatformEnvironmentApi.d.ts

@@ -0,0 +1,108 @@
+/*!
+ * power-apps-native-host — PowerPlatformEnvironmentApi
+ *
+ * Mirrors the Host SDK's DefaultAppMetadataProvider.fetchAppMetadataFromPowerConfig
+ * pattern: resolves the Power Platform environment-scoped API endpoint from the
+ * environment GUID and region, then fetches linkedEnvironmentMetadata to obtain
+ * the Dataverse instanceUrl.
+ *
+ * Reference (Host SDK):
+ *   packages/power-apps-host/src/providers/defaults/DefaultAppMetadataProvider.ts
+ *   packages/power-apps-common/src/services/PowerPlatformApiDiscovery.ts
+ */
+/**
+ * Build the Power Platform environment-scoped API base URL.
+ *
+ * Algorithm (mirrors PowerPlatformApiDiscovery.generateDomain):
+ *   1. Strip dashes from the environment GUID to get a hex string.
+ *   2. Split into prefix (all but last N chars) and suffix (last N chars),
+ *      where N = 2 for prod/firstrelease, 1 for all other regions.
+ *   3. Compose: `{prefix}.{suffix}.environment.{hostNameSuffix}`
+ *
+ * Example (prod, environmentId = "d909aac0-59d0-e5b1-900d-c082ef5774d7"):
+ *   hexName  = "d909aac059d0e5b1900dc082ef5774d7"
+ *   suffix   = "d7"
+ *   prefix   = "d909aac059d0e5b1900dc082ef5774"
+ *   → "d909aac059d0e5b1900dc082ef5774.d7.environment.api.powerplatform.com"
+ */
+export declare function buildEnvironmentEndpoint(environmentId: string, region: string): string;
+export interface LinkedEnvironmentMetadata {
+    resourceId?: string;
+    friendlyName?: string;
+    uniqueName?: string;
+    domainName?: string;
+    version?: string;
+    instanceUrl?: string;
+    instanceApiUrl?: string;
+    baseLanguage?: number;
+    instanceState?: string;
+    createdTime?: string;
+    platformSku?: string;
+}
+/**
+ * Token scope for the Power Platform management API (prod cluster).
+ * Non-prod clusters (test, gov, high, dev, mooncake, etc.) host the management
+ * API on their own audience, so prod-scope tokens are rejected with 401 by
+ * those clusters. Prefer {@link powerPlatformScope} when the region is known.
+ */
+export declare const POWER_PLATFORM_API_SCOPE = "https://api.powerplatform.com/.default";
+/**
+ * Region-aware Power Platform management API scope. The audience must match the
+ * cluster the request is sent to; reuses the same region → hostname table as
+ * {@link buildEnvironmentEndpoint}.
+ */
+export declare function powerPlatformScope(region: string): string;
+/**
+ * Fetch the Dataverse instanceUrl for a Power Platform environment by calling
+ * the environment-scoped Power Platform management API — the same call that
+ * the Host SDK's DefaultAppMetadataProvider makes to populate
+ * `databaseReferences[*].databaseDetails.linkedEnvironmentMetadata`.
+ *
+ * @param environmentId - Environment GUID (from power.config.json `environmentId`).
+ * @param region        - Cluster region string (from power.config.json `region`, default "prod").
+ * @param acquireToken  - Callback to obtain a bearer token for the given scopes.
+ *                        Scope will be {@link powerPlatformScope}`(region)`.
+ * @param bearerToken   - Optional pre-fetched bearer token for {@link powerPlatformScope}`(region)`.
+ *                        Pass this to avoid a redundant `acquireToken` round-trip when the
+ *                        caller has already obtained a token for the same audience.
+ * @returns The Dataverse org URL (e.g. "https://org12345.crm.dynamics.com"), or
+ *          `undefined` if the environment has no linked CDS database.
+ */
+export declare function fetchInstanceUrl(environmentId: string, region: string, acquireToken: (scopes: string[]) => Promise<string | null>, bearerToken?: string): Promise<string | undefined>;
+/**
+ * Shape of a single Dataverse table entry inside power.config.json
+ * `databaseReferences[*].dataSources[*]`.
+ */
+export interface DatabaseReferenceDataSource {
+    entitySetName?: string;
+    logicalName?: string;
+}
+/**
+ * Shape of a single database reference entry inside power.config.json
+ * `databaseReferences`.
+ */
+export interface DatabaseReference {
+    dataSources?: Record<string, DatabaseReferenceDataSource>;
+}
+/**
+ * Build the CDS data source config array that the SDK reads via
+ * AppPowerAppsClientPlugin.getAppCdsDataSourceConfigsAsync.
+ *
+ * Pass the resolved Dataverse org URL (from useConnectionRefs) and the
+ * databaseReferences map from power.config.json.  The resulting array is
+ * passed directly to <PowerAppsHostProvider dataSources={...} />.
+ *
+ * @param databaseReferences - The `databaseReferences` map from power.config.json.
+ * @param dataverseOrgUrl    - The resolved Dataverse org URL
+ *                             (connectionRefs['commondataserviceforapps']?.datasetName).
+ *                             Pass an empty string before the org URL is known;
+ *                             the host provider will receive empty runtimeUrl entries
+ *                             and the SDK will not attempt Dataverse calls.
+ */
+export declare function buildCdsDataSources(databaseReferences: Record<string, DatabaseReference>, dataverseOrgUrl: string): Array<{
+    runtimeUrl: string;
+    entitySetName: string;
+    logicalName: string;
+    version: string;
+}>;
+//# sourceMappingURL=PowerPlatformEnvironmentApi.d.ts.map

package/lib/typescript/commonjs/platform/resolveConnections.d.ts

@@ -0,0 +1,86 @@
+/*!
+ * power-apps-native-host — resolveConnections
+ *
+ * Pure async helpers for the two connection-resolution strategies used by
+ * useConnectionRefs:
+ *
+ *  • resolveViaStaticRefs — per-connector resolution using the static
+ *    connectionReferences map from power.config.json.  Used by the Dev Player
+ *    and during local development (no appId) or when the launch API is
+ *    unavailable.  Handles pre-disambiguation ACL grants so inaccessible
+ *    connections are excluded before the user is asked to pick.
+ *
+ *  • applyAclGrants — post-resolution ACL grants used by the fast path
+ *    (production APKs via fetchAppLaunchData).
+ *
+ * Both helpers return / consume the shared AppLaunchResult shape so the
+ * hook orchestrator can handle them uniformly.
+ */
+import type { AppLaunchResult } from './PowerPlatformConnectionApi';
+import type { OnDisambiguationNeeded, OnMissingConnection } from '../connections/types';
+import type { AppConnectionReference } from '../bridge/NativePowerAppsBridge';
+/**
+ * Connector schema entry generated by `generate-connector-schemas`.
+ * Keyed by data source name in the `schemaMap` passed to `useConnectionRefs`.
+ */
+export interface ConnectorSchema {
+    /** Connector name used as the connectorId in API calls, e.g. "shared_commondataserviceforapps". */
+    name: string;
+    properties: {
+        primaryRuntimeUrl: string;
+    };
+}
+export interface StaticRefsOptions {
+    /**
+     * Static connectionReferences from power.config.json.
+     * Shape: { [refId]: { id: string; dataSources: string[] } }
+     */
+    connectionReferences: Record<string, {
+        id: string;
+        dataSources: string[];
+    }>;
+    /** Connector schema map keyed by data source name. */
+    schemaMap: Record<string, ConnectorSchema>;
+    environmentId: string;
+    region: string;
+    /** Used for ACL grants and the Dataverse instanceUrl fetch. */
+    acquireToken: (scopes: string[]) => Promise<string | null>;
+    /** Pre-acquired Power Platform API bearer token. */
+    token: string;
+    /** ISV client ID — when provided, runs pre-disambiguation ACL grants. */
+    isvClientId?: string;
+    onDisambiguationNeeded?: OnDisambiguationNeeded;
+    onMissingConnection?: OnMissingConnection;
+}
+/**
+ * Resolve connections from the static `connectionReferences` map.
+ *
+ * Steps:
+ *  1. Build an apiId → schema lookup.
+ *  2. In parallel: fetch the Dataverse instanceUrl and all connection instances
+ *     for every connector.
+ *  3. If `isvClientId` is set, run pre-disambiguation ACL grants — connections
+ *     where the grant fails are marked `NeedsAclGrant` and excluded from
+ *     resolution, prompting the user to create a new connection.
+ *  4. Disambiguate: resolve single matches, invoke callbacks for ambiguous /
+ *     missing cases, perform one-shot retries when `onMissingConnection` returns
+ *     `true`.
+ *  5. Build and return an `AppLaunchResult`-shaped object.
+ */
+export declare function resolveViaStaticRefs({ connectionReferences, schemaMap, environmentId, region, acquireToken, token, isvClientId, onDisambiguationNeeded, onMissingConnection, }: StaticRefsOptions): Promise<AppLaunchResult>;
+/**
+ * Run idempotent post-resolution ACL grants on behalf of the ISV app.
+ *
+ * Used by the fast path (production APKs via `fetchAppLaunchData`) where the
+ * launch API has already resolved the user's connections — grants are applied
+ * after the fact so APIM accepts tokens issued to the ISV's AAD app.
+ *
+ * For the slow path the grants run before disambiguation inside
+ * `resolveViaStaticRefs`, where they can still influence which connections
+ * are considered available.
+ *
+ * Failures are swallowed — a failed grant will surface as a 403 at runtime
+ * when the connector is called.
+ */
+export declare function applyAclGrants(connectionRefs: Record<string, AppConnectionReference>, environmentId: string, isvClientId: string, acquireToken: (scopes: string[]) => Promise<string | null>): Promise<void>;
+//# sourceMappingURL=resolveConnections.d.ts.map

package/lib/typescript/commonjs/platform/useConnectionRefs.d.ts

@@ -0,0 +1,126 @@
+/*!
+ * power-apps-native-host — useConnectionRefs
+ *
+ * Resolves per-user connectionIds from the Power Platform environment-scoped
+ * connectivity API, then builds a fully-populated connection-references map
+ * ready to pass to <PowerAppsHostProvider connections={...} />.
+ *
+ * Now supports connection disambiguation: when multiple Connected connections
+ * exist for the same connector, the `onDisambiguationNeeded` callback lets the
+ * consuming app present a native picker UI (e.g. a bottom sheet) so the user
+ * can choose which connection to use.  When no connection exists for a connector
+ * the `onMissingConnection` callback fires so the consuming app can guide the
+ * user to create one.
+ *
+ * Usage:
+ *   import { useConnectionRefs } from '@microsoft/power-apps-native-host';
+ *   import powerConfig from '../power.config.json';
+ *   import { schemaMap } from '../src/connectorSchemas';
+ *
+ *   const { connectionRefs, isReady, error, missingConnectors } = useConnectionRefs({
+ *     isSignedIn,
+ *     acquireToken,
+ *     environmentId: authConfig.powerPlatform.environmentId,
+ *     region: authConfig.powerPlatform.region,
+ *     connectionReferences: powerConfig.connectionReferences,
+ *     schemaMap,
+ *     onDisambiguationNeeded: async ({ localRefId, apiId, candidates }) => {
+ *       // Show a picker sheet and return the selected connectionId, or null to skip.
+ *       return showConnectionPicker(candidates);
+ *     },
+ *   });
+ */
+import { type OnDisambiguationNeeded, type OnMissingConnection } from '../connections/types';
+import type { ConnectorSchema } from './resolveConnections';
+import type { AppConnectionReference } from '../bridge/NativePowerAppsBridge';
+export type { ConnectorSchema } from './resolveConnections';
+export interface UseConnectionRefsOptions {
+    isSignedIn: boolean;
+    acquireToken: (scopes: string[]) => Promise<string | null>;
+    /** Power Platform environment GUID (from auth.config.json). */
+    environmentId: string;
+    /**
+     * Routing region for the environment.
+     * @default 'prod'
+     */
+    region?: string;
+    /**
+     * PowerApps app GUID (from power.config.json `appId`).
+     * When provided (and not running inside the Dev Player), connection
+     * references are fetched at runtime from the PowerApps RP
+     * `/apps/{appId}/launch` endpoint and take precedence over the static
+     * `connectionReferences` object below.
+     * Leave undefined during local development to use the static fallback.
+     */
+    appId?: string;
+    /**
+     * The connectionReferences map from power.config.json.
+     * Shape: { [refId]: { id: string; dataSources: string[] } }
+     */
+    connectionReferences: Record<string, {
+        id: string;
+        dataSources: string[];
+    }>;
+    /**
+     * Connector schema map keyed by data source name.
+     * Generated automatically by generate-connector-schemas.
+     * Shape: { [dataSourceName]: ConnectorSchema }
+     */
+    schemaMap: Record<string, ConnectorSchema>;
+    /**
+     * Called when multiple Connected connections exist for the same connector.
+     * Present a native picker UI and return the chosen connectionId, or null to
+     * leave the connection unresolved.
+     */
+    onDisambiguationNeeded?: OnDisambiguationNeeded;
+    /**
+     * Called when no connections are found for a required connector.
+     * The app can redirect the user to a connection setup flow; return `true` to
+     * trigger a one-time retry of the connection fetch, `false` to leave it unresolved.
+     */
+    onMissingConnection?: OnMissingConnection;
+    /**
+     * The ISV's AAD application (client) ID.  When provided, each resolved
+     * `Connected` connection is checked via `addAadAppToConnectionAcl`.
+     * Connections where the grant fails are marked `NeedsAclGrant` and treated
+     * as missing so the setup screen can guide the user to create a new one.
+     */
+    isvClientId?: string;
+}
+export interface UseConnectionRefsResult {
+    connectionRefs: Record<string, AppConnectionReference>;
+    isReady: boolean;
+    error: string | null;
+    /**
+     * API IDs of connectors for which no connection was found (or the user did
+     * not resolve during disambiguation).  Useful for surfacing a "Set up
+     * connections" prompt in the app UI.
+     */
+    missingConnectors: string[];
+    /**
+     * The Dataverse org URL for this environment (e.g. "https://org12345.crm.dynamics.com").
+     * Fetched from the Power Platform environment metadata independently of whether a
+     * commondataserviceforapps connection reference is configured.
+     * Empty string until isReady is true or if the environment has no linked Dataverse database.
+     */
+    dataverseOrgUrl: string;
+}
+/**
+ * Resolves Power Platform connection references for the current user, with
+ * 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.
+ */
+export declare function useConnectionRefs({ isSignedIn, acquireToken, appId, environmentId, region, connectionReferences, schemaMap, onDisambiguationNeeded, onMissingConnection, isvClientId, }: UseConnectionRefsOptions): UseConnectionRefsResult;
+//# sourceMappingURL=useConnectionRefs.d.ts.map