公式SDKアーキテクチャと設計方針

全7つの公式SmallPict SDKが準拠する統一インターフェース、セキュリティ保証、および耐障害性。

SmallPictは、現代の主要なプログラミング言語向けに 7つの公式SDK を提供しており、どの技術スタックでも一貫性のある堅牢な開発体験を保証します。

統一された4つの基本インターフェース

言語や命名規則に関わらず、すべての公式SDKは以下の4つの基本操作を厳格に実装しています：

メソッド名	機能概要
`optimize(source, options)`	画像バイナリやURLを圧縮、変換（AVIF, WebP, JPEG, PNG）、リサイズ
`getQuota()`	処理済みバイト数、月間クォータ上限、CDN帯域幅の消費状況を取得
`purgeCdn(urls, purgeType)`	SmallPict Edge PoPノード上のキャッシュを即時無効化
`validateKey()`	認証情報の疎通確認およびアカウント状態の検証
補助: `getJobStatus(jobId)`	非同期変換ジョブの進捗と完了URLをポーリング取得

認証情報のゼロリーク秘匿化

すべてのSDKに正規表現ベースの秘匿化エンジンが組み込まれています。シークレットキー (sec_...) やAPIキー (sp_sdk_..., sp_wp_..., sp_test_...) が、標準出力、デバッガ、例外スタックトレースに平文で出力されることは決してありません：

TEXT

ログ出力例: "Request failed for key sp_sdk_9a8b...c4d3 and secret ***REDACTED***"

高弾力性リクエストパイプラインと冪等性

1. ジッター付き指数バックオフ再試行

HTTP 429 (レート制限) や一時的な 5xx サーバーエラーが発生した場合、SDKはランダムな揺らぎ（ジッター）を含む指数バックオフを用いて自動的に再試行します（デフォルト: 最大3回）：

TEXT

delay = baseDelay * (2 ^ (attempt - 1)) + jitter

レスポンスに Retry-After ヘッダーが含まれている場合は、その指定待機時間を厳格に遵守します。

2. UUID v4 冪等性キーの自動付与

すべての更新リクエストには、SDKによって一意の Idempotency-Key が自動付与されます。ネットワーク断による再試行でも、二重課金や二重処理が発生することはありません。

フォールバックモードの選択

すべてのSDKで fallbackMode を指定できます：

throw モード (デフォルト): クォータ上限到達時に型付きの QuotaExceededError を発生させます。
passthrough モード: 高い可用性が求められる本番サービス向け。HTTP 402（クォータ上限）時にもシステムを停止させず、元の未圧縮画像Bufferをそのまま返却し（savingsPercentage: 0.0）、サービスの中断を回避します。