alegra-api-client

통합 계층을 위해 설계된 Alegra API용 경량 TypeScript 타입드 클라이언트입니다. 연락처, 품목, 송장 리소스에 대해 인증, 페이지네이션 및 재시도를 포함한 속도 제한 처리를 지원합니다. 이 프로젝트는 Alegra와 제휴하지 않은 비공식 프로젝트이며, 저자에 따르면 공식 문서가 부족하여 스페인어로 문서화되었습니다. 인증 이메일과 API 토큰(비밀번호 아님)을 사용하는 HTTP Basic 인증을 사용합니다. 토큰은 Alegra 계정의 통합/API 섹션에서 생성합니다. 기본 URL은 https://api.alegra.com/api/v1이며, 인증 실패 시 HTTP 401 응답을 반환합니다. README에서는 자격 증명을 코드에 직접 작성하지 말고 환경 변수에 저장할 것을 권장하며, .env.example 파일이 포함되어 있습니다. 페이지네이션 API는 start(오프셋) 및 limit 파라미터를 통해 페이지당 최대 30개의 레코드를 반환합니다. 클라이언트는 모든 데이터를 메모리에 로드하지 않고 페이지별로 탐색할 수 있는 비동기 제너레이터와 단일 페이지 가져오기 또는 모든 결과 수집 메서드를 제공합니다. 지원되는 리소스 및 메서드는 연락처(목록, 가져오기, 페이지네이션, 전체 목록), 품목(목록, 가져오기, 페이지네이션, 전체 목록), 송장(목록, 가져오기, 페이지네이션, 전체 목록)입니다. 지원되지 않는 엔드포인트의 경우 쿼리 파라미터를 허용하는 일반 request 호출을 통해 직접 클라이언트를 사용할 수 있습니다. 속도 제한 및 재시도 README에 따르면 사용자당 분당 150회(초당 약 2.5회)의 요청 제한이 있습니다. 이를 초과하면 API는 HTTP 429를 반환하며 X-Rate-Limit-Limit, X-Rate-Limit-Remaining, X-Rate-Limit-Reset(초 단위 리셋 대기 시간) 헤더를 통해 상태를 알립니다. 저자에 따르면 Alegra는 Retry-After 헤더를 보내지 않습니다. 클라이언트는 429 및 5xx 오류 발생 시 자동으로 재시도합니다. 429의 경우 X-Rate-Limit-Reset(또는 Retry-After가 있는 경우 해당 값)만큼 대기하며, 둘 다 없는 경우 지터(jitter)가 포함된 지수 백오프를 적용합니다. 4xx 오류는 재시도하지 않으며, 네트워크 오류 시에도 재시도합니다. 설정 가능한 옵션으로는 minRequestIntervalMs(요청 간 예방적 간격), maxRetries, retryBaseMs, timeoutMs가 있습니다. 요청 타임아웃은 AbortController로 구현됩니다. 429 재시도가 모두 소진되면 retryAfterSeconds를 포함할 수 있는 AlegraRateLimitError가 발생합니다. 오류 처리 API 오류와 사용 제한 오류를 구분하기 위해 AlegraApiError(status, endpoint, body 포함) 및 AlegraRateLimitError 클래스가 제공됩니다. 요구 사항 및 개발 네이티브 fetch 사용을 위해 Node.js 18 이상이 필요하며, 런타임 의존성이 없어 Node, Deno 및 엣지 환경으로 이식이 가능합니다. 개발 흐름은 npm run build, 모의 fetch 및 가상 데이터를 이용한 vitest 테스트, 타입 검사(lint:types)를 포함합니다. 예제는 가상 데이터와 환경 변수 자격 증명을 사용합니다. MIT 라이선스를 따르며, 변경 로그에 기재된 버전은 첫 공개 버전인 0.1.0입니다. 범위 README에서는 포함된 Alegra API 요약 표가 공식 API 변경 시 업데이트되어야 하며, 스페인어 문서 부족으로 인해 요약본을 작성했음을 명시하고 있습니다. 성능에 대한 주장이나 다른 클라이언트와의 비교는 제공되지 않습니다.