import type { TokenType } from './common';

/** A base interface for API calls that allow passing custom headers.
 * @hidden
 */
interface RequestOptions {
  /** Optional custom headers to be included in the request. */
  headers?: Record<string, string>;
  [key: string]: any;
}

// ========= URL Builder Parameters =========

/** Parameters for building a URL for the `/authorize` endpoint. */
export interface AuthorizeUrlParameters extends RequestOptions {
  responseType: string;
  redirectUri: string;
  state: string;
}

/** Parameters for building a URL for the `/v2/logout` endpoint. */
export interface LogoutUrlParameters extends RequestOptions {
  federated?: boolean;
  clientId?: string;
  returnTo?: string;
}

// ========= Web Authorize & Logout Parameters =========

/**
 * Parameters for the web-based authorization flow.
 * @see https://auth0.com/docs/api/authentication#authorize-client
 */
export interface WebAuthorizeParameters {
  /**
   * Random string to prevent CSRF attacks.
   */
  state?: string;
  /**
   * One-time random value that is used to prevent replay attacks.
   */
  nonce?: string;
  /**
   * The intended API identifier that will be the consumer for the issued access token.
   */
  audience?: string;
  /**
   * The scopes requested for the issued tokens. e.g. `openid profile`
   */
  scope?: string;
  /**
   * The database connection in which to look for users.
   */
  connection?: string;
  /**
   * The maximum age in seconds that the resulting ID token should be issued for.
   */
  maxAge?: number;
  /**
   * The organization in which user's should be authenticated into.
   */
  organization?: string;
  /**
   * The invitation URL for those users who have been invited to join a specific organization.
   */
  invitationUrl?: string;
  /**
   * Specify a custom redirect URL to be used. Normally, you wouldn't need to call this method manually as the default value is autogenerated for you.
   *
   * If you are using this, ensure a proper redirect URL is constructed in the following format
   * - **Android:** `{YOUR_APP_PACKAGE_NAME}.auth0://{AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback`
   * - **iOS:** `{PRODUCT_BUNDLE_IDENTIFIER}.auth0://{AUTH0_DOMAIN}/ios/{PRODUCT_BUNDLE_IDENTIFIER}/callback`
   *
   * If you have `useLegacyCallbackUrl` set to true then the redirect URL should in the format
   * - **Android:** `{YOUR_APP_PACKAGE_NAME}://{AUTH0_DOMAIN}/android/{YOUR_APP_PACKAGE_NAME}/callback`
   * - **iOS:** `{PRODUCT_BUNDLE_IDENTIFIER}://{AUTH0_DOMAIN}/ios/{PRODUCT_BUNDLE_IDENTIFIER}/callback`
   */
  redirectUrl?: string;
  /**
   * Any additional arbitrary parameters to send along in the URL.
   */
  additionalParameters?: { [key: string]: string };
}

/**
 * Parameters for clearing the user's session.
 * @see https://auth0.com/docs/api/authentication#logout
 */
export interface ClearSessionParameters {
  /**
   * If `true`, the user will also be logged out from their identity provider (e.g., Google).
   * @default false
   */
  federated?: boolean;
  /** The URL to which the user is redirected after logout. */
  returnToUrl?: string;
}

// ========= OAuth/OIDC Token Flow Parameters =========

/** Parameters for exchanging a code for tokens (PKCE Flow). */
export interface ExchangeParameters extends RequestOptions {
  code: string;
  verifier: string;
  redirectUri: string;
}

/**
 * Parameters for exchanging a refresh token for session transfer credentials (Native to Web SSO).
 * This allows apps that manage their own tokens to obtain a session transfer token
 * without using the Credentials Manager.
 *
 * @see https://auth0.com/docs/authenticate/single-sign-on/native-to-web/configure-implement-native-to-web
 */
export interface SSOExchangeParameters extends RequestOptions {
  /**
   * The refresh token to exchange for a session transfer token.
   */
  refreshToken: string;
}

/** Parameters for exchanging a native social provider's token for Auth0 tokens. */
export interface ExchangeNativeSocialParameters extends RequestOptions {
  subjectToken: string;
  subjectTokenType: string;
  userProfile?: string;
  audience?: string;
  scope?: string;
}

/**
 * Parameters for Custom Token Exchange (RFC 8693).
 * Exchanges an external identity provider token for Auth0 tokens.
 *
 * Custom Token Exchange allows you to exchange tokens from external identity
 * providers for Auth0 tokens. The external token must be validated in Auth0
 * Actions using cryptographic verification.
 *
 * @see https://auth0.com/docs/authenticate/custom-token-exchange
 */
export interface CustomTokenExchangeParameters {
  /**
   * The external token to be exchanged for Auth0 tokens.
   * Must be validated in Auth0 Actions using cryptographic verification.
   */
  subjectToken: string;

