SDK Architecture & Invariants

Behavior shared by all seven SmallPict SDKs: methods, options, retries, and credential handling.

SmallPict maintains 7 official SDKs. They follow each language's conventions but behave the same way.

Core methods

Every SDK implements the same four operations (names follow each language's conventions):

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)`	Purge cached images from the CDN.
`validateKey()`	Check that the credentials are valid and the account is active.
Helper: `getJobStatus(jobId)`	Poll status and download URLs for asynchronous background conversion jobs.

Optimization options

optimize() accepts an OptimizeOptions object that controls output format, dimensions, and compression mode:

Option	Type	Default	Description
`format`	`string`	`'auto'`	Target format: `'auto'`, `'avif'`, `'webp'`, `'jpeg'`, or `'png'`.
`lossless`	`boolean`	`false`	When `true`, enables lossless compression (pixel-perfect fidelity). When `false` (default), enables lossy compression.
`quality`	`number`	`80`	Quality level from `1` to `100`. Only applies in lossy mode (`lossless: false`). Ignored in lossless mode.
`maxWidth`	`number`	`null`	Maximum bounding width constraint in pixels (e.g. `1600`, `1920`).
`maxHeight`	`number`	`null`	Maximum bounding height constraint in pixels.
`stripMetadata`	`boolean`	`true`	Removes camera EXIF, GPS, and private metadata.

Choosing lossy or lossless

1. Lossy Mode (`lossless: false`, Default)

Activation: Set lossless: false (or omit it) and optionally specify quality (e.g. 80).
Typical savings: 70% to 85% smaller files with no visible difference on high-DPI screens.
Use for: E-commerce product photos, hero banners, blog photography, and user uploads.

2. Lossless Mode (`lossless: true`)

Activation: Set lossless: true.
Typical savings: 15% to 35%, with every pixel kept exactly.
Use for: Brand logos, sharp typography, technical line art, transparent UI assets, and medical/legal archival records.

Credential redaction

All SDKs mask credentials. Secret keys (sec_...) and API keys (sp_sdk_..., sp_wp_..., sp_test_...) are never printed in plain text in logs, debugger output, or stack traces:

TEXT

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

Retries and idempotency

1. 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. Idempotency keys (UUID v4)

Every mutating request automatically injects an Idempotency-Key header with a unique UUID v4. Retries after network errors are never billed twice.

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), the SDK returns the original image buffer you passed in, unchanged (savingsPercentage: 0.0), instead of throwing, so your application keeps working.