/** Message type sent from the OAuth callback popup to the opener. */
export declare const GITHUB_CALLBACK_MESSAGE_TYPE = "stigmer:github:callback-success";
/** Minimal GitHub user profile for display. */
export interface GitHubUser {
    /** GitHub username (e.g. `"octocat"`). */
    readonly login: string;
    /** URL of the user's avatar image. */
    readonly avatarUrl: string;
    /** Display name, or `null` when the user has not set one. */
    readonly name: string | null;
}
/** Options for {@link UseGitHubConnectionReturn.connect}. */
export interface GitHubConnectOptions {
    /**
     * When `true`, open the OAuth authorization page in a popup window
     * instead of redirecting the current page. The callback page signals
     * success via `postMessage` and the hook re-reconciles the token
     * from the personal environment — keeping the user on the same page.
     *
     * Falls back to redirect if the popup is blocked by the browser.
     *
     * @default false
     */
    readonly popup?: boolean;
}
/**
 * Optional configuration for {@link useGitHubConnection}.
 *
 * Enables desktop and non-browser environments to participate in the
 * GitHub OAuth flow without relying on `window.open()` popups.
 */
export interface UseGitHubConnectionConfig {
    /**
     * Custom function to open the authorization URL in a browser.
     *
     * When provided, the hook calls this instead of `window.open()` during
     * popup-mode `connect()` flows. This enables desktop environments
     * (e.g. Tauri, Electron) where webview popups are blocked but the
     * system browser is available.
     *
     * When used with {@link callbackUrl}, the callback page processes the
     * token exchange and the consumer calls {@link UseGitHubConnectionReturn.reconcile}
     * to pick up the token from the personal environment.
     *
     * When used without {@link callbackUrl} (e.g. localhost callback server),
     * the consumer calls {@link UseGitHubConnectionReturn.handleCallback}
     * with the code, state, and redirect URI to complete the exchange.
     */
    readonly openUrl?: (url: string) => void | Promise<void>;
    /**
     * Override the OAuth callback URL.
     *
     * When provided, this replaces the `redirectUri` parameter passed to
     * `connect()` by UI components like `WorkspaceEditor`. Use this to
     * route the GitHub callback to a specific URL — for example, the
     * Stigmer web console's callback page for desktop flows, or a
     * localhost server for local development.
     *
     * When the callback page handles the token exchange itself (cloud
     * desktop flows), the consumer triggers re-reconciliation via
     * {@link UseGitHubConnectionReturn.reconcile} after the callback
     * completes externally.
     *
     * When the consumer handles the exchange (localhost flows), the same
     * URL must be passed to `handleCallback()` — GitHub requires an
     * exact match between the authorize and exchange redirect URIs.
     */
    readonly callbackUrl?: string;
}
/** Return value of {@link useGitHubConnection}. */
export interface UseGitHubConnectionReturn {
    /** Whether a valid GitHub token exists. */
    readonly isConnected: boolean;
    /** Whether the connection state is being validated on mount. */
    readonly isLoading: boolean;
    /** Whether an OAuth popup is open and the flow is in progress. */
    readonly isConnecting: boolean;
    /**
     * Whether the last popup `connect()` attempt was blocked by the
     * browser. When `true`, the UI should prompt the user to allow
     * popups or offer a redirect fallback (call `connect` without
     * `{ popup: true }`).
     */
    readonly popupBlocked: boolean;
    /** The connected GitHub user profile, if connected. */
    readonly user: GitHubUser | null;
    /** The current access token (null if not connected). */
    readonly token: string | null;
    /** Initiate the OAuth flow — redirect or popup based on options. */
    readonly connect: (redirectUri: string, options?: GitHubConnectOptions) => Promise<void>;
    /** Handle the OAuth callback — exchange code for token. */
    readonly handleCallback: (code: string, state: string, redirectUri: string) => Promise<void>;
    /**
     * Trigger re-reconciliation from the personal environment.
     *
     * Call this when the token exchange was handled externally (e.g. by
     * the Stigmer web callback page during a desktop OAuth flow) and the
     * token is already stored server-side. The hook will refetch the
     * personal environment, reveal the token, and update
     * {@link isConnected}.
     */
    readonly reconcile: () => void;
    /** Clear the stored token and user info. */
    readonly disconnect: () => void;
}
/**
 * Behavior hook that manages the GitHub OAuth connection lifecycle.
 *
 * Handles the full OAuth flow: generating the authorize URL via the
 * Stigmer backend, exchanging the code for a token, validating it,
 * and persisting it in the user's server-side personal
 * `Environment`.
 *
 * **Storage strategy:** The token is stored encrypted in the personal
 * environment (server-side). On OAuth callback the token is written
 * directly to the personal environment via `getOrCreate` /
 * `addVariables`. On subsequent mounts the token is revealed from the
 * personal environment and validated against the GitHub API.
 *
 * Pass `null` as `org` to disable server-side storage (the hook will
 * report as not connected until org context is available).
 *
 * Platform builders who need custom GitHub integration UI use this
 * hook directly. The styled `WorkspaceEditor` component accepts the
 * return value as a prop.
 *
 * @param org - The active organization slug. Required for server-side
 *   token storage. Pass `null` to skip all server operations.
 * @param config - Optional configuration for desktop / non-browser
 *   environments. See {@link UseGitHubConnectionConfig}.
 *
 * @example
 * ```tsx
 * function GitHubConnect({ org }: { org: string }) {
 *   const gh = useGitHubConnection(org);
 *
 *   if (gh.isLoading) return <Skeleton />;
 *
 *   if (!gh.isConnected) {
 *     return (
 *       <button
 *         onClick={() => gh.connect(window.location.href, { popup: true })}
 *         disabled={gh.isConnecting}
 *       >
 *         {gh.isConnecting ? "Connecting…" : "Connect GitHub"}
 *       </button>
 *     );
 *   }
 *
 *   return (
 *     <div>
 *       <img src={gh.user?.avatarUrl} alt={gh.user?.login} />
 *       <span>{gh.user?.login}</span>
 *       <button onClick={gh.disconnect}>Disconnect</button>
 *     </div>
 *   );
 * }
 * ```
 *
 * @example Desktop (Tauri) — open in system browser, callback via deep link
 * ```tsx
 * function DesktopGitHubConnect({ org }: { org: string }) {
 *   const gh = useGitHubConnection(org, {
 *     openUrl: (url) => invoke("open_auth_in_browser", { authUrl: url }),
 *     callbackUrl: "https://app.stigmer.ai/auth/github/callback?source=desktop",
 *   });
 *   // The web callback page processes the exchange, then redirects to
 *   // stigmer://github/callback-done. The desktop deep link handler
 *   // calls gh.reconcile() to pick up the token.
 * }
 * ```
 */
export declare function useGitHubConnection(org: string | null, config?: UseGitHubConnectionConfig): UseGitHubConnectionReturn;
//# sourceMappingURL=useGitHubConnection.d.ts.map