@omnistreams/sdk 0.1.0

package/README.md

@@ -0,0 +1,138 @@
+# @omnistreams/sdk
+
+Official **TypeScript SDK** for the [OmniStream](https://github.com/Cepat-Kilat-Teknologi/omnistream)
+omnichannel CRM API. Types are generated from the published OpenAPI spec; the
+runtime adds auth, retries, pagination, idempotency and webhook verification.
+
+## Install
+
+```bash
+npm install @omnistreams/sdk
+```
+
+Requires Node.js ≥ 18 (uses the global `fetch` and Web Crypto).
+
+## Quick start
+
+```ts
+import { OmnistreamClient } from "@omnistreams/sdk";
+
+const client = new OmnistreamClient({
+  apiKey: process.env.OMNISTREAM_API_KEY!,        // create in Developer → API Keys
+  baseUrl: "https://your-omnistream-host",         // default http://localhost:3000
+});
+
+// Typed resource helpers
+const open = await client.conversations.list({ status: "open" });
+const message = await client.conversations.sendMessage(open[0].id, {
+  type: "text",
+  content: { text: "Hi! How can I help?" },
+});
+```
+
+## Features
+
+### Auth
+
+Every request sends your key as `X-API-Key`. Lock the key down with an **IP
+allow list** (Developer → API Keys) for server-to-server use.
+
+### Retries & rate limits
+
+Failed requests are retried automatically with exponential backoff and full
+jitter. `429` responses honour the `Retry-After` header. Safe methods (`GET`)
+retry on network/5xx errors; unsafe methods only retry on `429` — unless you
+pass an idempotency key (see below).
+
+```ts
+const client = new OmnistreamClient({ apiKey, maxRetries: 3, timeoutMs: 15000 });
+```
+
+### Idempotency
+
+Pass an idempotency key so a `POST` can be safely retried on transient failures:
+
+```ts
+import { generateIdempotencyKey } from "@omnistreams/sdk";
+
+await client.conversations.sendMessage(
+  id,
+  { type: "text", content: { text: "hi" } },
+  { idempotencyKey: generateIdempotencyKey() },
+);
+```
+
+### Pagination
+
+`paginate()` returns an async iterator that walks page-numbered list endpoints
+lazily:
+
+```ts
+import type { Contact } from "@omnistreams/sdk";
+
+for await (const contact of client.paginate<Contact>("/api/contacts", { search: "acme" })) {
+  console.log(contact.name);
+}
+```
+
+### Typed errors
+
+```ts
+import { OmnistreamApiError, OmnistreamNetworkError } from "@omnistreams/sdk";
+
+try {
+  await client.conversations.get("does-not-exist");
+} catch (err) {
+  if (err instanceof OmnistreamApiError && err.isNotFound) {
+    // 404
+  } else if (err instanceof OmnistreamNetworkError && err.timedOut) {
+    // request timed out
+  }
+}
+```
+
+`OmnistreamApiError` exposes `status`, `code`, `body`, and helpers:
+`isAuthError` (401), `isForbidden` (403), `isNotFound` (404),
+`isValidationError` (422), `isRateLimited` (429), `isServerError` (5xx).
+
+### Webhook verification
+
+Verify inbound webhooks signed by the gateway (`X-Omnistream-Signature`,
+HMAC-SHA256 hex). Works in Node, browsers and edge runtimes.
+
+```ts
+import { verifyWebhookSignature, verifyWebhookSignatureWithRotation } from "@omnistreams/sdk";
+
+// rawBody must be the exact bytes received — verify BEFORE JSON.parse.
+const ok = await verifyWebhookSignature(rawBody, req.headers["x-omnistream-signature"], secret);
+
+// During a secret rotation, accept the current OR previous signature:
+const okRotating = await verifyWebhookSignatureWithRotation(rawBody, secret, {
+  current: req.headers["x-omnistream-signature"],
+  previous: req.headers["x-omnistream-signature-previous"],
+});
+```
+
+## Low-level access
+
+Every endpoint is reachable through the generic verbs, and the full generated
+OpenAPI types are exported:
+
+```ts
+import type { components } from "@omnistreams/sdk";
+type Campaign = components["schemas"]["Campaign"];
+
+const campaigns = await client.get<Campaign[]>("/api/campaigns", { page: 1 });
+await client.request("DELETE", `/api/api-keys/${keyId}`);
+```
+
+## Development
+
+```bash
+npm install
+npm run generate   # regenerate src/generated/openapi.ts from ../../docs/openapi.yaml
+npm run build
+npm test
+```
+
+Regenerate the types whenever `docs/openapi.yaml` changes.

package/dist/client.d.ts

@@ -0,0 +1,226 @@
+/**
+ * OmniStream API client.
+ *
+ * A small, typed wrapper around the OmniStream REST API with:
+ * - API-key auth (`X-API-Key`),
+ * - automatic retries with exponential backoff (honouring `Retry-After`),
+ * - optional idempotency keys for safe POST retries,
+ * - typed errors,
+ * - an async pagination helper.
+ *
+ * Response types come from the generated OpenAPI schema (`./generated/openapi`).
+ */
+import type { components } from "./generated/openapi.js";
+type Schemas = components["schemas"];
+export type Conversation = Schemas["ConversationWithContact"];
+export type Contact = Schemas["Contact"];
+export type Message = Schemas["Message"];
+export type MessageListResponse = Schemas["MessageListResponse"];
+export type WaTemplate = Schemas["WaTemplate"];
+export type ApiKey = Schemas["ApiKey"];
+export type SendMessageRequest = Schemas["SendMessageRequest"];
+export type CreateApiKeyRequest = Schemas["CreateApiKeyRequest"];
+export type ApiKeyCreateResponse = Schemas["ApiKeyCreateResponse"];
+export type ConversationStatus = Schemas["ConversationStatus"];
+/** Query parameters; nullish values are omitted. */
+export type Query = Record<string, string | number | boolean | undefined | null>;
+/** Options accepted by the client constructor. */
+export interface OmnistreamClientOptions {
+    /** REST API key (`os_..._...`), sent as `X-API-Key`. */
+    apiKey: string;
+    /** API gateway base URL. Default `http://localhost:3000`. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default 30000. */
+    timeoutMs?: number;
+    /** Max automatic retries per request. Default 2. */
+    maxRetries?: number;
+    /** Injectable fetch implementation (defaults to the global). */
+    fetch?: typeof fetch;
+}
+/** Per-request options. */
+export interface RequestOptions {
+    query?: Query;
+    body?: unknown;
+    /**
+     * Idempotency key sent as `Idempotency-Key`. When set, POST requests become
+     * safe to retry on network/5xx failures.
+     */
+    idempotencyKey?: string;
+    /** Caller-supplied abort signal (combined with the client timeout). */
+    signal?: AbortSignal;
+    /** Override the client's `maxRetries` for this request. */
+    maxRetries?: number;
+}
+/** Serialize a query object, skipping nullish values. */
+export declare function buildQueryString(query?: Query): string;
+/** Generate a random idempotency key (RFC 4122 UUID). */
+export declare function generateIdempotencyKey(): string;
+export declare class OmnistreamClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    constructor(options: OmnistreamClientOptions);
+    readonly conversations: {
+        /** List conversations (filter by status / assigned agent, paginated). */
+        list: (params?: {
+            status?: ConversationStatus;
+            assigned_agent_id?: string;
+            page?: number;
+            per_page?: number;
+        }) => Promise<{
+            id: string;
+            contact_id: string;
+            assigned_agent_id?: string | null;
+            assigned_agent_name?: string | null;
+            status: components["schemas"]["ConversationStatus"];
+            last_message_at: string;
+            unread_count: number;
+            created_at: string;
+            updated_at: string;
+            contact_name?: string | null;
+            contact_phone?: string | null;
+            contact_channel: string;
+            assignees?: components["schemas"]["Assignee"][] | null;
+        }[]>;
+        /** Get a single conversation by id. */
+        get: (id: string) => Promise<{
+            id: string;
+            contact_id: string;
+            assigned_agent_id?: string | null;
+            assigned_agent_name?: string | null;
+            status: components["schemas"]["ConversationStatus"];
+            last_message_at: string;
+            unread_count: number;
+            created_at: string;
+            updated_at: string;
+            contact_name?: string | null;
+            contact_phone?: string | null;
+            contact_channel: string;
+            assignees?: components["schemas"]["Assignee"][] | null;
+        }>;
+        /** List messages in a conversation (cursor paginated, newest first). */
+        messages: (id: string, params?: {
+            cursor?: string;
+            limit?: number;
+        }) => Promise<{
+            messages: components["schemas"]["Message"][];
+            next_cursor?: string | null;
+            has_more: boolean;
+        }>;
+        /** Send an outbound message. */
+        sendMessage: (id: string, body: SendMessageRequest, options?: RequestOptions) => Promise<{
+            _id?: string;
+            conversation_id: string;
+            external_id?: string | null;
+            direction: components["schemas"]["MessageDirection"];
+            type: components["schemas"]["MessageType"];
+            content: unknown;
+            status: components["schemas"]["MessageStatus"];
+            sender_phone?: string | null;
+            error_message?: string | null;
+            error_code?: string | null;
+            error_source?: string | null;
+            error_details?: Record<string, never> | null;
+            created_at: string;
+        }>;
+    };
+    readonly contacts: {
+        /** List/search contacts. */
+        list: (params?: {
+            search?: string;
+            tag?: string;
+            page?: number;
+            per_page?: number;
+        }) => Promise<{
+            id: string;
+            phone_number?: string | null;
+            name?: string | null;
+            email?: string | null;
+            channel_source: string;
+            tags: string[];
+            created_at: string;
+            updated_at: string;
+        }[]>;
+    };
+    readonly messages: {
+        /** Full-text search across message content. */
+        search: (q: string, limit?: number) => Promise<{
+            _id?: string;
+            conversation_id: string;
+            external_id?: string | null;
+            direction: components["schemas"]["MessageDirection"];
+            type: components["schemas"]["MessageType"];
+            content: unknown;
+            status: components["schemas"]["MessageStatus"];
+            sender_phone?: string | null;
+            error_message?: string | null;
+            error_code?: string | null;
+            error_source?: string | null;
+            error_details?: Record<string, never> | null;
+            created_at: string;
+        }[]>;
+    };
+    readonly templates: {
+        /** List WhatsApp templates. */
+        list: (params?: {
+            status?: string;
+            category?: string;
+            waba_id?: string;
+        }) => Promise<{
+            id: string;
+            meta_template_id?: string | null;
+            waba_id: string;
+            name: string;
+            language: string;
+            category: "MARKETING" | "UTILITY" | "AUTHENTICATION";
+            status: "APPROVED" | "PENDING" | "REJECTED" | "PAUSED" | "DISABLED";
+            components: unknown;
+            header_media_url?: string | null;
+            created_at: string;
+            updated_at: string;
+        }[]>;
+    };
+    readonly apiKeys: {
+        /** List the caller's API keys. */
+        list: () => Promise<{
+            id: string;
+            agent_id: string;
+            name: string;
+            key_type: "rest" | "webhook_signing";
+            key_prefix: string;
+            scopes: unknown;
+            last_used_at?: string | null;
+            expires_at?: string | null;
+            is_active: boolean;
+            created_at: string;
+            revoked_at?: string | null;
+        }[]>;
+        /** Create an API key (returns the plaintext key once). */
+        create: (body: CreateApiKeyRequest) => Promise<{
+            key: components["schemas"]["ApiKey"];
+            plaintext_key: string;
+        }>;
+        /** Revoke an API key. */
+        revoke: (id: string) => Promise<void>;
+    };
+    get<T>(path: string, query?: Query): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * Iterate every item across a page-numbered list endpoint that returns a
+     * JSON array (e.g. `/api/conversations`, `/api/contacts`). Fetches lazily.
+     */
+    paginate<T>(path: string, params?: Query, options?: {
+        perPage?: number;
+    }): AsyncGenerator<T, void, unknown>;
+    /**
+     * Low-level request with auth, timeout and retry. Throws
+     * {@link OmnistreamApiError} on non-2xx and {@link OmnistreamNetworkError} on
+     * network/timeout failures.
+     */
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+    /** Build an abort signal combining the client timeout with a caller signal. */
+    private deadline;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,245 @@
+/**
+ * OmniStream API client.
+ *
+ * A small, typed wrapper around the OmniStream REST API with:
+ * - API-key auth (`X-API-Key`),
+ * - automatic retries with exponential backoff (honouring `Retry-After`),
+ * - optional idempotency keys for safe POST retries,
+ * - typed errors,
+ * - an async pagination helper.
+ *
+ * Response types come from the generated OpenAPI schema (`./generated/openapi`).
+ */
+import { OmnistreamApiError, OmnistreamNetworkError } from "./errors.js";
+const DEFAULT_BASE_URL = "http://localhost:3000";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+const RETRY_BASE_DELAY_MS = 200;
+const RETRY_MAX_DELAY_MS = 5_000;
+/** Serialize a query object, skipping nullish values. */
+export function buildQueryString(query) {
+    if (!query)
+        return "";
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value === undefined || value === null)
+            continue;
+        params.append(key, String(value));
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : "";
+}
+/** Generate a random idempotency key (RFC 4122 UUID). */
+export function generateIdempotencyKey() {
+    return crypto.randomUUID();
+}
+export class OmnistreamClient {
+    apiKey;
+    baseUrl;
+    timeoutMs;
+    maxRetries;
+    fetchImpl;
+    constructor(options) {
+        if (!options.apiKey)
+            throw new Error("OmnistreamClient: `apiKey` is required.");
+        this.apiKey = options.apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+        const f = options.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new Error("OmnistreamClient: no fetch implementation (Node >= 18 required).");
+        this.fetchImpl = f.bind(globalThis);
+    }
+    // ── Resource helpers ──────────────────────────────────────────────────
+    conversations = {
+        /** List conversations (filter by status / assigned agent, paginated). */
+        list: (params) => this.get("/api/conversations", params),
+        /** Get a single conversation by id. */
+        get: (id) => this.get(`/api/conversations/${enc(id)}`),
+        /** List messages in a conversation (cursor paginated, newest first). */
+        messages: (id, params) => this.get(`/api/conversations/${enc(id)}/messages`, params),
+        /** Send an outbound message. */
+        sendMessage: (id, body, options) => this.post(`/api/conversations/${enc(id)}/messages`, body, options),
+    };
+    contacts = {
+        /** List/search contacts. */
+        list: (params) => this.get("/api/contacts", params),
+    };
+    messages = {
+        /** Full-text search across message content. */
+        search: (q, limit) => this.get("/api/messages/search", { q, limit }),
+    };
+    templates = {
+        /** List WhatsApp templates. */
+        list: (params) => this.get("/api/wa-templates", params),
+    };
+    apiKeys = {
+        /** List the caller's API keys. */
+        list: () => this.get("/api/api-keys"),
+        /** Create an API key (returns the plaintext key once). */
+        create: (body) => this.post("/api/api-keys", body),
+        /** Revoke an API key. */
+        revoke: (id) => this.request("DELETE", `/api/api-keys/${enc(id)}`),
+    };
+    // ── Generic verbs ─────────────────────────────────────────────────────
+    get(path, query) {
+        return this.request("GET", path, { query });
+    }
+    post(path, body, options) {
+        return this.request("POST", path, { ...options, body });
+    }
+    /**
+     * Iterate every item across a page-numbered list endpoint that returns a
+     * JSON array (e.g. `/api/conversations`, `/api/contacts`). Fetches lazily.
+     */
+    async *paginate(path, params = {}, options = {}) {
+        const perPage = options.perPage ?? 50;
+        let page = 1;
+        for (;;) {
+            const items = await this.get(path, { ...params, page, per_page: perPage });
+            for (const item of items)
+                yield item;
+            if (!Array.isArray(items) || items.length < perPage)
+                break;
+            page += 1;
+        }
+    }
+    /**
+     * Low-level request with auth, timeout and retry. Throws
+     * {@link OmnistreamApiError} on non-2xx and {@link OmnistreamNetworkError} on
+     * network/timeout failures.
+     */
+    async request(method, path, options = {}) {
+        const url = `${this.baseUrl}${path}${buildQueryString(options.query)}`;
+        const hasBody = options.body !== undefined;
+        const maxRetries = options.maxRetries ?? this.maxRetries;
+        const headers = { "X-API-Key": this.apiKey, Accept: "application/json" };
+        if (hasBody)
+            headers["Content-Type"] = "application/json";
+        if (options.idempotencyKey)
+            headers["Idempotency-Key"] = options.idempotencyKey;
+        const body = hasBody ? JSON.stringify(options.body) : undefined;
+        let attempt = 0;
+        for (;;) {
+            const { signal, cancel } = this.deadline(options.signal);
+            let res;
+            try {
+                res = await this.fetchImpl(url, { method, headers, body, signal });
+            }
+            catch (err) {
+                cancel();
+                const timedOut = isAbortError(err) && !options.signal?.aborted;
+                // External abort → propagate; timeout/network → maybe retry.
+                if (isAbortError(err) && options.signal?.aborted) {
+                    throw new OmnistreamNetworkError("Request aborted by caller", false, err);
+                }
+                if (attempt < maxRetries && retryableOnNetwork(method, options.idempotencyKey)) {
+                    await sleep(backoffDelay(attempt));
+                    attempt += 1;
+                    continue;
+                }
+                throw new OmnistreamNetworkError(timedOut ? `Request timed out after ${this.timeoutMs}ms` : `Network error: ${errMessage(err)}`, timedOut, err);
+            }
+            cancel();
+            if (res.ok) {
+                return (await parseJson(res));
+            }
+            // Retry on 429 (all methods) and 5xx (idempotent/keyed methods).
+            const retryable = res.status === 429 || (res.status >= 500 && retryableOnNetwork(method, options.idempotencyKey));
+            if (attempt < maxRetries && retryable) {
+                await sleep(retryAfterMs(res) ?? backoffDelay(attempt));
+                attempt += 1;
+                continue;
+            }
+            const parsed = await parseJson(res);
+            throw new OmnistreamApiError(res.status, extractErrorMessage(parsed, res.status), extractErrorCode(parsed), parsed);
+        }
+    }
+    /** Build an abort signal combining the client timeout with a caller signal. */
+    deadline(external) {
+        const controller = new AbortController();
+        const onExternalAbort = () => controller.abort(external?.reason);
+        if (external) {
+            if (external.aborted)
+                controller.abort(external.reason);
+            else
+                external.addEventListener("abort", onExternalAbort, { once: true });
+        }
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        const cancel = () => {
+            clearTimeout(timer);
+            external?.removeEventListener("abort", onExternalAbort);
+        };
+        return { signal: controller.signal, cancel };
+    }
+}
+/** URL-encode a path segment. */
+function enc(segment) {
+    return encodeURIComponent(segment);
+}
+function isAbortError(err) {
+    return err instanceof Error && err.name === "AbortError";
+}
+function errMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** GET is always safe to retry; POST/PUT/PATCH/DELETE only with an idempotency key. */
+function retryableOnNetwork(method, idempotencyKey) {
+    return method.toUpperCase() === "GET" || idempotencyKey !== undefined;
+}
+/** Exponential backoff with full jitter. */
+function backoffDelay(attempt) {
+    const capped = Math.min(RETRY_MAX_DELAY_MS, RETRY_BASE_DELAY_MS * 2 ** attempt);
+    return Math.floor(Math.random() * capped);
+}
+/** Parse a `Retry-After` header (seconds) into milliseconds, if present. */
+function retryAfterMs(res) {
+    const header = res.headers.get("retry-after");
+    if (!header)
+        return undefined;
+    const seconds = Number(header);
+    return Number.isFinite(seconds) && seconds >= 0 ? seconds * 1000 : undefined;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function parseJson(res) {
+    const text = await res.text();
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function extractErrorMessage(body, status) {
+    if (typeof body === "string" && body.trim())
+        return body.trim();
+    if (body && typeof body === "object") {
+        const err = body.error;
+        if (typeof err === "string")
+            return err;
+        if (err && typeof err === "object" && typeof err.message === "string") {
+            return err.message;
+        }
+        const msg = body.message;
+        if (typeof msg === "string")
+            return msg;
+    }
+    return `HTTP ${status}`;
+}
+function extractErrorCode(body) {
+    if (body && typeof body === "object") {
+        const err = body.error;
+        if (err && typeof err === "object") {
+            const code = err.code;
+            if (typeof code === "string" || typeof code === "number")
+                return code;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+/** Error types thrown by the OmniStream SDK. */
+/** Base class for every error the SDK throws. */
+export declare class OmnistreamError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown for non-2xx API responses. Carries the HTTP status, the API error
+ * `code` when present, and the raw parsed body. Convenience getters classify
+ * common cases.
+ */
+export declare class OmnistreamApiError extends OmnistreamError {
+    readonly status: number;
+    readonly code?: string | number | undefined;
+    readonly body?: unknown | undefined;
+    constructor(status: number, message: string, code?: string | number | undefined, body?: unknown | undefined);
+    /** 401 — missing/invalid credentials (or a source IP outside a key's allow list). */
+    get isAuthError(): boolean;
+    /** 403 — authenticated but not permitted. */
+    get isForbidden(): boolean;
+    /** 404 — resource not found. */
+    get isNotFound(): boolean;
+    /** 422 — request validation failed. */
+    get isValidationError(): boolean;
+    /** 429 — rate limited. */
+    get isRateLimited(): boolean;
+    /** 5xx — server-side error. */
+    get isServerError(): boolean;
+}
+/** Thrown when a request never got a response (network failure or timeout). */
+export declare class OmnistreamNetworkError extends OmnistreamError {
+    /** Whether the failure was a client-side timeout. */
+    readonly timedOut: boolean;
+    readonly cause?: unknown | undefined;
+    constructor(message: string, 
+    /** Whether the failure was a client-side timeout. */
+    timedOut?: boolean, cause?: unknown | undefined);
+}