@kirimdev/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kirim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @kirimdev/sdk
+
+Official TypeScript SDK for the [Kirim](https://kirim.chat) Public API.
+
+## Install
+
+```bash
+npm install @kirimdev/sdk
+# or
+bun add @kirimdev/sdk
+```
+
+## Quickstart
+
+```ts
+import { Kirim } from '@kirimdev/sdk'
+
+const kirim = new Kirim({ apiKey: process.env.KIRIM_API_KEY! })
+
+// Send a message
+const msg = await kirim.messages.send({
+  to: '628123456789',
+  type: 'text',
+  text: { body: 'Halo dari SDK!' },
+})
+
+// Paginate
+for await (const m of kirim.messages.list({ limit: 50 })) {
+  console.log(m.id, m.status)
+}
+
+// Webhook verification
+import { verifyWebhookSignature } from '@kirimdev/sdk/webhooks'
+
+const ok = verifyWebhookSignature(rawBody, req.headers['x-kirim-signature'], secret)
+```
+
+## Features
+
+- Full coverage of the Kirim `/v1` API (~35 endpoints)
+- Type-safe — generated from the live OpenAPI 3.1 spec
+- Automatic retries with exponential backoff (429, 5xx, network errors)
+- Automatic `Idempotency-Key` injection for POST requests
+- Async iterator pagination (`for await ... of kirim.messages.list(...)`)
+- Typed error class hierarchy keyed off stable API error codes
+- Webhook HMAC-SHA256 verifier
+- Zero Node-specific dependencies — works in Node 18+, Bun, Deno
+
+## Configuration
+
+```ts
+new Kirim({
+  apiKey: 'kdv_live_...',                    // required
+  baseUrl: 'https://api-kckit.kirim.chat/v1', // optional
+  timeout: 30_000,                            // ms, default 30s
+  maxRetries: 2,                              // default 2
+  fetch: globalThis.fetch,                    // injectable for testing
+})
+```
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Top-level `Kirim` client. Owns one `HttpClient` and exposes resource
+ * namespaces. Construction is cheap; one instance per API key per process.
+ */
+import { type RequestOptions } from './http.js';
+import { ContactsResource } from './resources/contacts.js';
+import { ConversationsResource } from './resources/conversations.js';
+import { LabelsResource } from './resources/labels.js';
+import { MessagesResource } from './resources/messages.js';
+import { TemplatesResource } from './resources/templates.js';
+import { WebhookDeliveriesResource } from './resources/webhook-deliveries.js';
+import { WebhookSubscriptionsResource } from './resources/webhook-subscriptions.js';
+import type { MeContext } from './types.js';
+export declare const SDK_VERSION = "1.0.0";
+export interface KirimOptions {
+    /** Bearer API key. Format: `kdv_live_<...>`. Required. */
+    apiKey: string;
+    /** Override the API base URL (incl. `/v1`). Default: production. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. Default: 30_000. */
+    timeout?: number;
+    /** Retries on 429/5xx/network. Default: 2. */
+    maxRetries?: number;
+    /** Injectable fetch (for testing or custom transports). */
+    fetch?: typeof fetch;
+    /** Extra suffix appended to the SDK User-Agent (e.g. your app name). */
+    userAgentSuffix?: string;
+}
+export declare class Kirim {
+    readonly messages: MessagesResource;
+    readonly templates: TemplatesResource;
+    readonly conversations: ConversationsResource;
+    readonly contacts: ContactsResource;
+    readonly labels: LabelsResource;
+    readonly webhookSubscriptions: WebhookSubscriptionsResource;
+    readonly webhookDeliveries: WebhookDeliveriesResource;
+    private readonly http;
+    constructor(options: KirimOptions);
+    /** GET /me — introspect the calling API key. */
+    me(options?: RequestOptions): Promise<MeContext>;
+    /**
+     * Escape hatch for endpoints not yet wrapped by the SDK. Returns the raw
+     * decoded JSON body (envelope NOT unwrapped). Useful for previewing new
+     * API endpoints before the next SDK release.
+     */
+    request<T = unknown>(method: 'GET' | 'POST' | 'PATCH' | 'DELETE', path: string, init?: {
+        body?: unknown;
+        query?: Record<string, string | number | boolean | undefined | null>;
+        options?: RequestOptions;
+    }): Promise<T>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAiC,KAAK,cAAc,EAAE,MAAM,WAAW,CAAA;AAC9E,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAA;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAA;AAC7E,OAAO,EAAE,4BAA4B,EAAE,MAAM,sCAAsC,CAAA;AACnF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE3C,eAAO,MAAM,WAAW,UAAU,CAAA;AAKlC,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAA;IACd,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2DAA2D;IAC3D,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,wEAAwE;IACxE,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED,qBAAa,KAAK;IAChB,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAA;IACrC,QAAQ,CAAC,aAAa,EAAE,qBAAqB,CAAA;IAC7C,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAA;IACnC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,QAAQ,CAAC,oBAAoB,EAAE,4BAA4B,CAAA;IAC3D,QAAQ,CAAC,iBAAiB,EAAE,yBAAyB,CAAA;IAErD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAY;gBAErB,OAAO,EAAE,YAAY;IAiCjC,gDAAgD;IAChD,EAAE,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,CAAC;IAQhD;;;;OAIG;IACH,OAAO,CAAC,CAAC,GAAG,OAAO,EACjB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,EAC3C,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QACL,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAA;QACpE,OAAO,CAAC,EAAE,cAAc,CAAA;KACzB,GACA,OAAO,CAAC,CAAC,CAAC;CASd"}

package/dist/client.js

@@ -0,0 +1,75 @@
+/**
+ * Top-level `Kirim` client. Owns one `HttpClient` and exposes resource
+ * namespaces. Construction is cheap; one instance per API key per process.
+ */
+import { HttpClient } from './http.js';
+import { ContactsResource } from './resources/contacts.js';
+import { ConversationsResource } from './resources/conversations.js';
+import { LabelsResource } from './resources/labels.js';
+import { MessagesResource } from './resources/messages.js';
+import { TemplatesResource } from './resources/templates.js';
+import { WebhookDeliveriesResource } from './resources/webhook-deliveries.js';
+import { WebhookSubscriptionsResource } from './resources/webhook-subscriptions.js';
+export const SDK_VERSION = '1.0.0';
+const DEFAULT_BASE_URL = 'https://api-kckit.kirim.chat/v1';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_RETRIES = 2;
+export class Kirim {
+    messages;
+    templates;
+    conversations;
+    contacts;
+    labels;
+    webhookSubscriptions;
+    webhookDeliveries;
+    http;
+    constructor(options) {
+        if (!options.apiKey) {
+            throw new TypeError('Kirim: `apiKey` is required.');
+        }
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== 'function') {
+            throw new TypeError('Kirim: global `fetch` is not available. Pass `fetch` in options or upgrade to Node 18+.');
+        }
+        const ua = `kirimdev-sdk-js/${SDK_VERSION}${options.userAgentSuffix ? ` ${options.userAgentSuffix}` : ''}`;
+        const config = {
+            apiKey: options.apiKey,
+            baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+            timeout: options.timeout ?? DEFAULT_TIMEOUT_MS,
+            maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+            fetch: fetchImpl,
+            userAgent: ua,
+        };
+        this.http = new HttpClient(config);
+        this.messages = new MessagesResource(this.http);
+        this.templates = new TemplatesResource(this.http);
+        this.conversations = new ConversationsResource(this.http);
+        this.contacts = new ContactsResource(this.http);
+        this.labels = new LabelsResource(this.http);
+        this.webhookSubscriptions = new WebhookSubscriptionsResource(this.http);
+        this.webhookDeliveries = new WebhookDeliveriesResource(this.http);
+    }
+    /** GET /me — introspect the calling API key. */
+    me(options) {
+        return this.http.requestData({
+            method: 'GET',
+            path: '/me',
+            ...(options ? { options } : {}),
+        });
+    }
+    /**
+     * Escape hatch for endpoints not yet wrapped by the SDK. Returns the raw
+     * decoded JSON body (envelope NOT unwrapped). Useful for previewing new
+     * API endpoints before the next SDK release.
+     */
+    request(method, path, init) {
+        return this.http.requestRaw({
+            method,
+            path,
+            ...(init?.body !== undefined ? { body: init.body } : {}),
+            ...(init?.query ? { query: init.query } : {}),
+            ...(init?.options ? { options: init.options } : {}),
+        });
+    }
+}
+//# 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,70 @@
+/**
+ * Error class hierarchy for `@kirimdev/sdk`.
+ *
+ * Every HTTP error from the Kirim API is mapped to a subclass of
+ * `KirimError`. Network/timeout failures throw `ConnectionError`. The
+ * subclass tree mirrors `error.type` from the API envelope so callers can
+ * use `instanceof` for coarse categorization and inspect `code` for the
+ * specific stable identifier.
+ *
+ * Source of truth for codes: `apps/api/src/lib/api-error.ts` (ERROR_CATALOG).
+ */
+export type KirimErrorType = 'invalid_request_error' | 'authentication_error' | 'permission_error' | 'not_found' | 'conflict' | 'rate_limit_error' | 'api_error' | 'connection_error';
+export interface KirimErrorPayload {
+    type: KirimErrorType;
+    code: string;
+    message: string;
+    status: number;
+    requestId: string | null;
+    param?: string | undefined;
+    /** Raw decoded error body, for debugging. */
+    raw?: unknown;
+}
+/** Base class. All errors thrown by the SDK extend this. */
+export declare class KirimError extends Error {
+    readonly type: KirimErrorType;
+    readonly code: string;
+    readonly status: number;
+    readonly requestId: string | null;
+    readonly param: string | undefined;
+    readonly raw: unknown;
+    constructor(payload: KirimErrorPayload);
+}
+export declare class InvalidRequestError extends KirimError {
+    constructor(payload: KirimErrorPayload);
+}
+export declare class AuthenticationError extends KirimError {
+    constructor(payload: KirimErrorPayload);
+}
+export declare class PermissionError extends KirimError {
+    constructor(payload: KirimErrorPayload);
+}
+export declare class NotFoundError extends KirimError {
+    constructor(payload: KirimErrorPayload);
+}
+export declare class ConflictError extends KirimError {
+    constructor(payload: KirimErrorPayload);
+}
+export declare class RateLimitError extends KirimError {
+    /** Seconds the server asked us to wait, if `Retry-After` was a delta. */
+    readonly retryAfter: number | null;
+    constructor(payload: KirimErrorPayload & {
+        retryAfter: number | null;
+    });
+}
+export declare class ApiServerError extends KirimError {
+    constructor(payload: KirimErrorPayload);
+}
+/** No response received (DNS, TCP, abort, timeout, CORS). */
+export declare class ConnectionError extends KirimError {
+    readonly cause: unknown;
+    constructor(message: string, cause: unknown);
+}
+/**
+ * Build a typed error from an HTTP response body + status. The body is
+ * expected to follow `ErrorResponse` (see `apps/api/src/lib/api-response.ts`)
+ * but we tolerate non-conforming bodies (e.g. a stray HTML 502 from a CDN)
+ * by falling back to a generic message.
+ */
+export declare function fromHttpResponse(status: number, body: unknown, requestId: string | null, retryAfterSeconds: number | null): KirimError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,MAAM,cAAc,GACtB,uBAAuB,GACvB,sBAAsB,GACtB,kBAAkB,GAClB,WAAW,GACX,UAAU,GACV,kBAAkB,GAClB,WAAW,GACX,kBAAkB,CAAA;AAEtB,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,cAAc,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC1B,6CAA6C;IAC7C,GAAG,CAAC,EAAE,OAAO,CAAA;CACd;AAED,4DAA4D;AAC5D,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;gBAET,OAAO,EAAE,iBAAiB;CAUvC;AAED,qBAAa,mBAAoB,SAAQ,UAAU;gBACrC,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,mBAAoB,SAAQ,UAAU;gBACrC,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,eAAgB,SAAQ,UAAU;gBACjC,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,aAAc,SAAQ,UAAU;gBAC/B,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,aAAc,SAAQ,UAAU;gBAC/B,OAAO,EAAE,iBAAiB;CAIvC;AAED,qBAAa,cAAe,SAAQ,UAAU;IAC5C,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;gBACtB,OAAO,EAAE,iBAAiB,GAAG;QAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;CAKvE;AAED,qBAAa,cAAe,SAAQ,UAAU;gBAChC,OAAO,EAAE,iBAAiB;CAIvC;AAED,6DAA6D;AAC7D,qBAAa,eAAgB,SAAQ,UAAU;IAC7C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;gBACX,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO;CAW5C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,SAAS,EAAE,MAAM,GAAG,IAAI,EACxB,iBAAiB,EAAE,MAAM,GAAG,IAAI,GAC/B,UAAU,CAiCZ"}

package/dist/errors.js

@@ -0,0 +1,167 @@
+/**
+ * Error class hierarchy for `@kirimdev/sdk`.
+ *
+ * Every HTTP error from the Kirim API is mapped to a subclass of
+ * `KirimError`. Network/timeout failures throw `ConnectionError`. The
+ * subclass tree mirrors `error.type` from the API envelope so callers can
+ * use `instanceof` for coarse categorization and inspect `code` for the
+ * specific stable identifier.
+ *
+ * Source of truth for codes: `apps/api/src/lib/api-error.ts` (ERROR_CATALOG).
+ */
+/** Base class. All errors thrown by the SDK extend this. */
+export class KirimError extends Error {
+    type;
+    code;
+    status;
+    requestId;
+    param;
+    raw;
+    constructor(payload) {
+        super(payload.message);
+        this.name = 'KirimError';
+        this.type = payload.type;
+        this.code = payload.code;
+        this.status = payload.status;
+        this.requestId = payload.requestId;
+        this.param = payload.param;
+        this.raw = payload.raw;
+    }
+}
+export class InvalidRequestError extends KirimError {
+    constructor(payload) {
+        super(payload);
+        this.name = 'InvalidRequestError';
+    }
+}
+export class AuthenticationError extends KirimError {
+    constructor(payload) {
+        super(payload);
+        this.name = 'AuthenticationError';
+    }
+}
+export class PermissionError extends KirimError {
+    constructor(payload) {
+        super(payload);
+        this.name = 'PermissionError';
+    }
+}
+export class NotFoundError extends KirimError {
+    constructor(payload) {
+        super(payload);
+        this.name = 'NotFoundError';
+    }
+}
+export class ConflictError extends KirimError {
+    constructor(payload) {
+        super(payload);
+        this.name = 'ConflictError';
+    }
+}
+export class RateLimitError extends KirimError {
+    /** Seconds the server asked us to wait, if `Retry-After` was a delta. */
+    retryAfter;
+    constructor(payload) {
+        super(payload);
+        this.name = 'RateLimitError';
+        this.retryAfter = payload.retryAfter;
+    }
+}
+export class ApiServerError extends KirimError {
+    constructor(payload) {
+        super(payload);
+        this.name = 'ApiServerError';
+    }
+}
+/** No response received (DNS, TCP, abort, timeout, CORS). */
+export class ConnectionError extends KirimError {
+    cause;
+    constructor(message, cause) {
+        super({
+            type: 'connection_error',
+            code: 'connection_error',
+            message,
+            status: 0,
+            requestId: null,
+        });
+        this.name = 'ConnectionError';
+        this.cause = cause;
+    }
+}
+/**
+ * Build a typed error from an HTTP response body + status. The body is
+ * expected to follow `ErrorResponse` (see `apps/api/src/lib/api-response.ts`)
+ * but we tolerate non-conforming bodies (e.g. a stray HTML 502 from a CDN)
+ * by falling back to a generic message.
+ */
+export function fromHttpResponse(status, body, requestId, retryAfterSeconds) {
+    const env = isErrorEnvelope(body) ? body.error : null;
+    const code = env?.code ?? defaultCodeForStatus(status);
+    const type = env?.type ?? defaultTypeForStatus(status);
+    const message = env?.message ?? `Kirim API responded with status ${status}.`;
+    const param = env?.param;
+    const payload = {
+        type,
+        code,
+        message,
+        status,
+        requestId: env?.request_id ?? requestId,
+        param,
+        raw: body,
+    };
+    switch (type) {
+        case 'invalid_request_error':
+            return new InvalidRequestError(payload);
+        case 'authentication_error':
+            return new AuthenticationError(payload);
+        case 'permission_error':
+            return new PermissionError(payload);
+        case 'not_found':
+            return new NotFoundError(payload);
+        case 'conflict':
+            return new ConflictError(payload);
+        case 'rate_limit_error':
+            return new RateLimitError({ ...payload, retryAfter: retryAfterSeconds });
+        case 'api_error':
+        default:
+            return new ApiServerError(payload);
+    }
+}
+function isErrorEnvelope(body) {
+    return (typeof body === 'object' &&
+        body !== null &&
+        'error' in body &&
+        typeof body.error === 'object' &&
+        body.error !== null);
+}
+function defaultTypeForStatus(status) {
+    if (status === 401)
+        return 'authentication_error';
+    if (status === 403)
+        return 'permission_error';
+    if (status === 404)
+        return 'not_found';
+    if (status === 409)
+        return 'conflict';
+    if (status === 429)
+        return 'rate_limit_error';
+    if (status >= 500)
+        return 'api_error';
+    return 'invalid_request_error';
+}
+function defaultCodeForStatus(status) {
+    if (status === 401)
+        return 'invalid_api_key';
+    if (status === 403)
+        return 'feature_not_available';
+    if (status === 404)
+        return 'resource_not_found';
+    if (status === 409)
+        return 'conflict';
+    if (status === 429)
+        return 'rate_limit_exceeded';
+    if (status >= 500)
+        return 'internal_error';
+    return 'invalid_field_value';
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/http.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Internal HTTP client. All resource methods funnel through here so retry,
+ * idempotency, timeout, and error mapping are implemented once.
+ *
+ * Design notes:
+ *   - Uses Web Standard `fetch` only; no Node-only APIs. Works in Node 18+,
+ *     Bun, Deno, and Web/edge runtimes.
+ *   - Auto-injects `Idempotency-Key` on POST so retries are safe by default
+ *     (matches `apps/api/src/middleware/idempotency.ts`). User-supplied
+ *     keys override.
+ *   - Retries on 429 + 502/503/504 + network errors with exponential
+ *     backoff + jitter. Honors `Retry-After`.
+ *   - Throws subclasses of `KirimError` for any non-2xx response.
+ */
+export type HttpMethod = 'GET' | 'POST' | 'PATCH' | 'DELETE';
+export interface ClientConfig {
+    apiKey: string;
+    baseUrl: string;
+    timeout: number;
+    maxRetries: number;
+    fetch: typeof fetch;
+    userAgent: string;
+}
+export interface RequestOptions {
+    /** Per-call override; otherwise auto-generated for POST. */
+    idempotencyKey?: string;
+    /** Per-call timeout override (ms). */
+    timeout?: number;
+    /** Per-call retry override. */
+    maxRetries?: number;
+    /** Caller-supplied AbortSignal; merged with the timeout signal. */
+    signal?: AbortSignal;
+    /** Extra headers — last-write-wins over SDK defaults except Authorization. */
+    headers?: Record<string, string>;
+}
+export interface RequestArgs {
+    method: HttpMethod;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined | null>;
+    body?: unknown;
+    options?: RequestOptions;
+}
+/**
+ * Public envelope shapes — duplicated here (instead of imported from
+ * `generated/`) because the generated file inlines them per-endpoint as
+ * anonymous shapes, and we need a single name we can reference.
+ */
+export interface SingleEnvelope<T> {
+    data: T;
+    request_id: string;
+}
+export interface ListEnvelope<T> {
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
+    request_id: string;
+}
+export declare class HttpClient {
+    private readonly config;
+    constructor(config: ClientConfig);
+    /**
+     * Execute a request, parse the envelope, and unwrap `data`. Use this for
+     * single-resource endpoints. For paginated endpoints use `requestRaw`.
+     */
+    requestData<T>(args: RequestArgs): Promise<T>;
+    /** Return the raw decoded body (envelope intact). For pagination. */
+    requestRaw<T = unknown>(args: RequestArgs): Promise<T>;
+    private request;
+    private attemptOnce;
+}
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAQH,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE5D,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,OAAO,KAAK,CAAA;IACnB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,sCAAsC;IACtC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,+BAA+B;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,UAAU,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,IAAI,CAAC,CAAA;IACpE,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,IAAI,EAAE,CAAC,CAAA;IACP,UAAU,EAAE,MAAM,CAAA;CACnB;AACD,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,IAAI,EAAE,CAAC,EAAE,CAAA;IACT,QAAQ,EAAE,OAAO,CAAA;IACjB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,qBAAa,UAAU;IACT,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,YAAY;IAEjD;;;OAGG;IACG,WAAW,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;IAOnD,qEAAqE;IAC/D,UAAU,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,CAAC,CAAC;YAI9C,OAAO;YA0BP,WAAW;CA+D1B"}