Arsitektur & Standar SDK Resmi

Prinsip desain terpadu, jaminan keamanan, dan ketahanan jaringan di seluruh 7 SDK resmi SmallPict.

SmallPict menyediakan 7 SDK resmi yang dibangun dengan standar arsitektur terpadu di berbagai bahasa pemrograman modern.

Antarmuka Terpadu 4 Metode Utama

Setiap SDK resmi mengimplementasikan 4 operasi utama yang sama:

Metode	Deskripsi
`optimize(source, options)`	Mengompresi dan mengonversi format gambar (AVIF, WebP, JPEG, PNG).
`getQuota()`	Mengambil informasi pemakaian kuota dan metrik bandwidth CDN.
`purgeCdn(urls, purgeType)`	Membersihkan cache CDN edge global.
`validateKey()`	Melakukan pengecekan kesehatan kredensial tanpa efek samping.
Helper: `getJobStatus(jobId)`	Memantau status proses konversi asinkron.

Opsi Optimasi: Mode Lossy vs Lossless

Seluruh SDK resmi menerima objek OptimizeOptions pada method optimize() untuk mengontrol format gambar, dimensi, dan mode kompresi:

Opsi	Tipe	Nilai Bawaan	Deskripsi
`format`	`string`	`'auto'`	Format output target: `'auto'`, `'avif'`, `'webp'`, `'jpeg'`, atau `'png'`.
`lossless`	`boolean`	`false`	Ketika `true`, mengaktifkan kompresi lossless (kualitas 100% pixel-perfect). Ketika `false` (default), menggunakan kompresi lossy.
`quality`	`number`	`80`	Tingkat kualitas kompresi dari `1` hingga `100`. Hanya berlaku pada mode lossy (`lossless: false`). Pada mode lossless, parameter ini diabaikan secara aman.
`maxWidth`	`number`	`null`	Batas lebar maksimum gambar dalam pixel (misal `1600`, `1920`).
`maxHeight`	`number`	`null`	Batas tinggi maksimum gambar dalam pixel.
`stripMetadata`	`boolean`	`true`	Menghapus metadata kamera EXIF, lokasi GPS, dan profil perangkat.

Panduan Memilih Mode Lossy vs Lossless

1. Mode Lossy (`lossless: false`, Bawaan / Rekomendasi Umum)

Cara Mengaktifkan: Set lossless: false (atau tidak perlu ditulis karena default) dan atur quality (misal: 80).
Efisiensi Ukuran: Memangkas ukuran file sebesar 70% hingga 85% dengan visual yang tetap tajam di layar Retina.
Cocok Untuk: Foto produk toko online, banner hero, foto artikel blog, dan gambar media sosial.

2. Mode Lossless (`lossless: true`)

Cara Mengaktifkan: Set lossless: true.
Efisiensi Ukuran: Menghemat sekitar 15% hingga 35% dengan mengoptimalkan tabel entropi internal dan stream Deflate tanpa mengubah nilai piksel satu bit pun.
Cocok Untuk: Logo perusahaan, grafis tipografi tajam, aset ikon UI PNG transparan, diagram teknis, serta arsip medis/legal.

Masking Kredensial Zero-Leak

Seluruh SDK mengimplementasikan penyamaran kredensial otomatis menggunakan regex. Kunci rahasia (sec_...) dan API key (sp_sdk_..., sp_wp_..., sp_test_...) tidak pernah ditampilkan dalam bentuk teks polos pada log aplikasi atau stack trace error:

TEXT

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

Ketahanan Jaringan & Idempotensi

Exponential Backoff dengan Jitter: Saat menerima error HTTP 429 atau 5xx, SDK secara cerdas melakukan retry otomatis hingga 3 kali dengan jeda waktu eksponensial.
Idempotency Key Otomatis (UUID v4): Setiap request mutasi otomatis menyertakan header idempotency unik agar retry jaringan tidak menimbulkan duplikasi tagihan.
Mode Fallback: Mendukung mode throw (melempar exception) dan passthrough (mengembalikan buffer asli jika kuota habis agar website tetap berjalan normal).