Copy page

Developer

SDK (TypeScript & Go)

OmniStream punya dua SDK resmi: TypeScript (@omnistreams/sdk) dan Go (omnistream-go). Keduanya menambahkan auth, retry, pagination, idempotency, typed errors, dan verifikasi webhook di atas REST API.

TypeScript

@omnistreams/sdk adalah client TypeScript resmi. Tipe di-generate dari OpenAPI spec; runtime menambahkan auth, retry, pagination, idempotency, typed errors, dan helper verifikasi webhook.

Instalasi

Code
npm install @omnistreams/sdk

Butuh Node.js ≥ 18 (memakai fetch global dan Web Crypto).

Penggunaan

Code
import { OmnistreamClient } from "@omnistreams/sdk";

const client = new OmnistreamClient({
  apiKey: process.env.OMNISTREAM_API_KEY!,
  baseUrl: "https://api.omnistream.example", // default http://localhost:3000
});

// Resource helper yang typed
const open = await client.conversations.list({ status: "open" });

await client.conversations.sendMessage(open[0].id, {
  type: "text",
  content: { body: "Halo! Ada yang bisa kami bantu?" },
});

Untuk membaca teks pesan, pakai content.body: semua channel engine menormalkan konten masuk ke { body } sebelum menyimpannya. Di jalur kirim kedua kunci diterima (text didahulukan, jatuh ke body), dan apa pun yang Anda kirim disimpan apa adanya — jadi mengirim body membuat baca dan tulis memakai kunci yang sama.

Pagination otomatis

Ada dua bentuk di API, dan cara paginasinya berbeda.

Array polos (/api/conversations, /api/wa-templates, …) — paginate() menelusurinya secara lazy:

Code
import type { Conversation } from "@omnistreams/sdk";

for await (const c of client.paginate<Conversation>("/api/conversations", { status: "open" })) {
  console.log(c.id);
}

Envelope pagination (/api/contacts, /api/messages/search) — endpoint ini mengembalikan { data | results, total, page, per_page, total_pages }, jadi paginate() tidak berlaku. Pakai helper resource-nya:

Code
const rows = await client.contacts.list({ search: "acme" });        // Contact[]
const page = await client.contacts.listPage({ search: "acme", page: 2 });
console.log(`${page.data.length} dari ${page.total}`);

Pencarian pesan

messages.search menerima objek params dan mengembalikan envelope berisi MessageSearchResult — hit membawa snippet ber-<mark> dan konteks kontak, dan sengaja tidak punya status, external_id, atau field error. Ukuran halaman memakai per_page (di-clamp 1..50 oleh server); tidak ada limit.

Code
const hits = await client.messages.search({
  q: "invoice",
  channel: "whatsapp",
  direction: "inbound",
  per_page: 50,
});
for (const hit of hits.results) {
  console.log(hit.contact_name, hit.snippet); // snippet berupa HTML — escape sebelum render
}

Idempotency

Code
import { generateIdempotencyKey } from "@omnistreams/sdk";

await client.conversations.sendMessage(
  id,
  { type: "text", content: { text: "hi" } },
  { idempotencyKey: generateIdempotencyKey() }, // aman di-retry
);

Typed errors

Code
import { OmnistreamApiError } from "@omnistreams/sdk";

try {
  await client.conversations.get("tidak-ada");
} catch (err) {
  if (err instanceof OmnistreamApiError && err.isNotFound) {
    // 404
  }
}

OmnistreamApiError mengekspos status, code, body, dan helper: isAuthError (401), isForbidden (403), isNotFound (404), isValidationError (422), isRateLimited (429), isServerError (5xx).

Retry & rate limit

Request yang gagal di-retry otomatis dengan exponential backoff + jitter; respons 429 menghormati Retry-After. GET di-retry pada error jaringan/5xx; method lain hanya pada 429 kecuali diberi Idempotency-Key. Atur dengan maxRetries dan timeoutMs di konstruktor.

Lihat juga: Verifikasi webhook.

Go

omnistream-go adalah client Go resmi. Cakupannya sama secara konsep (auth, retry, idempotency, pagination, verifikasi webhook) tapi tanpa dependency pihak ketiga; lima resource punya helper typed (Conversations, Contacts, Messages, Templates, APIKeys), endpoint lain dijangkau lewat generic escape hatch (Get/Post/Delete/Do). Belum ada tag rilis — pending v0.1.0.

Instalasi

Code
go get github.com/Cepat-Kilat-Teknologi/omnistream-go

Butuh Go 1.23 atau lebih baru. Tanpa dependency pihak ketiga.

Penggunaan

Code
import (
    "context"
    "log"
    "os"

    omnistream "github.com/Cepat-Kilat-Teknologi/omnistream-go"
)

client, err := omnistream.NewClient(
    os.Getenv("OMNISTREAM_API_KEY"),
    omnistream.WithBaseURL("https://api.omnistream.example"), // default http://localhost:3000
)
if err != nil {
    log.Fatal(err)
}

ctx := context.Background()
open, err := client.Conversations.List(ctx, &omnistream.ConversationListParams{
    Status: omnistream.ConversationOpen,
})

Verifikasi webhook

Code
import "github.com/Cepat-Kilat-Teknologi/omnistream-go/webhook"

// rawBody harus body mentah persis seperti diterima — verifikasi SEBELUM json.Unmarshal.
ok := webhook.Verify(rawBody, r.Header.Get(webhook.SignatureHeader), secret)

Selama rotasi secret, terima salah satu signature dengan webhook.VerifyWithRotation(rawBody, secret, currentHeader, previousHeader). Detail rotasi dan contoh tanpa SDK: Verifikasi webhook.

Source dan dokumentasi lengkap: https://github.com/Cepat-Kilat-Teknologi/omnistream-go