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パラメータを使用して、1ページあたり最大30件のレコードを返します。本クライアントは、メモリにすべてを読み込むことなくページごとに走査できる非同期ジェネレータに加え、単一ページの取得や全結果の収集メソッドを提供しています。利用可能なリソースとメソッドは、連絡先（リスト、取得、ページネーション、全リスト）、アイテム（リスト、取得、ページネーション、全リスト）、請求書（リスト、取得、ページネーション、全リスト）です。カバーされていないエンドポイントについては、クエリパラメータを受け付ける汎用的なrequestメソッドを使用して直接クライアントを操作できます。 レート制限とリトライ READMEには、ユーザーあたり1分間に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がスローされます。 エラー処理 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の変更に合わせて更新する必要があること、また、スペイン語のドキュメントが不足しているためこの要約が存在することが警告されています。パフォーマンスに関する主張や他のクライアントとの比較は提供されていません。