@kodar/send 0.1.0

package/dist/errors.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Error thrown for every non-2xx API response (and terminal network
+ * failures). `name` carries the API's machine-readable error name, e.g.
+ * "domain_not_verified", "rate_limit_exceeded", "invalid_api_key".
+ */
+export declare class SendError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, name: string, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,13 @@
+/**
+ * Error thrown for every non-2xx API response (and terminal network
+ * failures). `name` carries the API's machine-readable error name, e.g.
+ * "domain_not_verified", "rate_limit_exceeded", "invalid_api_key".
+ */
+export class SendError extends Error {
+    statusCode;
+    constructor(statusCode, name, message) {
+        super(message);
+        this.name = name;
+        this.statusCode = statusCode;
+    }
+}

package/dist/http.d.ts

@@ -0,0 +1,18 @@
+export interface HttpClientOptions {
+    apiKey: string;
+    baseUrl: string;
+    fetchFn: typeof fetch;
+    /** Extra attempts after the first (default 2). */
+    maxRetries: number;
+    timeoutMs: number;
+}
+export interface RequestParams {
+    query?: Record<string, string | number | undefined>;
+    body?: unknown;
+    idempotencyKey?: string;
+}
+export declare class HttpClient {
+    private readonly opts;
+    constructor(opts: HttpClientOptions);
+    request<T>(method: string, path: string, params?: RequestParams): Promise<T>;
+}

package/dist/http.js

