alegra-api-client

A lightweight and typed TypeScript client for the Alegra API, oriented toward the integration layer. It covers authentication, pagination, and rate limit handling with retries for contacts, items, and invoices resources. This is an unofficial project with no affiliation with Alegra; its documentation is in Spanish because, according to the author, there is little available. Authentication It uses HTTP Basic with email and API token (not the password). The token is generated in Alegra within the account's integrations/API section. The indicated base URL is https://api.alegra.com/api/v1, and authentication failures respond with HTTP 401. The README recommends storing credentials in environment variables rather than in the code; a .env.example file is included. Pagination The API returns a maximum of 30 records per page using the start (offset) and limit parameters. The client exposes an asynchronous generator to traverse page by page without loading everything into memory, in addition to methods to obtain a single page or collect all results. Available resources and their methods are: contacts (list, get, paginate, listAll), items (list, get, paginate, listAll), and invoices (list, get, paginate, listAll). For endpoints not covered, the direct client can be used with a generic request call that accepts query parameters. Rate limits and retries The README documents a limit of 150 requests per minute per user (approximately 2.5 per second). When exceeded, the API responds with HTTP 429 and reports the status in the X-Rate-Limit-Limit, X-Rate-Limit-Remaining, and X-Rate-Limit-Reset headers (remaining seconds to reset the window); according to the author, Alegra does not send Retry-After. The client automatically retries on 429 and 5xx: in the case of 429, it waits for the time indicated by X-Rate-Limit-Reset (or Retry-After if present) and, if neither exists, applies exponential backoff with jitter. 4xx errors are not retried, though retries occur for network failures. Mentioned configurable options include minRequestIntervalMs (preventive spacing between requests), maxRetries, retryBaseMs, and timeoutMs. The per-request timeout is implemented with AbortController. If retries for 429 are exhausted, an AlegraRateLimitError is thrown, which may include retryAfterSeconds. Errors The AlegraApiError (with status, endpoint, and body) and AlegraRateLimitError classes are exposed to distinguish API failures from exhausted usage limits. Requirements and development Requires Node.js 18 or higher due to the use of native fetch and has no runtime dependencies; it is presented as portable to Node, Deno, and edge environments. The development flow includes npm run build, tests with vitest using simulated fetch and dummy data, and type verification (lint:types). Examples use dummy data and credentials via environment variables. MIT License; the version listed in the changelog is 0.1.0, the first public version. Scope The README itself warns that the included Alegra API summary table must be updated if the official API changes, and that the summary exists due to the scarcity of documentation in Spanish. No performance claims or comparisons with other clients are offered.