/**
 * Parse the OAuth redirect callback that Tokenite sends to your app's
 * `redirect_uri`. Returns a typed result the caller can switch on
 * instead of hand-checking string params.
 *
 * ```typescript
 * import { parseCallback } from '@tokenite/sdk';
 *
 * const result = parseCallback(req.url, { expectedState: storedState });
 * if (result.ok) {
 *   const { code } = result;
 *   const { access_token } = await tk.exchangeCode(code);
 *   // ...
 * } else {
 *   switch (result.reason) {
 *     case 'user_denied':    return renderCancelled();      // user clicked Cancel
 *     case 'invalid_state':  return renderRetry();          // CSRF check failed
 *     case 'missing_code':   return renderRetry();          // user landed here directly
 *     default:               return renderError(result);    // other OAuth error
 *   }
 * }
 * ```
 *
 * Pure function — no side effects, no network, no SDK config needed.
 * Works server-side (Node, edge runtimes) and in the browser.
 */
export type CallbackSuccess = {
    readonly ok: true;
    readonly code: string;
    readonly state: string | null;
};
/**
 * Why an OAuth callback didn't yield a usable authorization code.
 *
 * - `user_denied` — the end user clicked "Cancel" on the Tokenite
 *   consent screen. The most common non-success case. Render a
 *   friendly "you cancelled" UI with a "Try again" CTA, NOT a
 *   technical error.
 *
 * - `access_denied` — the server returned `error=access_denied`
 *   without the `user_denied` description. Generic access refusal
 *   (e.g. the app's `redirect_uri` didn't match, scope was refused
 *   by policy). Still recoverable with a retry, but the cause is
 *   server-side rather than the user's choice.
 *
 * - `invalid_state` — `expectedState` was provided to `parseCallback`
 *   and didn't match the returned `state` value. Either a stale
 *   session or a CSRF attempt. Always reject and force a fresh
 *   flow; never auto-retry without user interaction.
 *
 * - `missing_code` — neither `code` nor `error` was present in the
 *   callback URL. Usually means the user navigated to the callback
 *   path directly (e.g. via bookmark or browser back) rather than
 *   completing a real OAuth round-trip.
 *
 * - `oauth_error` — any other OAuth 2.0 error code (`invalid_request`,
 *   `unauthorized_client`, `server_error`, etc.). Inspect
 *   `error` / `description` for specifics.
 */
export type CallbackReason = 'user_denied' | 'access_denied' | 'invalid_state' | 'missing_code' | 'oauth_error';
export type CallbackError = {
    readonly ok: false;
    readonly reason: CallbackReason;
    /** Raw OAuth error code from the URL, when present. */
    readonly error?: string;
    /** Raw `error_description` from the URL, when present. */
    readonly description?: string;
    /** The `state` value returned by Tokenite (may be null if the original flow didn't include one). */
    readonly state: string | null;
};
export type CallbackResult = CallbackSuccess | CallbackError;
export type ParseCallbackOptions = {
    /**
     * If provided, compare against the returned `state` query param.
     * Mismatch → `{ ok: false, reason: 'invalid_state' }`, even if a
     * `code` is present (a code + bad state is treated as a CSRF
     * attempt, not a success).
     */
    readonly expectedState?: string;
};
/**
 * Parse an OAuth callback. Accepts any of: a full URL string, a path
 * with query string (e.g. Node's `req.url`), a `URL` object, a
 * `URLSearchParams`, or a plain query string (with or without leading
 * `?`).
 */
export declare const parseCallback: (input: string | URL | URLSearchParams, options?: ParseCallbackOptions) => CallbackResult;
//# sourceMappingURL=parse-callback.d.ts.map