sec-edgar-toolkit
Version:
Open source toolkit to facilitate working with the SEC EDGAR database
294 lines • 10.5 kB
JavaScript
"use strict";
/**
* Comprehensive error classes for SEC EDGAR Toolkit
*
* This module provides a rich hierarchy of error classes for better
* error handling and debugging throughout the TypeScript SDK.
*/
Object.defineProperty(exports, "__esModule", { value: true });
exports.NotFoundError = exports.AuthenticationError = exports.SecEdgarApiError = exports.ErrorHandler = exports.ErrorWithContext = exports.CacheError = exports.InvalidUnitError = exports.ConceptNotFoundError = exports.XBRLError = exports.JSONParsingError = exports.XMLParsingError = exports.ParsingError = exports.FilingContentError = exports.FilingNotFoundError = exports.MultipleCompaniesFoundError = exports.CompanyNotFoundError = exports.InvalidFormTypeError = exports.InvalidDateError = exports.InvalidCIKError = exports.ValidationError = exports.NetworkError = exports.TimeoutError = exports.RequestError = exports.InvalidUserAgentError = exports.ConfigurationError = void 0;
const base_1 = require("./base");
/**
* Configuration errors
*/
class ConfigurationError extends base_1.SecEdgarApiError {
constructor(message, field) {
super(message);
this.field = field;
this.name = 'ConfigurationError';
}
}
exports.ConfigurationError = ConfigurationError;
class InvalidUserAgentError extends ConfigurationError {
constructor(userAgent) {
const message = userAgent
? `Invalid user agent format: "${userAgent}". Must include contact information.`
: 'User agent is required and must include contact information.';
super(message, 'userAgent');
this.name = 'InvalidUserAgentError';
}
}
exports.InvalidUserAgentError = InvalidUserAgentError;
/**
* API request errors
*/
class RequestError extends base_1.SecEdgarApiError {
constructor(message, url, statusCode, response) {
super(message, statusCode);
this.url = url;
this.statusCode = statusCode;
this.response = response;
this.name = 'RequestError';
}
}
exports.RequestError = RequestError;
class TimeoutError extends RequestError {
constructor(url, timeout) {
super(`Request timed out after ${timeout}ms`, url);
this.name = 'TimeoutError';
}
}
exports.TimeoutError = TimeoutError;
class NetworkError extends RequestError {
constructor(message, url, originalError) {
super(message, url);
this.originalError = originalError;
this.name = 'NetworkError';
}
}
exports.NetworkError = NetworkError;
/**
* Data validation errors
*/
class ValidationError extends base_1.SecEdgarApiError {
constructor(message, field, value) {
super(message);
this.field = field;
this.value = value;
this.name = 'ValidationError';
}
}
exports.ValidationError = ValidationError;
class InvalidCIKError extends ValidationError {
constructor(cik) {
super(`Invalid CIK format: "${cik}". CIK must be a number or numeric string.`, 'cik', cik);
this.name = 'InvalidCIKError';
}
}
exports.InvalidCIKError = InvalidCIKError;
class InvalidDateError extends ValidationError {
constructor(date, expectedFormat = 'YYYY-MM-DD') {
super(`Invalid date format: "${date}". Expected format: ${expectedFormat}`, 'date', date);
this.name = 'InvalidDateError';
}
}
exports.InvalidDateError = InvalidDateError;
class InvalidFormTypeError extends ValidationError {
constructor(formType, validTypes) {
const message = validTypes
? `Invalid form type: "${formType}". Valid types: ${validTypes.join(', ')}`
: `Invalid form type: "${formType}"`;
super(message, 'formType', formType);
this.name = 'InvalidFormTypeError';
}
}
exports.InvalidFormTypeError = InvalidFormTypeError;
/**
* Company lookup errors
*/
class CompanyNotFoundError extends base_1.SecEdgarApiError {
constructor(identifier, searchType) {
const message = `Company not found: ${identifier} (searched by ${searchType})`;
super(message, 404);
this.identifier = identifier;
this.searchType = searchType;
this.name = 'CompanyNotFoundError';
}
}
exports.CompanyNotFoundError = CompanyNotFoundError;
class MultipleCompaniesFoundError extends base_1.SecEdgarApiError {
constructor(identifier, count) {
super(`Multiple companies found for "${identifier}": ${count} matches`);
this.identifier = identifier;
this.count = count;
this.name = 'MultipleCompaniesFoundError';
}
}
exports.MultipleCompaniesFoundError = MultipleCompaniesFoundError;
/**
* Filing errors
*/
class FilingNotFoundError extends base_1.SecEdgarApiError {
constructor(accessionNumber, cik) {
const message = cik
? `Filing not found: ${accessionNumber} for CIK ${cik}`
: `Filing not found: ${accessionNumber}`;
super(message, 404);
this.accessionNumber = accessionNumber;
this.cik = cik;
this.name = 'FilingNotFoundError';
}
}
exports.FilingNotFoundError = FilingNotFoundError;
class FilingContentError extends base_1.SecEdgarApiError {
constructor(message, accessionNumber, contentType) {
super(message);
this.accessionNumber = accessionNumber;
this.contentType = contentType;
this.name = 'FilingContentError';
}
}
exports.FilingContentError = FilingContentError;
/**
* Parsing errors
*/
class ParsingError extends base_1.SecEdgarApiError {
constructor(message, documentType, section, originalError) {
super(message);
this.documentType = documentType;
this.section = section;
this.originalError = originalError;
this.name = 'ParsingError';
}
}
exports.ParsingError = ParsingError;
class XMLParsingError extends ParsingError {
constructor(message, lineNumber, columnNumber) {
const location = lineNumber && columnNumber
? ` at line ${lineNumber}, column ${columnNumber}`
: '';
super(`XML parsing error${location}: ${message}`, 'XML');
this.lineNumber = lineNumber;
this.columnNumber = columnNumber;
this.name = 'XMLParsingError';
}
}
exports.XMLParsingError = XMLParsingError;
class JSONParsingError extends ParsingError {
constructor(message, json) {
super(`JSON parsing error: ${message}`, 'JSON');
this.json = json;
this.name = 'JSONParsingError';
}
}
exports.JSONParsingError = JSONParsingError;
/**
* XBRL-specific errors
*/
class XBRLError extends base_1.SecEdgarApiError {
constructor(message, concept, taxonomy) {
super(message);
this.concept = concept;
this.taxonomy = taxonomy;
this.name = 'XBRLError';
}
}
exports.XBRLError = XBRLError;
class ConceptNotFoundError extends XBRLError {
constructor(concept, taxonomy = 'us-gaap') {
super(`XBRL concept not found: ${concept} in ${taxonomy}`, concept, taxonomy);
this.name = 'ConceptNotFoundError';
}
}
exports.ConceptNotFoundError = ConceptNotFoundError;
class InvalidUnitError extends XBRLError {
constructor(unit, validUnits) {
const message = validUnits
? `Invalid XBRL unit: "${unit}". Valid units: ${validUnits.join(', ')}`
: `Invalid XBRL unit: "${unit}"`;
super(message);
this.name = 'InvalidUnitError';
}
}
exports.InvalidUnitError = InvalidUnitError;
/**
* Cache errors
*/
class CacheError extends base_1.SecEdgarApiError {
constructor(message, operation) {
super(message);
this.operation = operation;
this.name = 'CacheError';
}
}
exports.CacheError = CacheError;
class ErrorWithContext extends base_1.SecEdgarApiError {
constructor(message, context, originalError) {
super(message);
this.context = context;
this.originalError = originalError;
this.name = 'ErrorWithContext';
}
toString() {
const contextStr = Object.entries(this.context)
.map(([key, value]) => `${key}=${value}`)
.join(', ');
return `${this.name}: ${this.message} [${contextStr}]`;
}
}
exports.ErrorWithContext = ErrorWithContext;
/**
* Error handler utility
*/
class ErrorHandler {
/**
* Wrap an error with additional context
*/
static wrapError(error, context, message) {
const finalMessage = message || error.message;
return new ErrorWithContext(finalMessage, context, error);
}
/**
* Convert unknown errors to SecEdgarApiError
*/
static normalize(error) {
if (error instanceof base_1.SecEdgarApiError) {
return error;
}
if (error instanceof Error) {
return new base_1.SecEdgarApiError(error.message);
}
if (typeof error === 'string') {
return new base_1.SecEdgarApiError(error);
}
return new base_1.SecEdgarApiError('An unknown error occurred');
}
/**
* Check if error is retryable
*/
static isRetryable(error) {
if (error instanceof base_1.RateLimitError)
return true;
if (error instanceof TimeoutError)
return true;
if (error instanceof NetworkError)
return true;
if (error instanceof RequestError) {
// Retry on 5xx errors (server errors)
if (error.statusCode && error.statusCode >= 500)
return true;
// Retry on 408 (Request Timeout)
if (error.statusCode === 408)
return true;
}
return false;
}
/**
* Get retry delay for an error
*/
static getRetryDelay(error, attempt) {
if (error instanceof base_1.RateLimitError) {
// Use longer delay for rate limits
return Math.min(60000, Math.pow(2, attempt) * 5000);
}
// Exponential backoff for other errors
return Math.min(30000, Math.pow(2, attempt) * 1000);
}
}
exports.ErrorHandler = ErrorHandler;
// Re-export base errors
var base_2 = require("./base");
Object.defineProperty(exports, "SecEdgarApiError", { enumerable: true, get: function () { return base_2.SecEdgarApiError; } });
Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return base_2.AuthenticationError; } });
Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return base_2.NotFoundError; } });
//# sourceMappingURL=errors.js.map