这个项目能做什么

这是一个面向集成层的轻量级 TypeScript 类型化 Alegra API 客户端。它涵盖了联系人、项目和发票资源的认证、分页及速率限制重试处理。该项目是非官方的，与 Alegra 无隶属关系；由于作者认为可用文档较少，因此文档以西班牙语编写。 认证 使用包含电子邮件和 API 令牌（而非密码）的 HTTP Basic 认证。令牌在 Alegra 账户的集成/API 部分生成。基础 URL 为 https://api.alegra.com/api/v1，认证失败将返回 HTTP 401。README 建议将凭据存储在环境变量中而非代码中，并提供了一个 .env.example 文件。 分页 API 通过 start（偏移量）和 limit 参数每页最多返回 30 条记录。客户端提供了一个异步生成器，用于逐页遍历而无需将所有数据加载到内存中，此外还提供了获取单页或收集所有结果的方法。可用资源及其方法包括：contactos（列出、获取、分页、列出所有）、items（列出、获取、分页、列出所有）和 facturas（列出、获取、分页、列出所有）。对于未涵盖的端点，可以使用接受查询参数的通用 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，如果存在）指示的时间；若两者均不存在，则应用带有抖动的指数退避。4xx 错误不进行重试，但网络故障会触发重试。可配置选项包括：minRequestIntervalMs（请求间的预防性间隔）、maxRetries、retryBaseMs 和 timeoutMs。单次请求的超时通过 AbortController 实现。如果 429 重试次数耗尽，将抛出可能包含 retryAfterSeconds 的 AlegraRateLimitError。 错误处理 提供了 AlegraApiError（包含状态、端点和正文）和 AlegraRateLimitError 类，以区分 API 故障与用量限制耗尽。 要求与开发 由于使用了原生 fetch，要求 Node.js 18 或更高版本，且没有运行时依赖；可移植到 Node、Deno 和 Edge 环境。开发流程包括 npm run build、使用 vitest 对模拟 fetch 和虚拟数据进行测试，以及类型检查（lint:types）。示例使用虚拟数据和环境变量凭据。采用 MIT 许可证；changelog 中列出的版本为 0.1.0，为首个公开版本。 范围 README 警告称，如果官方 API 发生变化，随附的 Alegra API 摘要表需要更新，且该摘要的存在是因为缺乏西班牙语文档。未提供性能声明或与其他客户端的比较。