@@ -0,0 +1,68 @@
+import { SendError } from "./errors.js";
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class HttpClient {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async request(method, path, params = {}) {
+        const url = new URL(this.opts.baseUrl.replace(/\/$/, "") + path);
+        for (const [key, value] of Object.entries(params.query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        const headers = {
+            authorization: `Bearer ${this.opts.apiKey}`,
+            "user-agent": "kodar-send-node/0.1.0",
+        };
+        if (params.body !== undefined)
+            headers["content-type"] = "application/json";
+        if (params.idempotencyKey)
+            headers["idempotency-key"] = params.idempotencyKey;
+        // Retry policy: 429 is always safe (the request was rejected before any
+        // processing). Network errors and 5xx retry only when the request is
+        // idempotent — reads, or writes carrying an Idempotency-Key.
+        const retriableWrite = method === "GET" || params.idempotencyKey !== undefined;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.opts.fetchFn(url, {
+                    method,
+                    headers,
+                    body: params.body !== undefined ? JSON.stringify(params.body) : undefined,
+                    signal: AbortSignal.timeout(this.opts.timeoutMs),
+                });
+            }
+            catch (err) {
+                if (attempt < this.opts.maxRetries && retriableWrite) {
+                    await sleep(250 * 2 ** attempt);
+                    continue;
+                }
+                throw new SendError(0, "network_error", `Request to ${url.pathname} failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (res.status === 429 && attempt < this.opts.maxRetries) {
+                const retryAfterSec = Math.min(Number(res.headers.get("retry-after")) || 1, 30);
+                await res.arrayBuffer().catch(() => undefined);
+                await sleep(retryAfterSec * 1000);
+                continue;
+            }
+            if (res.status >= 500 && attempt < this.opts.maxRetries && retriableWrite) {
+                await res.arrayBuffer().catch(() => undefined);
+                await sleep(250 * 2 ** attempt);
+                continue;
+            }
+            const text = await res.text();
+            let json;
+            try {
+                json = text ? JSON.parse(text) : {};
+            }
+            catch {
+                throw new SendError(res.status, "invalid_response", `Non-JSON response (HTTP ${res.status})`);
+            }
+            if (!res.ok) {
+                throw new SendError(res.status, typeof json.name === "string" ? json.name : "api_error", typeof json.message === "string" ? json.message : `HTTP ${res.status}`);
+            }
+            return json;
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,32 @@
+import { ApiKeys, Domains, Emails, Suppressions, Webhooks } from "./resources.js";
+export interface SendOptions {
+    /** API origin; defaults to the hosted platform. */
+    baseUrl?: string;
+    /** Injectable fetch (tests, custom agents). */
+    fetch?: typeof fetch;
+    /** Extra attempts after the first, for 429/transient failures. Default 2. */
+    maxRetries?: number;
+    /** Per-request timeout. Default 30 000 ms. */
+    timeoutMs?: number;
+}
+/**
+ * Send by Kodar API client.
+ *
+ *   const send = new Send("km_live_...");
+ *   const { id } = await send.emails.create({
+ *     from: "billing@acme.eu",
+ *     to: "mari@client.ee",
+ *     subject: "Invoice #4471",
+ *     html: invoice,
+ *   });
+ */
+export declare class Send {
+    readonly emails: Emails;
+    readonly domains: Domains;
+    readonly suppressions: Suppressions;
+    readonly webhooks: Webhooks;
+    readonly apiKeys: ApiKeys;
+    constructor(apiKey: string, options?: SendOptions);
+}
+export { SendError } from "./errors.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,38 @@
+import { HttpClient } from "./http.js";
+import { ApiKeys, Domains, Emails, Suppressions, Webhooks } from "./resources.js";
+/**
+ * Send by Kodar API client.
+ *
+ *   const send = new Send("km_live_...");
+ *   const { id } = await send.emails.create({
+ *     from: "billing@acme.eu",
+ *     to: "mari@client.ee",
+ *     subject: "Invoice #4471",
+ *     html: invoice,
+ *   });
+ */
+export class Send {
+    emails;
+    domains;
+    suppressions;
+    webhooks;
+    apiKeys;
+    constructor(apiKey, options = {}) {
+        if (!apiKey || !apiKey.startsWith("km_")) {
+            throw new Error('Send: expected an API key starting with "km_"');
+        }
+        const http = new HttpClient({
+            apiKey,
+            baseUrl: options.baseUrl ?? "https://send.kodar.io",
+            fetchFn: options.fetch ?? fetch,
+            maxRetries: options.maxRetries ?? 2,
+            timeoutMs: options.timeoutMs ?? 30_000,
+        });
+        this.emails = new Emails(http);
+        this.domains = new Domains(http);
+        this.suppressions = new Suppressions(http);
+        this.webhooks = new Webhooks(http);
+        this.apiKeys = new ApiKeys(http);
+    }
+}
+export { SendError } from "./errors.js";

package/dist/resources.d.ts

@@ -0,0 +1,97 @@
+import type { HttpClient } from "./http.js";
+import type { ApiKeyObject, ApiKeyWithSecret, CreateEmailInput, DomainObject, DomainVerifyResult, EmailEventObject, EmailObject, List, ListEmailsParams, RequestOptions, SendEmailResponse, SuppressionObject, WebhookEventType, WebhookObject, WebhookWithSecret } from "./types.js";
+export declare class Emails {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** POST /emails — returns as soon as the email is durably queued. */
+    create(input: CreateEmailInput, opts?: RequestOptions): Promise<SendEmailResponse>;
+    /** POST /emails/batch — up to 100 emails, all-or-nothing, no attachments. */
+    batch(inputs: CreateEmailInput[], opts?: RequestOptions): Promise<{
+        data: SendEmailResponse[];
+    }>;
+    get(id: string): Promise<EmailObject>;
+    list(params?: ListEmailsParams): Promise<List<EmailObject>>;
+    events(id: string): Promise<List<EmailEventObject>>;
+    cancel(id: string): Promise<EmailObject>;
+}
+export declare class Domains {
+    private readonly http;
+    constructor(http: HttpClient);
+    create(input: {
+        name: string;
+    }): Promise<DomainObject>;
+    list(): Promise<List<DomainObject>>;
+    get(id: string): Promise<DomainObject>;
+    /** Re-check DNS + provider verification now. */
+    verify(id: string): Promise<DomainVerifyResult>;
+    delete(id: string): Promise<{
+        object: "domain";
+        id: string;
+        deleted: boolean;
+    }>;
+}
+export declare class Suppressions {
+    private readonly http;
+    constructor(http: HttpClient);
+    list(params?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<List<SuppressionObject>>;
+    create(input: {
+        email: string;
+    }): Promise<SuppressionObject>;
+    /** Resolves when suppressed; throws SendError(404) when not. */
+    check(email: string): Promise<{
+        object: "suppression";
+        email: string;
+        suppressed: true;
+    }>;
+    delete(email: string): Promise<{
+        object: "suppression";
+        email: string;
+        deleted: boolean;
+    }>;
+}
+export declare class ApiKeys {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** The returned secret (km_live_...) is shown exactly once — store it. */
+    create(input: {
+        name: string;
+    }): Promise<ApiKeyWithSecret>;
+    list(): Promise<List<ApiKeyObject>>;
+    /** Soft revoke — the key stops authenticating immediately. Idempotent. */
+    revoke(id: string): Promise<{
+        object: "api_key";
+        id: string;
+        revoked: boolean;
+    }>;
+}
+export declare class Webhooks {
+    private readonly http;
+    constructor(http: HttpClient);
+    /** The returned secret (whsec_...) is shown exactly once — store it. */
+    create(input: {
+        url: string;
+        events: WebhookEventType[];
+    }): Promise<WebhookWithSecret>;
+    list(): Promise<List<WebhookObject>>;
+    get(id: string): Promise<WebhookObject>;
+    update(id: string, input: {
+        url?: string;
+        events?: WebhookEventType[];
+        status?: "enabled" | "disabled";
+    }): Promise<WebhookObject>;
+    delete(id: string): Promise<{
+        object: "webhook";
+        id: string;
+        deleted: boolean;
+    }>;
+    /** Push a synthetic event through the real queue + dispatcher. */
+    test(id: string): Promise<{
+        object: "webhook";
+        id: string;
+        test_enqueued: boolean;
+        delivery_id: string;
+    }>;
+}

package/dist/resources.js

@@ -0,0 +1,156 @@
+function toBase64(data) {
+    if (typeof Buffer !== "undefined")
+        return Buffer.from(data).toString("base64");
+    let binary = "";
+    for (const byte of data)
+        binary += String.fromCharCode(byte);
+    return btoa(binary);
+}
+function toIso(value) {
+    if (value === undefined)
+        return undefined;
+    return value instanceof Date ? value.toISOString() : value;
+}
+function toWirePayload(input) {
+    return {
+        from: input.from,
+        to: input.to,
+        cc: input.cc,
+        bcc: input.bcc,
+        reply_to: input.replyTo,
+        subject: input.subject,
+        html: input.html,
+        text: input.text,
+        headers: input.headers,
+        attachments: input.attachments?.map((a) => ({
+            filename: a.filename,
+            content: typeof a.content === "string" ? a.content : toBase64(a.content),
+            content_type: a.contentType,
+        })),
+    };
+}
+export class Emails {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** POST /emails — returns as soon as the email is durably queued. */
+    create(input, opts = {}) {
+        return this.http.request("POST", "/emails", {
+            body: toWirePayload(input),
+            idempotencyKey: opts.idempotencyKey,
+        });
+    }
+    /** POST /emails/batch — up to 100 emails, all-or-nothing, no attachments. */
+    batch(inputs, opts = {}) {
+        return this.http.request("POST", "/emails/batch", {
+            body: inputs.map(toWirePayload),
+            idempotencyKey: opts.idempotencyKey,
+        });
+    }
+    get(id) {
+        return this.http.request("GET", `/emails/${encodeURIComponent(id)}`);
+    }
+    list(params = {}) {
+        return this.http.request("GET", "/emails", {
+            query: {
+                status: params.status,
+                to: params.to,
+                created_after: toIso(params.createdAfter),
+                created_before: toIso(params.createdBefore),
+                limit: params.limit,
+                cursor: params.cursor,
+            },
+        });
+    }
+    events(id) {
+        return this.http.request("GET", `/emails/${encodeURIComponent(id)}/events`);
+    }
+    cancel(id) {
+        return this.http.request("POST", `/emails/${encodeURIComponent(id)}/cancel`);
+    }
+}
+export class Domains {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    create(input) {
+        return this.http.request("POST", "/domains", { body: input });
+    }
+    list() {
+        return this.http.request("GET", "/domains");
+    }
+    get(id) {
+        return this.http.request("GET", `/domains/${encodeURIComponent(id)}`);
+    }
+    /** Re-check DNS + provider verification now. */
+    verify(id) {
+        return this.http.request("POST", `/domains/${encodeURIComponent(id)}/verify`);
+    }
+    delete(id) {
+        return this.http.request("DELETE", `/domains/${encodeURIComponent(id)}`);
+    }
+}
+export class Suppressions {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(params = {}) {
+        return this.http.request("GET", "/suppressions", { query: params });
+    }
+    create(input) {
+        return this.http.request("POST", "/suppressions", { body: input });
+    }
+    /** Resolves when suppressed; throws SendError(404) when not. */
+    check(email) {
+        return this.http.request("GET", `/suppressions/${encodeURIComponent(email)}`);
+    }
+    delete(email) {
+        return this.http.request("DELETE", `/suppressions/${encodeURIComponent(email)}`);
+    }
+}
+export class ApiKeys {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** The returned secret (km_live_...) is shown exactly once — store it. */
+    create(input) {
+        return this.http.request("POST", "/api-keys", { body: input });
+    }
+    list() {
+        return this.http.request("GET", "/api-keys");
+    }
+    /** Soft revoke — the key stops authenticating immediately. Idempotent. */
+    revoke(id) {
+        return this.http.request("DELETE", `/api-keys/${encodeURIComponent(id)}`);
+    }
+}
+export class Webhooks {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** The returned secret (whsec_...) is shown exactly once — store it. */
+    create(input) {
+        return this.http.request("POST", "/webhooks", { body: input });
+    }
+    list() {
+        return this.http.request("GET", "/webhooks");
+    }
+    get(id) {
+        return this.http.request("GET", `/webhooks/${encodeURIComponent(id)}`);
+    }
+    update(id, input) {
+        return this.http.request("PATCH", `/webhooks/${encodeURIComponent(id)}`, { body: input });
+    }
+    delete(id) {
+        return this.http.request("DELETE", `/webhooks/${encodeURIComponent(id)}`);
+    }
+    /** Push a synthetic event through the real queue + dispatcher. */
+    test(id) {
+        return this.http.request("POST", `/webhooks/${encodeURIComponent(id)}/test`);
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,142 @@
+export type EmailStatus = "queued" | "sending" | "sent" | "delivered" | "bounced" | "complained" | "failed" | "canceled";
+export interface EmailObject {
+    object: "email";
+    id: string;
+    from: string;
+    to: string[];
+    cc: string[];
+    bcc: string[];
+    reply_to: string[];
+    subject: string;
+    html: string | null;
+    text: string | null;
+    headers: Record<string, string>;
+    attachments: {
+        filename: string;
+        content_type: string;
+        size: number;
+    }[];
+    status: EmailStatus;
+    provider_message_id: string | null;
+    error: {
+        name: string;
+        message: string;
+        permanent?: boolean;
+    } | null;
+    attempt: number;
+    max_attempts: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface EmailEventObject {
+    id: string;
+    type: string;
+    payload: Record<string, unknown> | null;
+    occurred_at: string;
+    created_at: string;
+}
+export interface DnsRecord {
+    purpose: string;
+    type: string;
+    host: string;
+    value: string;
+}
+export interface DomainObject {
+    object: "domain";
+    id: string;
+    name: string;
+    status: "pending" | "verified" | "failed";
+    dkim_selector: string;
+    mail_from_subdomain: string;
+    dns_records: DnsRecord[];
+    created_at: string;
+    verified_at: string | null;
+    last_checked_at: string | null;
+}
+export interface DomainVerifyResult extends DomainObject {
+    checks: {
+        dkim_dns: boolean;
+        backend_dkim: boolean;
+        backend_mail_from: boolean;
+    };
+}
+export interface SuppressionObject {
+    object: "suppression";
+    email: string;
+    reason: "hard_bounce" | "complaint" | "manual";
+    source_email_id?: string | null;
+    created_at?: string;
+}
+export type WebhookEventType = "email.sent" | "email.delivered" | "email.bounced" | "email.complained" | "email.delivery_delayed" | "email.failed";
+export interface WebhookObject {
+    object: "webhook";
+    id: string;
+    url: string;
+    events: string[];
+    status: "enabled" | "disabled";
+    created_at: string;
+}
+/** Returned by webhooks.create only — the secret is shown exactly once. */
+export interface WebhookWithSecret extends WebhookObject {
+    secret: string;
+}
+export interface ApiKeyObject {
+    object: "api_key";
+    id: string;
+    name: string;
+    key_prefix: string;
+    created_at: string;
+    last_used_at: string | null;
+    revoked_at: string | null;
+}
+/** Returned by apiKeys.create only — the secret is shown exactly once. */
+export interface ApiKeyWithSecret {
+    object: "api_key";
+    id: string;
+    name: string;
+    key_prefix: string;
+    created_at: string;
+    secret: string;
+}
+export interface List<T> {
+    object: "list";
+    data: T[];
+    next_cursor?: string | null;
+}
+export interface EmailAttachmentInput {
+    filename: string;
+    /** base64 string or raw bytes. */
+    content: string | Uint8Array;
+    contentType?: string;
+}
+export interface CreateEmailInput {
+    from: string;
+    to: string | string[];
+    cc?: string | string[];
+    bcc?: string | string[];
+    replyTo?: string | string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    headers?: Record<string, string>;
+    /** Not supported on batch sends. */
+    attachments?: EmailAttachmentInput[];
+}
+export interface SendEmailResponse {
+    id: string;
+    /** Recipients dropped because they are on the suppression list. */
+    suppressed_recipients?: string[];
+}
+export interface ListEmailsParams {
+    status?: EmailStatus;
+    /** Recipient filter (bare address). */
+    to?: string;
+    createdAfter?: Date | string;
+    createdBefore?: Date | string;
+    limit?: number;
+    cursor?: string;
+}
+export interface RequestOptions {
+    /** Sent as the Idempotency-Key header (POST /emails and /emails/batch). */
+    idempotencyKey?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+// Wire types, exactly as the API returns them (snake_case).
+export {};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@kodar/send",
+  "version": "0.1.0",
+  "description": "TypeScript SDK for Send by Kodar — the transactional email API. Zero runtime dependencies; Node 18+ (global fetch).",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@hono/node-server": "^1.13.0",
+    "@kodar/core": "*",
+    "@kodar/db": "*",
+    "@kodar/delivery": "*",
+    "@kodar/mail-api": "*",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}