Unofficial multi-provider TypeScript SDK for shipping rate checking and tracking in Indonesia. Not affiliated with, endorsed by, or officially connected to Biteship, Komerce (RajaOngkir), or any courier service.
Dokumentasi lengkap: ongkir-sdk docs — panduan Bahasa Indonesia (instalasi, quickstart, setup provider, error handling, caching, webhooks, testing) plus API reference TypeDoc untuk setiap package.
- Satu contract untuk semua provider (
ShippingProvider) — cek ongkir, tracking resi, parse webhook, dan buat shipment dengan API yang sama, apa pun provider di baliknya. - 3 provider Indonesia siap pakai: Biteship, Komerce (RajaOngkir), dan Shipper — ganti provider cukup ganti satu baris config.
- Error ternormalisasi (
ShippingSDKError) — kode error konsisten lintas provider, plus flagretryableuntuk keputusan retry. - Bring-your-own-key — SDK murni client-side, tidak menyimpan atau mem-proxy API key kamu.
- Runtime-agnostic — Node ≥18, Bun, Deno, dan Cloudflare Workers (Web-standard API).
- Opsional: wrapper caching in-memory (
@ongkir-sdk/cache-memory) dan REST middleware Hono (@ongkir-sdk/hono).
| Package | Description | Version | Status |
|---|---|---|---|
@ongkir-sdk/core |
Types, contract, errors, shared contract test suite | |
✅ released |
@ongkir-sdk/biteship |
Biteship adapter (rates, tracking, webhook, shipment) |  |
✅ released |
@ongkir-sdk/komerce |
Komerce (RajaOngkir) adapter (rates, tracking) |  |
✅ released |
@ongkir-sdk/shipper |
Shipper adapter (rates, tracking, webhook, shipment) |  |
✅ released |
@ongkir-sdk/cache-memory |
In-memory cache wrapper around any provider (rates only) |  |
✅ released |
@ongkir-sdk/hono |
Hono middleware — expose providers as REST routes |  |
✅ released |
Install core + adapter yang kamu pakai. Adapter otomatis ber-dependency ke @ongkir-sdk/core.
npm install @ongkir-sdk/core @ongkir-sdk/biteship
# atau: npm install @ongkir-sdk/core @ongkir-sdk/komerce
# atau: npm install @ongkir-sdk/core @ongkir-sdk/shipperPaket opsional:
npm install @ongkir-sdk/hono # REST middleware (butuh hono + zod)
npm install @ongkir-sdk/cache-memory # wrapper caching hasil getRatesimport { BiteshipProvider } from '@ongkir-sdk/biteship'
import { KomerceProvider } from '@ongkir-sdk/komerce'
import { ShipperProvider } from '@ongkir-sdk/shipper'
const provider = new KomerceProvider({ apiKey: process.env.RAJAONGKIR_API_KEY! })
const rates = await provider.getRates({
origin: { postalCode: '12440' },
destination: { postalCode: '12240' },
items: [{ weightGrams: 1000, value: 199000, quantity: 1 }],
})
const tracking = await provider.trackShipment('AWB001', { courier: 'jne' })Provider Shipper memakai flow yang sama, tapi wajib postalCode di origin/destination (area_id di-resolve otomatis oleh adapter):
const shipper = new ShipperProvider({ apiKey: process.env.SHIPPER_API_KEY! })
const shipperRates = await shipper.getRates({
origin: { postalCode: '10110' },
destination: { postalCode: '40111' },
items: [{ weightGrams: 1000, value: 50000, quantity: 1 }],
})Tiga provider lulus contract test suite yang sama (runProviderContractTests() dari @ongkir-sdk/core/testing) — ganti provider tanpa ubah kode consumer.
import { createShippingRoutes } from '@ongkir-sdk/hono'
import { BiteshipProvider } from '@ongkir-sdk/biteship'
const app = new Hono()
app.route('/', createShippingRoutes({
providers: { biteship: new BiteshipProvider({ apiKey }) },
}))
// GET /rates?origin=12440&destination=12240&weight=1000
// GET /track/:id?courier=jne
// POST /shipments (CreateShipmentRequest — side-effect nyata, berpotensi menagih saldo)
// POST /webhooks/:provider- PRD.md — produk & scope
- ARCHITECTURE.md — keputusan arsitektur (final untuk v1)
- ROADMAP.md — progress fase
- CONTRIBUTING.md — panduan berkontribusi
- docs/deployment.md — deploy instance
api-wilayah-indonesia examples/node-basic— contoh SDK langsungexamples/hono-api— contoh REST API
v1 (Fase 0–3) selesai: core + 3 provider + Hono middleware, read-only. Fase 4 (v2) selesai: createShipment aktif — Biteship membuat order sungguhan (POST /v1/orders), Shipper membuat order sungguhan (POST /v3/order, rate_id di-resolve ulang dari pricing), Komerce melempar CREATE_SHIPMENT_NOT_SUPPORTED (batasan tier Shipping Cost), Hono punya route POST /shipments. Fase 5 selesai: paket @ongkir-sdk/cache-memory tersedia sebagai wrapper caching opsional. Lihat ROADMAP.md.
MIT