@yaotoshi/cahub-sdk

SDK TypeScript resmi untuk muka depan API cahub. Nol dependensi runtime (fetch global), dual ESM/CommonJS, tipe di-generate dari openapi.json cahub — salah ketik path ketahuan saat kompilasi, dan parameter path wajib tidak bisa dilupakan.

• createCahubClient({ baseUrl, apiKey }) — konfigurasi eksplisit, mudah dites.
• fromEnv() — baca CAHUB_BASE_URL + CAHUB_API_KEY dari lingkungan proses.
• Satu kelas error: CahubSdkError — bedakan lewat .code, lapor ke tim cahub dengan .requestId.

Pasang

npm install @yaotoshi/cahub-sdk

Mulai cepat

import { fromEnv } from '@yaotoshi/cahub-sdk'

// (a) dari lingkungan — CAHUB_BASE_URL + CAHUB_API_KEY
const c = fromEnv()

// (b) eksplisit — mudah dites, tanpa sihir env
import { createCahubClient } from '@yaotoshi/cahub-sdk'
const c2 = createCahubClient({
  baseUrl: 'https://cahub.example.com',
  apiKey: process.env.CAHUB_API_KEY!,
})

const nota = await c.GET('/v1/pembelian/importir/{id}', { params: { path: { id: '291' } } })
console.log(nota.nota.amount_due_rmb) // string — uang tidak pernah number

CommonJS juga bisa:

const { fromEnv } = require('@yaotoshi/cahub-sdk')

Variabel lingkungan (untuk fromEnv)

| Variabel | Isi | | --- | --- | | CAHUB_BASE_URL | origin API cahub, tanpa trailing slash | | CAHUB_API_KEY | API key — ch_live_… hanya untuk server produksi, ch_test_… untuk server lain |

Error

try {
  await c.GET('/v1/pembelian/importir/{id}', { params: { path: { id: '291' } } })
} catch (e) {
  if (e instanceof CahubSdkError) {
    if (e.code === 'SCOPE_DENIED') console.error(e.message) // menyebut scope yang dibutuhkan
    if (e.code === 'AUTH_ERROR')   console.error(e.serverCode, e.requestId)
  }
}

| code | arti | | --- | --- | | MISSING_CONFIG | baseUrl/apiKey/env kosong atau bentuk salah (sebelum network) | | INVALID_KEY | bentuk key tidak sah — bukan ch_live_/ch_test_ (sebelum network) | | INVALID_REQUEST | parameter path wajib tidak diisi (sebelum network) | | TIMEOUT | permintaan melebihi timeoutMs | | NETWORK_ERROR | server tidak terjangkau | | AUTH_ERROR | 401 — key tidak dikenal/dicabut/kadaluwarsa/dll; serverCode membawa kode problem asli | | SCOPE_DENIED | 403 — scope key tidak mencakup endpoint ini | | VALIDATION_ERROR | 400 — parameter tidak sesuai skema | | NOT_FOUND | 404 — data tidak ditemukan | | SOURCE_READ_ONLY | 409 — koneksi sumber tercatat hanya-baca, tulis ditolak | | RATE_LIMITED | 429 — kuota app habis | | SERVER_ERROR | 5xx — kesalahan internal / sumber tak tersedia | | API_ERROR | respons di luar daftar di atas |

Aturan yang menggigit kalau diabaikan

Uang dan semua pengenal dikirim sebagai string. Cacah dan kuantitas tetap number. Tipe SDK mewarisi aturan ini dari skema API — amount_due_rmb bertipe string | null, bukan number. Jangan Number() nilai uang; bandingkan sebagai string atau pakai aritmetika desimal (mis. decimal.js).

Key test tidak bisa dipakai ke server produksi, dan sebaliknya. Prefix key harus cocok dengan sifat server yang dituju (server menolak 401 KEY_ENVIRONMENT_MISMATCH).

Tipe ikut registry — tidak pernah basi diam-diam

src/openapi.ts di-generate dari registry operation lewat openapi-typescript (path /admin/* sengaja dibuang — itu permukaan dashboard, bukan API key). Tes sinkron di suite menegakkannya: operation berubah tanpa npm run generate:sdk = CI merah.

npm run generate:sdk   # dari root monorepo cahub

Mengembangkan

npm run build --workspace @yaotoshi/cahub-sdk   # tsup (ESM+CJS) + tsc (deklarasi)
npx vitest run packages/sdk/test                # unit + integrasi + sinkron

Menerbitkan

Sepenuhnya lewat workflow — tidak ada tag, tidak ada login manual:

1. (Sekali saja) tambah secret NPM_TOKEN di pengaturan repo — token npm tipe Automation dengan izin publish untuk @yaotoshi/cahub-sdk.
2. Naikkan version di packages/sdk/package.json dalam PR.
3. Merge ke master → workflow .github/workflows/publish-sdk.yml membandingkan versi lokal dengan versi yang sudah terbit di npm: berbeda = tes SDK + npm publish otomatis; sama = dilewati.

Bisa juga dipicu manual dari tab Actions → Run workflow, atau lewat tag sdk-v*.