AvnologyIdError
 +-- AuthError
 |    +-- InvalidCredentialsError
 |    +-- AccountLockedError
 |    +-- AccountDisabledError
 |    +-- MfaRequiredError
 |    +-- InvalidCodeError
 |    +-- ExpiredFlowError
 |    +-- PasswordBreachedError
 |    +-- PasswordTooWeakError
 |    +-- DuplicateAccountError
 |    +-- RegistrationDisabledError
 |    +-- MethodDisabledError
 |    +-- MfaAlreadyEnrolledError
 +-- OAuthError
 |    +-- InvalidGrantError
 |    +-- InvalidClientError
 |    +-- InvalidScopeError
 |    +-- InvalidRedirectUriError
 |    +-- ExpiredCodeError
 |    +-- DeviceFlowExpiredError
 |    +-- DeviceFlowDeniedError
 |    +-- InsufficientScopeError
 +-- ApiError
 |    +-- NotFoundError
 |    +-- ForbiddenError
 |    +-- UnauthorizedError
 |    +-- ConflictError
 |    +-- ValidationError
 |    +-- DuplicateError
 +-- RateLimitError
 +-- NetworkError
 +-- TimeoutError

class AvnologyIdError extends Error {
  /** Machine-readable error code (e.g., "AVNOLOGY_AUTH_001") */
  code: string;

  /** HTTP status code (if applicable) */
  statusCode: number | null;

  /** Human-readable error message */
  message: string;

  /** Request ID for support debugging */
  requestId: string | null;

  /** Additional error details */
  details: Record<string, unknown>;
}

class InvalidCredentialsError extends AuthError {
  code: "AVNOLOGY_AUTH_001";
  statusCode: 401;
}

class AccountLockedError extends AuthError {
  code: "AVNOLOGY_AUTH_002";
  statusCode: 423;
  retryAfter: number;  // Seconds until unlock
}

class MfaRequiredError extends AuthError {
  code: "AVNOLOGY_AUTH_004";
  statusCode: 403;
  flowId: string;                    // Flow ID for MFA verification
  availableMethods: MfaMethod[];     // ["totp", "webauthn", "recovery_code"]
}

class InvalidCodeError extends AuthError {
  code: "AVNOLOGY_AUTH_006";
  statusCode: 400;
  attemptsRemaining: number;  // Remaining attempts before lockout
}

class ValidationError extends ApiError {
  code: "AVNOLOGY_API_422";
  statusCode: 422;
  fieldErrors: FieldError[];
}

interface FieldError {
  field: string;       // "email", "traits.phone", "password"
  message: string;     // "Invalid email format"
  code: string;        // "invalid_format", "too_short", "required"
}

class RateLimitError extends AvnologyIdError {
  code: "AVNOLOGY_API_429";
  statusCode: 429;
  retryAfter: number;      // Seconds until rate limit resets
  limit: number;            // Request limit
  remaining: number;        // Remaining requests (always 0)
  resetAt: string;          // ISO 8601 reset time
}

import {
  InvalidCredentialsError,
  MfaRequiredError,
  RateLimitError,
} from "@avnology/sdk-typescript";

try {
  await client.login({ email, password });
} catch (error) {
  if (error instanceof InvalidCredentialsError) {
    // Handle wrong credentials
  } else if (error instanceof MfaRequiredError) {
    // Handle MFA challenge
  } else if (error instanceof RateLimitError) {
    // Handle rate limit
  } else {
    // Unknown error
    throw error;
  }
}

import { AvnologyIdError } from "@avnology/sdk-typescript";

try {
  await client.admin.getUser({ userId: "usr_nonexistent" });
} catch (error) {
  if (error instanceof AvnologyIdError) {
    switch (error.code) {
      case "AVNOLOGY_API_404":
        console.log("User not found");
        break;
      case "AVNOLOGY_API_403":
        console.log("Permission denied");
        break;
      default:
        console.log("Error:", error.code, error.message);
    }
  }
}

import { AvnologyIdError } from "@avnology/sdk-typescript";

try {
  await someOperation();
} catch (error) {
  if (error instanceof AvnologyIdError && error.requestId) {
    console.error(
      `Avnology ID error: ${error.code} (request: ${error.requestId})`
    );
    // Provide request ID to support for debugging
  }
}