import type { Auth, OpaqueSession } from '@microsoft/rayfin-auth';
import type { FabricAuthOptions } from './types.js';
/**
 * Ensures the user is signed in via Fabric brokered authentication.
 *
 * Implements a multi-step waterfall — the first step that succeeds short-circuits the rest:
 *
 * 1. **Already authenticated** — if `auth.getSession().isAuthenticated` is true,
 *    return the existing session immediately.  On a legacy embedded host (one that
 *    stamps no `?_fu=` hint) this is skipped on the first call per page load, so a
 *    session belonging to a previously signed-in Fabric user cannot be reused.
 * 2. **Refresh token** — if a refresh token is available, attempt `auth.refreshSession()`.
 *    Return the refreshed session on success; continue on failure.
 *    Subject to the same skip.
 * 3. **Embedded mode** — if running inside a Fabric iframe (`fabricEmbedded=true`),
 *    use `embeddedFabricLogin()` to acquire a session via `postMessage` handoff.
 * 4. **Open Fabric broker** — no existing auth path available. Open the Fabric Portal
 *    in a new tab via `initiateFabricLogin()` and wait for the Fabric extension to post
 *    the handoff code via `postMessage`. The function exchanges the code internally
 *    and creates the session. Once the promise resolves, return the new session.
 *
 * **Step 4 calls `window.open()`** — to avoid popup/tab blockers, call this function
 * from inside a synchronous user-gesture handler (e.g., a button click).
 * Steps 1–3 do not open windows and are safe to call on page load.
 *
 * @param auth - The Auth instance.
 * @param options - Fabric authentication options (workspaceId, projectId, fabricPortalUrl, returnOrigin).
 * @returns A promise that resolves with the authenticated session.
 * @throws `AuthError` - If all steps fail or the broker tab is blocked.
 *
 * @example
 * ```typescript
 * import { Auth } from '@microsoft/rayfin-auth';
 * import { ApiClient } from '@microsoft/rayfin-lib';
 * import {
 *   ensureSignedInWithFabric,
 *   type FabricAuthOptions,
 * } from '@microsoft/rayfin-auth-provider-fabric';
 *
 * const apiClient = new ApiClient({
 *   baseUrl: import.meta.env.VITE_RAYFIN_API_URL,
 *   publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
 * });
 * const auth = new Auth(apiClient);
 * const fabricOptions: FabricAuthOptions = {
 *   workspaceId: import.meta.env.VITE_FABRIC_WORKSPACE_ID,
 *   projectId: import.meta.env.VITE_FABRIC_ITEM_ID,
 *   fabricPortalUrl: import.meta.env.VITE_FABRIC_PORTAL_URL,
 *   returnOrigin: window.location.origin,
 * };
 *
 * // Wire to a button click so step 4 (window.open) is in a user-gesture context.
 * signInButton.addEventListener('click', async () => {
 *   try {
 *     const session = await ensureSignedInWithFabric(auth, fabricOptions);
 *     console.log('Signed in as', session.user?.email);
 *   } catch (error) {
 *     console.error('Fabric sign-in failed:', error.message);
 *   }
 * });
 * ```
 */
export declare function ensureSignedInWithFabric(auth: Auth, options: FabricAuthOptions): Promise<OpaqueSession>;
//# sourceMappingURL=ensureSignedInWithFabric.d.ts.map