  /**
   * The type identifier for the subject token being exchanged.
   *
   * Must be a unique profile token type URI starting with `https://` or `urn:`.
   *
   * Valid patterns:
   * - `urn:yourcompany:token-type` - Company-specific URN (recommended)
   * - `https://yourcompany.com/tokens/custom` - HTTPS URL under your control
   *
   * Reserved namespaces (forbidden):
   * - `http://auth0.com/*`, `https://auth0.com/*`
   * - `http://okta.com/*`, `https://okta.com/*`
   * - `urn:ietf:*`, `urn:auth0:*`, `urn:okta:*`
   *
   * @example "urn:acme:legacy-system-token" // Custom legacy token
   * @example "https://yourcompany.com/tokens/partner-jwt" // Custom HTTPS identifier
   */
  subjectTokenType: string;

  /**
   * The target audience for the requested Auth0 token.
   * Must match an API identifier configured in your Auth0 tenant.
   */
  audience?: string;

  /**
   * Space-separated list of OAuth 2.0 scopes.
   * @default "openid profile email"
   */
  scope?: string;

  /**
   * Organization ID or name for authenticating in an organization context.
   * When provided, the organization ID will be present in the access token.
   */
  organization?: string;
}

/**
 * Parameters for authenticating with a username and password.
 * @see https://auth0.com/docs/api-auth/grant/password
 */
export interface PasswordRealmParameters extends RequestOptions {
  username: string;
  password: string;
  realm: string;
  audience?: string;
  scope?: string;
}

/**
 * Parameters for refreshing an access token.
 * @see https://auth0.com/docs/tokens/refresh-tokens
 */
export interface RefreshTokenParameters extends RequestOptions {
  /**
   * The issued refresh token
   */
  refreshToken: string;
  /**
   * The scopes requested for the issued tokens. e.g. `openid profile`
   */
  scope?: string;
  /**
   * The intended API identifier that will be the consumer for the issued access token.
   */
  audience?: string;
}

/** Parameters for revoking a refresh token. */
export interface RevokeOptions extends RequestOptions {
  refreshToken: string;
}

// ========= Passwordless Flow Parameters =========

/** Parameters for initiating passwordless login with an email. */
export interface PasswordlessEmailParameters extends RequestOptions {
  email: string;
  send?: 'link' | 'code';
  authParams?: object;
}

/** Parameters for initiating passwordless login with SMS. */
export interface PasswordlessSmsParameters extends RequestOptions {
  phoneNumber: string;
  send?: 'link' | 'code';
  authParams?: object;
}

/** Parameters for completing passwordless login with an email code/OTP. */
export interface LoginEmailParameters extends RequestOptions {
  email: string;
  code: string;
  audience?: string;
  scope?: string;
}

/** Parameters for completing passwordless login with an SMS code/OTP. */
export interface LoginSmsParameters extends RequestOptions {
  phoneNumber: string;
  code: string;
  audience?: string;
  scope?: string;
}

// ========= Multi-Factor Authentication (MFA) Parameters =========

/** Parameters for logging in with an OTP code after an MFA challenge. */
export interface LoginOtpParameters extends RequestOptions {
  mfaToken: string;
  otp: string;
  audience?: string;
}

/** Parameters for logging in with an Out-of-Band (OOB) code after an MFA challenge. */
export interface LoginOobParameters extends RequestOptions {
  mfaToken: string;
  oobCode: string;
  bindingCode?: string;
}

/** Parameters for logging in with a recovery code after an MFA challenge. */
export interface LoginRecoveryCodeParameters extends RequestOptions {
  mfaToken: string;
  recoveryCode: string;
}

/** Parameters for requesting an MFA challenge. */
export interface MfaChallengeParameters extends RequestOptions {
  mfaToken: string;
  challengeType?: 'oob' | 'otp';
  authenticatorId?: string;
}

// ========= User Management & Profile Parameters =========

/** Parameters for accessing the `/userinfo` endpoint. */
export interface UserInfoParameters extends RequestOptions {
  token: string;
  /**
   * The type of the token. When 'DPoP', DPoP headers will be generated automatically.
   * Defaults to the client's configured token type.
   */
  tokenType?: TokenType;
}

/** Parameters for requesting a password reset email. */
export interface ResetPasswordParameters extends RequestOptions {
  email: string;
  connection: string;
  organization?: string;
}

/** Parameters for creating a new user in a database connection. */
export interface CreateUserParameters extends RequestOptions {
  email: string;
  password: string;
  connection: string;
  username?: string;
  given_name?: string;
  family_name?: string;
  name?: string;
  nickname?: string;
  picture?: string;
  metadata?: object;
}

/**
 * Parameters for patching a user's metadata via the Management API.
 * Requires an access token with `update:current_user_metadata` scope.
 */
export interface PatchUserParameters {
  /** The ID of the user to update (e.g., `auth0|12345`). */
  id: string;
  /** An object containing the metadata to set or update. */
  metadata: Record<string, any>;
}

/**
 * Parameters for retrieving a user's full profile from the Management API.
 * Requires an access token with `read:current_user` scope.
 */
export interface GetUserParameters {
  /** The ID of the user to retrieve. */
  id: string;
}