parameters.ts

/** A base interface for API calls that allow passing custom headers. */
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 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 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;
}

/** 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;
}

/** 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;
}