@lgriffin/esi.ts 10.2.0 → 11.0.0

package/dist/chunk-JNFQXEWZ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/util/error.ts"],"sourcesContent":["const SENSITIVE_PARAMS = [\n  'token',\n  'access_token',\n  'api_key',\n  'refresh_token',\n  'client_secret',\n  'code',\n  'key',\n  'secret',\n  'auth',\n  'password',\n  'bearer',\n];\n\n/**\n * Matches text that may carry a query parameter `sanitizeUrl` redacts: one of\n * the names above, or a percent-encoded name it could decode to. A cheap\n * prefilter, so a line without one skips URL parsing entirely.\n */\nexport const SENSITIVE_QUERY_PATTERN: RegExp = new RegExp(\n  `[?&](?:(?:${SENSITIVE_PARAMS.join('|')})(?![A-Za-z0-9_])|[^?&=\\\\s]*%)`,\n);\n\nconst SENSITIVE_PARAM_SET: ReadonlySet<string> = new Set(SENSITIVE_PARAMS);\n\n/**\n * Whether a query parameter name, as written in a URL (percent-encoded or\n * not), is one `sanitizeUrl` redacts.\n */\nexport function isSensitiveQueryParam(rawName: string): boolean {\n  if (SENSITIVE_PARAM_SET.has(rawName)) return true;\n  try {\n    return SENSITIVE_PARAM_SET.has(\n      decodeURIComponent(rawName.replace(/\\+/g, ' ')),\n    );\n  } catch {\n    return false;\n  }\n}\n\nexport function sanitizeUrl(url?: string): string | undefined {\n  if (!url) return url;\n  try {\n    const parsed = new URL(url);\n    for (const param of SENSITIVE_PARAMS) {\n      if (parsed.searchParams.has(param)) {\n        parsed.searchParams.set(param, '[REDACTED]');\n      }\n    }\n    return parsed.toString();\n  } catch {\n    const qIndex = url.indexOf('?');\n    return qIndex >= 0 ? url.substring(0, qIndex) + '?[params-redacted]' : url;\n  }\n}\n\nexport class EsiError extends Error {\n  public readonly url?: string | undefined;\n\n  constructor(\n    public readonly statusCode: number,\n    message: string,\n    url?: string,\n    public readonly requestId?: string,\n  ) {\n    super(message);\n    this.name = 'EsiError';\n    this.url = sanitizeUrl(url);\n  }\n\n  isRateLimited(): boolean {\n    return this.statusCode === 420 || this.statusCode === 429;\n  }\n\n  isNotFound(): boolean {\n    return this.statusCode === 404;\n  }\n\n  isUnauthorized(): boolean {\n    return this.statusCode === 401;\n  }\n\n  isForbidden(): boolean {\n    return this.statusCode === 403;\n  }\n\n  isServerError(): boolean {\n    return this.statusCode >= 500;\n  }\n\n  isTimeout(): boolean {\n    return this.statusCode === 0;\n  }\n\n  get retryable(): boolean {\n    return (\n      this.statusCode === 0 ||\n      this.statusCode === 420 ||\n      this.statusCode === 429 ||\n      this.statusCode === 502 ||\n      this.statusCode === 503 ||\n      this.statusCode === 504\n    );\n  }\n}\n\nexport function isEsiError(error: unknown): error is EsiError {\n  return error instanceof EsiError;\n}\n\nexport function isRateLimited(error: unknown): error is EsiError {\n  return error instanceof EsiError && error.isRateLimited();\n}\n\nexport function isNotFound(error: unknown): error is EsiError {\n  return error instanceof EsiError && error.isNotFound();\n}\n\nexport function isUnauthorized(error: unknown): error is EsiError {\n  return error instanceof EsiError && error.isUnauthorized();\n}\n\nexport function isForbidden(error: unknown): error is EsiError {\n  return error instanceof EsiError && error.isForbidden();\n}\n\nexport function isServerError(error: unknown): error is EsiError {\n  return error instanceof EsiError && error.isServerError();\n}\n\nexport class TimeoutError extends EsiError {\n  constructor(\n    public readonly timeoutMs: number,\n    url?: string,\n    requestId?: string,\n  ) {\n    super(0, `Request timed out after ${timeoutMs}ms`, url, requestId);\n    this.name = 'TimeoutError';\n  }\n}\n\nexport function isTimeout(error: unknown): error is TimeoutError {\n  return error instanceof TimeoutError;\n}\n\nexport function isRetryable(error: unknown): error is EsiError {\n  return error instanceof EsiError && error.retryable;\n}\n\n/**\n * Raised by the circuit breaker before a request is sent, while the breaker\n * for its endpoint is open or its half-open probe slot is taken. Status `0`;\n * never retried by the client (wait `retryAfterMs` instead).\n */\nexport class CircuitOpenError extends EsiError {\n  readonly endpoint: string;\n  readonly failures: number;\n  readonly retryAfterMs: number;\n\n  constructor(endpoint: string, failures: number, retryAfterMs: number) {\n    super(\n      0,\n      `Circuit breaker open for ${endpoint} after ${failures} failures (retry after ${Math.ceil(retryAfterMs / 1000)}s)`,\n    );\n    this.name = 'CircuitOpenError';\n    this.endpoint = endpoint;\n    this.failures = failures;\n    this.retryAfterMs = retryAfterMs;\n  }\n\n  override get retryable(): boolean {\n    return false;\n  }\n\n  override isTimeout(): boolean {\n    return false;\n  }\n}\n\nexport function isCircuitOpen(error: unknown): error is CircuitOpenError {\n  return error instanceof CircuitOpenError;\n}\n\n/**\n * A request that failed below HTTP: DNS, a reset connection, TLS, or a body\n * that stopped arriving. Status `0`, retryable; the underlying error is on\n * `cause`. A timeout is a {@link TimeoutError} instead.\n */\nexport class EsiNetworkError extends EsiError {\n  override readonly cause: unknown;\n\n  constructor(reason: string, url?: string, cause?: unknown) {\n    super(0, `Network request failed: ${reason}`, url);\n    this.name = 'EsiNetworkError';\n    this.cause = cause;\n  }\n\n  override isTimeout(): boolean {\n    return false;\n  }\n}\n\nexport function isNetworkError(error: unknown): error is EsiNetworkError {\n  return error instanceof EsiNetworkError;\n}\n\n/** The code carried by an {@link EsiFaultError}; also its message prefix. */\nexport type EsiFaultCode =\n  | 'VALIDATION_ERROR'\n  | 'NO_AUTH_TOKEN'\n  | 'CONFIGURATION_ERROR'\n  | 'JSON_PARSE_ERROR'\n  | 'PAGINATION_INCOMPLETE'\n  | 'TOKEN_REFRESH_FAILED'\n  | 'ESIJS_ERROR';\n\n/**\n * A failure raised by the library itself rather than by ESI: bad\n * configuration or arguments, an unparseable body, an interrupted page walk,\n * a failed token refresh, or an unexpected error. Status `0`, never\n * retryable. The message starts with `[<code>]`.\n */\nexport class EsiFaultError extends EsiError {\n  readonly code: EsiFaultCode;\n  override readonly cause: unknown;\n\n  constructor(\n    code: EsiFaultCode,\n    message: string,\n    url?: string,\n    cause?: unknown,\n  ) {\n    super(0, `[${code}] ${message}`, url);\n    this.name = 'EsiFaultError';\n    this.code = code;\n    this.cause = cause;\n  }\n\n  override get retryable(): boolean {\n    return false;\n  }\n\n  override isTimeout(): boolean {\n    return false;\n  }\n}\n\nexport function isFaultError(error: unknown): error is EsiFaultError {\n  return error instanceof EsiFaultError;\n}\n\n/**\n * The client's setup or a call's arguments are wrong: an invalid base URL or\n * parameter (`VALIDATION_ERROR`), no access token for an authenticated\n * endpoint (`NO_AUTH_TOKEN`), or a missing dependency\n * (`CONFIGURATION_ERROR`). Fix the code; retrying cannot help.\n */\nexport class EsiConfigurationError extends EsiFaultError {\n  constructor(\n    code: 'VALIDATION_ERROR' | 'NO_AUTH_TOKEN' | 'CONFIGURATION_ERROR',\n    message: string,\n  ) {\n    super(code, message);\n    this.name = 'EsiConfigurationError';\n  }\n}\n\nexport function isConfigurationError(\n  error: unknown,\n): error is EsiConfigurationError {\n  return error instanceof EsiConfigurationError;\n}\n\n/** A response body that is not the JSON it should be (`JSON_PARSE_ERROR`). */\nexport class EsiParseError extends EsiFaultError {\n  constructor(message: string, url?: string, cause?: unknown) {\n    super('JSON_PARSE_ERROR', message, url, cause);\n    this.name = 'EsiParseError';\n  }\n}\n\nexport function isParseError(error: unknown): error is EsiParseError {\n  return error instanceof EsiParseError;\n}\n\n/**\n * A page walk that stopped part way on a failure that is not itself an\n * `EsiError` (`PAGINATION_INCOMPLETE`). The page's error is on `cause`.\n */\nexport class EsiPaginationError extends EsiFaultError {\n  constructor(where: string, cause: unknown) {\n    const safeWhere = sanitizeUrl(where) ?? where;\n    const reason = cause instanceof Error ? cause.message : String(cause);\n    super(\n      'PAGINATION_INCOMPLETE',\n      `Pagination incomplete for ${safeWhere}: ${reason}`,\n      where,\n      cause,\n    );\n    this.name = 'EsiPaginationError';\n  }\n}\n\nexport function isPaginationError(error: unknown): error is EsiPaginationError {\n  return error instanceof EsiPaginationError;\n}\n\n/**\n * The token provider threw while refreshing after a 401\n * (`TOKEN_REFRESH_FAILED`). What it threw, such as a `TokenRevokedError` or\n * `SsoError`, is on `cause`.\n */\nexport class EsiTokenRefreshError extends EsiFaultError {\n  constructor(cause: unknown) {\n    const reason = cause instanceof Error ? cause.message : String(cause);\n    super(\n      'TOKEN_REFRESH_FAILED',\n      `Token refresh failed: ${reason}`,\n      undefined,\n      cause,\n    );\n    this.name = 'EsiTokenRefreshError';\n  }\n}\n\nexport function isTokenRefreshError(\n  error: unknown,\n): error is EsiTokenRefreshError {\n  return error instanceof EsiTokenRefreshError;\n}\n\n/**\n * Wrap anything that is not already an `EsiError` so every failure the\n * client surfaces is one (`ESIJS_ERROR`, original on `cause`).\n */\nexport function toEsiError(error: unknown): EsiError {\n  if (error instanceof EsiError) return error;\n  const message = error instanceof Error ? error.message : String(error);\n  return new EsiFaultError('ESIJS_ERROR', message, undefined, error);\n}\n\nexport type ValidationDirection = 'request' | 'response';\n\nexport class EsiValidationError extends EsiError {\n  public readonly validationError: unknown;\n  public readonly direction: ValidationDirection;\n\n  constructor(\n    url: string,\n    zodError: unknown,\n    requestId?: string,\n    direction: ValidationDirection = 'response',\n  ) {\n    const safeUrl = sanitizeUrl(url) ?? url;\n    const label = direction === 'request' ? 'Request body' : 'Response';\n    super(0, `${label} validation failed for ${safeUrl}`, url, requestId);\n    this.name = 'EsiValidationError';\n    this.validationError = zodError;\n    this.direction = direction;\n  }\n\n  /** The same request returns the same body, so a retry cannot help. */\n  override get retryable(): boolean {\n    return false;\n  }\n\n  override isTimeout(): boolean {\n    return false;\n  }\n}\n\nexport function isValidationError(error: unknown): error is EsiValidationError {\n  return error instanceof EsiValidationError;\n}\n"],"mappings":"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","names":[]}