SDK Architecture & Invariants

Unified design principles, security guarantees, and fault-tolerance semantics across all 7 SmallPict SDKs.

Official SDK Architecture & Invariants

SmallPict provides 7 official SDKs engineered to provide a uniform, idiomatic, and rock-solid developer experience across modern programming languages.

🏛️ Unified 4-Method Core Interface

Regardless of programming language or naming convention, every official SmallPict SDK implements the exact same 4 fundamental operations:

Method	Description
`optimize(source, options)`	Compress, convert (AVIF, WebP, JPEG, PNG), and resize image binaries or URLs.
`getQuota()`	Retrieve real-time processed bytes, monthly quota, and CDN bandwidth metrics.
`purgeCdn(urls, purgeType)`	Instantly flush cached images across global Cloudflare Edge Points of Presence.
`validateKey()`	Perform non-destructive credential health checks and verify account status.
Helper: `getJobStatus(jobId)`	Poll status and download URLs for asynchronous background conversion jobs.

🛡️ Zero-Leak Credential Redaction

All SDKs implement strict regex-based credential masking. Secret keys (sec_...) and API keys (sp_live_..., sp_test_...) are never printed in plaintext in standard output, debugger inspection, or error stack traces:

TEXT

Log Output: "Request failed for key sp_live_9a8b...c4d3 and secret ***REDACTED***"

🔄 Resilient Request Pipeline & Idempotency

1. Bounded Exponential Backoff with Jitter

When an API request encounters HTTP 429 (Too Many Requests) or transient HTTP 5xx (500, 502, 503, 504), SDKs automatically retry up to maxRetries (default: 3) using exponential backoff:

TEXT

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

If the server provides a Retry-After header, the SDK respects that duration.

2. Automatic Idempotency Keys (UUID v4)

Every mutating request automatically injects an Idempotency-Key header with a unique UUID v4. Transient network drops or retries will never result in duplicate optimization charges.

🔀 Fallback Modes: Throw vs Passthrough

Every SDK supports the fallbackMode configuration option:

throw (Default): Throws a typed QuotaExceededError when limits are reached.
passthrough: On HTTP 402 (Quota Exceeded), rather than throwing an unhandled exception, the SDK gracefully returns the original uncompressed image buffer (savingsPercentage: 0.0), ensuring zero application downtime.