bul-email 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BUL
+
+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

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+# bul-email
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<div dir="rtl">
+
+הספרייה הרשמית של **בול** — Email API למיילים טרנזקציוניים ולדיוור — ל-JavaScript ול-TypeScript.
+עובדת ב-Node 18 ומעלה, ב-Bun, ב-Deno ובסביבות edge. התיעוד המלא: [bul.friman.app/docs](https://bul.friman.app/docs).
+
+## התקנה
+
+</div>
+
+```bash
+npm install bul-email
+```
+
+<div dir="rtl">
+
+## שליחת מייל
+
+</div>
+
+```ts
+import { Bul } from "bul-email";
+
+const bul = new Bul({ apiKey: process.env.BUL_API_KEY! });
+
+const { id } = await bul.emails.send(
+  { from: "Acme <hi@acme.co.il>", to: ["dana@example.com"], subject: "שלום", html: "<p>ההזמנה שלך התקבלה</p>" },
+  { idempotencyKey: "order-1234" },
+);
+```
+
+<div dir="rtl">
+
+## מה יש בספרייה
+
+- **כל נקודות הקצה:** `status`, ‏`stats`, ‏`usage`, ‏`emails.{send,batch,get,list,listAll}`, ‏`events.{list,iterate}`,
+  ‏`campaigns.{create,get}`, ‏`domains.{list,create,get,delete}`, ‏`webhooks.{list,create,get,delete,test}`,
+  ‏`suppressions.{list,add,import,remove}`, ‏`recipients.proof`.
+- **ניסיונות חוזרים:** שגיאות רשת, timeout, ‏429 (לפי Retry-After), ‏500/502/503/504 ו-409 `already_processing` — עם המתנה הולכת וגדלה
+  (`maxRetries`, ברירת מחדל 3). לכל שליחה `Idempotency-Key` אחד, שחוזר בכל ניסיון — ניסיון חוזר אף פעם לא שולח פעמיים.
+- **שגיאות ברורות:** כל שגיאה מה-API היא `BulError` (או תת-מחלקה) עם `code` ו-`status`. ‏409 `route_paused` → ‏`RoutePausedError`
+  (`reasonCode`, ‏`returns[]`) — שום דבר לא התקבל; שולחים בדרך אחרת ומדווחים עם `recipients.proof`.
+- **Webhooks:** ‏`verifyWebhookSignature` / ‏`constructWebhookEvent` — ‏HMAC-SHA256, סבילות של 5 דקות, השוואה בזמן קבוע.
+  ‏`BulEvent` מוקלד לפי `event`.
+
+## מעבר מ-Resend
+
+כמעט אותו קוד: מחליפים את ה-import ואת המפתח. המדריך המלא: [מעבר מ-Resend לבול](https://bul.friman.app/docs#migrate-from-resend).
+
+## רישיון
+
+MIT
+
+</div>
+
+---
+
+## English
+
+The official JavaScript / TypeScript client for **BUL** — an Email API for transactional email and campaigns.
+Works on Node 18+, Bun, Deno and edge runtimes. Full documentation: [bul.friman.app/docs](https://bul.friman.app/docs).
+
+### Install
+
+```bash
+npm install bul-email
+```
+
+### Send an email
+
+```ts
+import { Bul } from "bul-email";
+
+const bul = new Bul({ apiKey: process.env.BUL_API_KEY! });
+
+const { id } = await bul.emails.send(
+  { from: "Acme <hi@acme.co.il>", to: ["dana@example.com"], subject: "Hello", html: "<p>Your order is confirmed</p>" },
+  { idempotencyKey: "order-1234" },
+);
+```
+
+### What's included
+
+- **Every endpoint**: `status`, `stats`, `usage`, `emails.{send,batch,get,list,listAll}`, `events.{list,iterate}`,
+  `campaigns.{create,get}`, `domains.{list,create,get,delete}`, `webhooks.{list,create,get,delete,test}`,
+  `suppressions.{list,add,import,remove}`, `recipients.proof`.
+- **Retries**: network errors, timeouts, 429 (honours Retry-After), 500/502/503/504 and 409 `already_processing`, with exponential
+  backoff (`maxRetries`, default 3). Each send gets one `Idempotency-Key`, reused on every retry — a retry never sends twice.
+- **Clear errors**: every API error is a `BulError` (or a subclass) with `code` and `status`. 409 `route_paused` → `RoutePausedError` (`reasonCode`,
+  `returns[]`) — nothing was accepted; send another way and report it with `recipients.proof`.
+- **Webhooks**: `verifyWebhookSignature` / `constructWebhookEvent` — HMAC-SHA256, 5-minute tolerance, constant-time comparison.
+  `BulEvent` is typed by `event`.
+
+### Migrating from Resend
+
+Almost the same code: change the import and the key. Full guide: [Migrating from Resend](https://bul.friman.app/docs#migrate-from-resend).
+
+### Changelog
+
+- **0.1.1** — documentation (this changelog) and the version string. No behavior changes. The first release published straight from the build pipeline, with a verified publisher.
+- **0.1.0** — first release.
+
+### License
+
+MIT

package/dist/errors.d.ts

@@ -0,0 +1,55 @@
+/** Errors thrown by the Bul client. `code` is the stable API error code; `message` is the API's (Hebrew) explanation. */
+export declare class BulError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** The full `error` object from the response (extra fields such as `limit`, `fields`, `returns`). */
+    readonly details: Record<string, unknown>;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown>);
+}
+/** 401 — missing, wrong or revoked API key. */
+export declare class AuthenticationError extends BulError {
+    name: string;
+}
+/** 403 — the key's scope is not allowed (forbidden), or a tier limit (tier_domain_limit). */
+export declare class PermissionError extends BulError {
+    name: string;
+}
+/** 429 — rate limit or daily tier limit, after the client's own retries were exhausted. */
+export declare class RateLimitError extends BulError {
+    readonly retryAfterSeconds: number | null;
+    name: string;
+    constructor(status: number, code: string, message: string, details: Record<string, unknown>, retryAfterSeconds: number | null);
+}
+/** 423 — account frozen (account_frozen) or sending blocked (sending_blocked). Reads still work. */
+export declare class AccountBlockedError extends BulError {
+    name: string;
+}
+export interface ReturnedMessage {
+    /** Position of the item in the batch, or of the recipient in the request. */
+    index: number;
+    recipient: string;
+    /** Report the outcome after resending with your provider: client.recipients.proof({ return_ref, ... }). */
+    return_ref: string;
+}
+/**
+ * 409 route_paused — nothing from the request was accepted; it is safe to send it with another provider.
+ * `reasonCode`: route_paused | recipient_not_proven | direct_unavailable.
+ */
+export declare class RoutePausedError extends BulError {
+    name: string;
+    readonly reasonCode: string;
+    readonly returns: ReturnedMessage[];
+    readonly safeToResend: true;
+    constructor(status: number, message: string, details: Record<string, unknown>);
+}
+/** The request could not reach Bul (network error / timeout) after all retries. */
+export declare class ConnectionError extends Error {
+    readonly cause?: unknown | undefined;
+    name: string;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** Webhook signature missing, invalid or too old. */
+export declare class WebhookVerificationError extends Error {
+    name: string;
+}
+export declare function errorFromResponse(status: number, body: unknown, retryAfterSeconds: number | null): BulError;

package/dist/errors.js

@@ -0,0 +1,79 @@
+/** Errors thrown by the Bul client. `code` is the stable API error code; `message` is the API's (Hebrew) explanation. */
+export class BulError extends Error {
+    status;
+    code;
+    /** The full `error` object from the response (extra fields such as `limit`, `fields`, `returns`). */
+    details;
+    constructor(status, code, message, details = {}) {
+        super(message);
+        this.name = "BulError";
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+/** 401 — missing, wrong or revoked API key. */
+export class AuthenticationError extends BulError {
+    name = "AuthenticationError";
+}
+/** 403 — the key's scope is not allowed (forbidden), or a tier limit (tier_domain_limit). */
+export class PermissionError extends BulError {
+    name = "PermissionError";
+}
+/** 429 — rate limit or daily tier limit, after the client's own retries were exhausted. */
+export class RateLimitError extends BulError {
+    retryAfterSeconds;
+    name = "RateLimitError";
+    constructor(status, code, message, details, retryAfterSeconds) {
+        super(status, code, message, details);
+        this.retryAfterSeconds = retryAfterSeconds;
+    }
+}
+/** 423 — account frozen (account_frozen) or sending blocked (sending_blocked). Reads still work. */
+export class AccountBlockedError extends BulError {
+    name = "AccountBlockedError";
+}
+/**
+ * 409 route_paused — nothing from the request was accepted; it is safe to send it with another provider.
+ * `reasonCode`: route_paused | recipient_not_proven | direct_unavailable.
+ */
+export class RoutePausedError extends BulError {
+    name = "RoutePausedError";
+    reasonCode;
+    returns;
+    safeToResend = true;
+    constructor(status, message, details) {
+        super(status, "route_paused", message, details);
+        this.reasonCode = typeof details["reason_code"] === "string" ? details["reason_code"] : "route_paused";
+        this.returns = Array.isArray(details["returns"]) ? details["returns"] : [];
+    }
+}
+/** The request could not reach Bul (network error / timeout) after all retries. */
+export class ConnectionError extends Error {
+    cause;
+    name = "ConnectionError";
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+    }
+}
+/** Webhook signature missing, invalid or too old. */
+export class WebhookVerificationError extends Error {
+    name = "WebhookVerificationError";
+}
+export function errorFromResponse(status, body, retryAfterSeconds) {
+    const e = (body?.error ?? {});
+    const code = typeof e["code"] === "string" ? e["code"] : `http_${status}`;
+    const message = typeof e["message"] === "string" ? e["message"] : `Bul API error ${status}`;
+    if (status === 409 && code === "route_paused")
+        return new RoutePausedError(status, message, e);
+    if (status === 401)
+        return new AuthenticationError(status, code, message, e);
+    if (status === 403)
+        return new PermissionError(status, code, message, e);
+    if (status === 429)
+        return new RateLimitError(status, code, message, e, retryAfterSeconds);
+    if (status === 423)
+        return new AccountBlockedError(status, code, message, e);
+    return new BulError(status, code, message, e);
+}

package/dist/index.d.ts

@@ -0,0 +1,154 @@
+import type * as T from "./types";
+export * from "./errors";
+export * from "./types";
+export { constructWebhookEvent, verifyWebhookSignature, type VerifyOptions } from "./webhooks";
+/**
+ * Bul — official JavaScript / TypeScript client (https://bul.friman.app/docs).
+ *
+ *   const bul = new Bul({ apiKey: process.env.BUL_API_KEY! });
+ *   const { id } = await bul.emails.send({ from: "Acme <hi@acme.co.il>", to: ["dana@example.com"], subject: "שלום", html: "<p>…</p>" });
+ *
+ * Retries: network errors, timeouts, 429 (honours Retry-After), 500/502/503/504 and 409 already_processing are retried with
+ * exponential backoff — but a POST is retried after a network error / 5xx only when it is idempotent: sends carry an
+ * `Idempotency-Key` that the client generates once per call and reuses on every retry, so a retry never sends twice.
+ * 409 route_paused is never retried: it throws RoutePausedError (nothing was accepted; `returns[].return_ref` for reporting).
+ */
+export interface BulOptions {
+    apiKey: string;
+    /** Default https://bul.friman.app */
+    baseUrl?: string;
+    /** Retries after the first attempt. Default 3. */
+    maxRetries?: number;
+    /** Per-attempt timeout. Default 30 seconds. */
+    timeoutMs?: number;
+    /** Custom fetch (tests, proxies, edge runtimes). */
+    fetch?: typeof fetch;
+    /** For tests: replaces the wait between retries. */
+    sleep?: (ms: number) => Promise<void>;
+}
+type Query = Record<string, string | number | boolean | string[] | undefined>;
+interface RequestSpec {
+    method: "GET" | "POST" | "DELETE";
+    path: string;
+    query?: Query;
+    body?: unknown;
+    idempotencyKey?: string;
+    /** POST that is safe to repeat even without an Idempotency-Key (the API deduplicates). */
+    idempotent?: boolean;
+}
+export declare const SDK_VERSION = "0.1.1";
+export declare class Bul {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly sleep;
+    constructor(opts: BulOptions);
+    /** Low-level request — prefer the typed methods below. */
+    request<R>(spec: RequestSpec): Promise<R>;
+    /** GET /v1/status — key, sending state, rate limit, domains. Any key scope. */
+    status(): Promise<T.AccountStatus>;
+    /** GET /v1/stats */
+    stats(): Promise<T.Stats>;
+    /** GET /v1/usage — per month, or per campaign. */
+    usage(params?: {
+        group?: "campaign";
+    }): Promise<{
+        data: Record<string, unknown>[];
+    } & Record<string, unknown>>;
+    readonly emails: {
+        /** POST /v1/emails — one recipient. `idempotencyKey` defaults to a new UUID (reused across retries). */
+        send: (input: T.SendEmailInput, opts?: {
+            idempotencyKey?: string;
+        }) => Promise<T.SendEmailResponse>;
+        /** POST /v1/emails/batch — an object (same message, up to 100 recipients) or an array of up to 100 different messages. */
+        batch: <I extends T.BatchObjectInput | T.BatchItemInput[]>(input: I, opts?: {
+            idempotencyKey?: string;
+            mode?: "partial" | "atomic";
+        }) => Promise<I extends T.BatchItemInput[] ? T.BatchItemsResponse : T.BatchObjectResponse>;
+        /** GET /v1/emails/{id} — `includeHtml` adds html and text. */
+        get: (id: string, opts?: {
+            includeHtml?: boolean;
+        }) => Promise<T.Email>;
+        /** GET /v1/emails — one page, newest first. */
+        list: (params?: T.ListEmailsParams) => Promise<T.Page<T.Email>>;
+        /** All pages (async iterator). */
+        listAll: (params?: Omit<T.ListEmailsParams, "cursor">) => AsyncGenerator<T.Email>;
+    };
+    readonly events: {
+        /** GET /v1/events — events in the order Bul received them (the same shape as webhooks). */
+        list: (params?: T.ListEventsParams) => Promise<T.Page<T.BulEvent>>;
+        /** All pages from `since` (async iterator). Save the last `next_cursor` to resume later. */
+        iterate: (params?: Omit<T.ListEventsParams, "cursor">) => AsyncGenerator<T.BulEvent>;
+    };
+    readonly campaigns: {
+        /** POST /v1/campaigns — up to 10,000 recipients (kind defaults to marketing). */
+        create: (input: T.CampaignInput, opts?: {
+            idempotencyKey?: string;
+        }) => Promise<T.Campaign>;
+        get: (id: string, opts?: {
+            includeHtml?: boolean;
+        }) => Promise<T.Campaign>;
+    };
+    readonly domains: {
+        list: () => Promise<{
+            data: T.Domain[];
+        }>;
+        /** POST /v1/domains (full key). */
+        create: (domain: string) => Promise<T.Domain>;
+        get: (id: string) => Promise<T.Domain>;
+        delete: (id: string) => Promise<void>;
+    };
+    readonly webhooks: {
+        list: () => Promise<{
+            data: T.Webhook[];
+        }>;
+        /** POST /v1/webhooks (full key). The `signing_secret` is returned only here — store it. */
+        create: (input: {
+            url: string;
+            events: T.WebhookEventName[];
+        }) => Promise<T.CreatedWebhook>;
+        get: (id: string) => Promise<T.Webhook>;
+        delete: (id: string) => Promise<void>;
+        /** POST /v1/webhooks/{id}/test — a signed test event (optionally of a chosen type). */
+        test: (id: string, spec?: T.WebhookTestSpec) => Promise<T.WebhookTestResult>;
+    };
+    readonly suppressions: {
+        list: (params?: {
+            limit?: number;
+            offset?: number;
+        }) => Promise<{
+            data: T.Suppression[];
+            total: number;
+            limit: number;
+            offset: number;
+        }>;
+        add: (input: {
+            recipient: string;
+            reason?: T.SuppressionReason;
+        }) => Promise<T.Suppression | {
+            recipient: string;
+            already_suppressed: true;
+        }>;
+        import: (input: {
+            recipients: string[];
+            reason?: T.SuppressionReason;
+        }) => Promise<{
+            added: number;
+            already_suppressed: number;
+            invalid: string[];
+        }>;
+        /** DELETE /v1/suppressions/{id or email} (full key). */
+        remove: (idOrEmail: string) => Promise<void>;
+    };
+    readonly recipients: {
+        /**
+         * POST /v1/recipients/proof — report the outcome of a message Bul returned to you (`return_ref` from RoutePausedError.returns
+         * or from a `withdrawn` event) after you sent it with your own provider. Idempotent by return_ref + outcome.
+         */
+        proof: (input: T.ProofInput) => Promise<T.ProofResponse>;
+    };
+    private paginate;
+}
+export default Bul;

package/dist/index.js

@@ -0,0 +1,185 @@
+import { BulError, ConnectionError, errorFromResponse } from "./errors";
+export * from "./errors";
+export * from "./types";
+export { constructWebhookEvent, verifyWebhookSignature } from "./webhooks";
+const RETRY_STATUS = new Set([500, 502, 503, 504]);
+export const SDK_VERSION = "0.1.1";
+function newKey() {
+    return typeof crypto !== "undefined" && "randomUUID" in crypto
+        ? crypto.randomUUID()
+        : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}${Math.random().toString(36).slice(2)}`;
+}
+function retryAfterSeconds(h) {
+    if (!h)
+        return null;
+    if (/^\d+$/.test(h.trim()))
+        return Number(h.trim());
+    const t = Date.parse(h);
+    return Number.isNaN(t) ? null : Math.max(0, Math.ceil((t - Date.now()) / 1000));
+}
+export class Bul {
+    apiKey;
+    baseUrl;
+    maxRetries;
+    timeoutMs;
+    fetchImpl;
+    sleep;
+    constructor(opts) {
+        if (!opts?.apiKey)
+            throw new Error("Bul: apiKey is required");
+        this.apiKey = opts.apiKey;
+        this.baseUrl = (opts.baseUrl ?? "https://bul.friman.app").replace(/\/$/, "");
+        this.maxRetries = opts.maxRetries ?? 3;
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        this.fetchImpl = opts.fetch ?? ((...a) => fetch(...a));
+        this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    }
+    /** Low-level request — prefer the typed methods below. */
+    async request(spec) {
+        const url = new URL(`${this.baseUrl}${spec.path}`);
+        for (const [k, v] of Object.entries(spec.query ?? {})) {
+            if (v === undefined)
+                continue;
+            url.searchParams.set(k, Array.isArray(v) ? v.join(",") : String(v));
+        }
+        const headers = {
+            authorization: `Bearer ${this.apiKey}`,
+            accept: "application/json",
+            "user-agent": `bul-js/${SDK_VERSION}`,
+        };
+        if (spec.body !== undefined)
+            headers["content-type"] = "application/json";
+        if (spec.idempotencyKey)
+            headers["idempotency-key"] = spec.idempotencyKey;
+        const safeToRepeat = spec.method !== "POST" || !!spec.idempotencyKey || !!spec.idempotent;
+        let lastError;
+        for (let attempt = 0;; attempt++) {
+            const backoff = (min = 0) => Math.max(min, Math.min(30_000, 500 * 2 ** attempt) * (0.75 + Math.random() * 0.5));
+            let res;
+            try {
+                res = await this.fetchImpl(url.toString(), {
+                    method: spec.method,
+                    headers,
+                    ...(spec.body !== undefined ? { body: JSON.stringify(spec.body) } : {}),
+                    signal: AbortSignal.timeout(this.timeoutMs),
+                });
+            }
+            catch (error) {
+                lastError = error;
+                if (safeToRepeat && attempt < this.maxRetries) {
+                    await this.sleep(backoff());
+                    continue;
+                }
+                throw new ConnectionError(`Bul: request failed (${spec.method} ${spec.path}): ${error?.message ?? error}`, error);
+            }
+            if (res.status === 204)
+                return undefined;
+            const text = await res.text().catch(() => "");
+            // A non-JSON body (e.g. an HTML 502 page from a proxy) must not throw SyntaxError — fall through to status handling.
+            let body = null;
+            try {
+                body = text ? JSON.parse(text) : null;
+            }
+            catch {
+                body = res.ok ? text : { error: { code: `http_${res.status}`, message: text.slice(0, 200) || `HTTP ${res.status}` } };
+            }
+            if (res.ok)
+                return body;
+            const ra = retryAfterSeconds(res.headers.get("retry-after"));
+            const code = body?.error?.code;
+            const retryable = res.status === 429 ||
+                (res.status === 409 && code === "already_processing") ||
+                (RETRY_STATUS.has(res.status) && safeToRepeat);
+            if (retryable && attempt < this.maxRetries) {
+                await this.sleep(ra !== null ? ra * 1000 : backoff(res.status === 409 ? 1000 : 0));
+                continue;
+            }
+            throw errorFromResponse(res.status, body, ra);
+        }
+        // unreachable
+        throw lastError instanceof BulError ? lastError : new ConnectionError("Bul: request failed");
+    }
+    /** GET /v1/status — key, sending state, rate limit, domains. Any key scope. */
+    status() {
+        return this.request({ method: "GET", path: "/v1/status" });
+    }
+    /** GET /v1/stats */
+    stats() {
+        return this.request({ method: "GET", path: "/v1/stats" });
+    }
+    /** GET /v1/usage — per month, or per campaign. */
+    usage(params = {}) {
+        return this.request({ method: "GET", path: "/v1/usage", query: params });
+    }
+    emails = {
+        /** POST /v1/emails — one recipient. `idempotencyKey` defaults to a new UUID (reused across retries). */
+        send: (input, opts = {}) => this.request({ method: "POST", path: "/v1/emails", body: input, idempotencyKey: opts.idempotencyKey ?? newKey() }),
+        /** POST /v1/emails/batch — an object (same message, up to 100 recipients) or an array of up to 100 different messages. */
+        batch: (input, opts = {}) => this.request({
+            method: "POST",
+            path: "/v1/emails/batch",
+            query: { mode: opts.mode },
+            body: input,
+            idempotencyKey: opts.idempotencyKey ?? newKey(),
+        }),
+        /** GET /v1/emails/{id} — `includeHtml` adds html and text. */
+        get: (id, opts = {}) => this.request({ method: "GET", path: `/v1/emails/${encodeURIComponent(id)}`, query: { include: opts.includeHtml ? "html" : undefined } }),
+        /** GET /v1/emails — one page, newest first. */
+        list: (params = {}) => this.request({ method: "GET", path: "/v1/emails", query: params }),
+        /** All pages (async iterator). */
+        listAll: (params = {}) => this.paginate((cursor) => this.emails.list({ ...params, ...(cursor ? { cursor } : {}) })),
+    };
+    events = {
+        /** GET /v1/events — events in the order Bul received them (the same shape as webhooks). */
+        list: (params = {}) => this.request({ method: "GET", path: "/v1/events", query: params }),
+        /** All pages from `since` (async iterator). Save the last `next_cursor` to resume later. */
+        iterate: (params = {}) => this.paginate((cursor) => this.events.list({ ...params, ...(cursor ? { cursor } : {}) })),
+    };
+    campaigns = {
+        /** POST /v1/campaigns — up to 10,000 recipients (kind defaults to marketing). */
+        create: (input, opts = {}) => this.request({ method: "POST", path: "/v1/campaigns", body: input, idempotencyKey: opts.idempotencyKey ?? newKey() }),
+        get: (id, opts = {}) => this.request({ method: "GET", path: `/v1/campaigns/${encodeURIComponent(id)}`, query: { include: opts.includeHtml ? "html" : undefined } }),
+    };
+    domains = {
+        list: () => this.request({ method: "GET", path: "/v1/domains" }),
+        /** POST /v1/domains (full key). */
+        create: (domain) => this.request({ method: "POST", path: "/v1/domains", body: { domain } }),
+        get: (id) => this.request({ method: "GET", path: `/v1/domains/${encodeURIComponent(id)}` }),
+        delete: (id) => this.request({ method: "DELETE", path: `/v1/domains/${encodeURIComponent(id)}` }),
+    };
+    webhooks = {
+        list: () => this.request({ method: "GET", path: "/v1/webhooks" }),
+        /** POST /v1/webhooks (full key). The `signing_secret` is returned only here — store it. */
+        create: (input) => this.request({ method: "POST", path: "/v1/webhooks", body: input }),
+        get: (id) => this.request({ method: "GET", path: `/v1/webhooks/${encodeURIComponent(id)}` }),
+        delete: (id) => this.request({ method: "DELETE", path: `/v1/webhooks/${encodeURIComponent(id)}` }),
+        /** POST /v1/webhooks/{id}/test — a signed test event (optionally of a chosen type). */
+        test: (id, spec) => this.request({ method: "POST", path: `/v1/webhooks/${encodeURIComponent(id)}/test`, ...(spec ? { body: spec } : {}) }),
+    };
+    suppressions = {
+        list: (params = {}) => this.request({ method: "GET", path: "/v1/suppressions", query: params }),
+        add: (input) => this.request({ method: "POST", path: "/v1/suppressions", body: input, idempotent: true }),
+        import: (input) => this.request({ method: "POST", path: "/v1/suppressions/import", body: input, idempotent: true }),
+        /** DELETE /v1/suppressions/{id or email} (full key). */
+        remove: (idOrEmail) => this.request({ method: "DELETE", path: `/v1/suppressions/${encodeURIComponent(idOrEmail)}` }),
+    };
+    recipients = {
+        /**
+         * POST /v1/recipients/proof — report the outcome of a message Bul returned to you (`return_ref` from RoutePausedError.returns
+         * or from a `withdrawn` event) after you sent it with your own provider. Idempotent by return_ref + outcome.
+         */
+        proof: (input) => this.request({ method: "POST", path: "/v1/recipients/proof", body: input, idempotent: true }),
+    };
+    async *paginate(page) {
+        let cursor = null;
+        for (;;) {
+            const p = await page(cursor);
+            for (const item of p.data)
+                yield item;
+            if (!p.has_more || !p.next_cursor)
+                return;
+            cursor = p.next_cursor;
+        }
+    }
+}
+export default Bul;

package/dist/types.d.ts

@@ -0,0 +1,339 @@
+/**
+ * Bul API — types. Field names are snake_case, exactly as the API sends and receives them (https://bul.friman.app/docs).
+ */
+export type ApiKeyScope = "read" | "send" | "full";
+export type MessageKind = "transactional" | "marketing";
+export type MessageStatus = "queued" | "sending" | "sent" | "delivered" | "opened" | "clicked" | "bounced" | "complained" | "unsubscribed" | "failed" | "deferred" | "withdrawn";
+export type Tags = Record<string, string>;
+export type Attachment = {
+    filename: string;
+    content_type: string;
+    content: string;
+    content_id?: string;
+} | {
+    filename: string;
+    url: string;
+    content_type?: string;
+    content_id?: string;
+};
+export interface SendEmailInput {
+    from: string;
+    to: string[];
+    subject: string;
+    html?: string;
+    text?: string;
+    track_clicks?: boolean;
+    kind?: MessageKind;
+    reply_to?: string[];
+    headers?: Record<string, string>;
+    tags?: Tags;
+    attachments?: Attachment[];
+}
+export interface SendEmailResponse {
+    id: string;
+    recipient: string;
+}
+/** Batch, form 1: the same message to up to 100 recipients. */
+export type BatchObjectInput = SendEmailInput;
+export interface BatchObjectResponse {
+    queued: {
+        id: string;
+        recipient: string;
+    }[];
+    suppressed: string[];
+    invalid: string[];
+}
+/** Batch, form 2: up to 100 different messages, one recipient each. */
+export interface BatchItemInput extends Omit<SendEmailInput, "to"> {
+    to: string;
+    idempotency_key?: string;
+}
+export interface BatchItemsResponse {
+    data: ({
+        index: number;
+        id: string;
+        recipient: string;
+        deduplicated?: boolean;
+    } | {
+        index: number;
+        recipient: string;
+        error: {
+            code: string;
+            message: string;
+        };
+    })[];
+    summary: {
+        queued: number;
+        deduplicated: number;
+        failed: number;
+    };
+}
+export interface BounceInfo {
+    event: string;
+    bounce_type: "hard" | "soft" | null;
+    bounce_sub_type: string | null;
+    smtp_status: string | null;
+    smtp_diagnostic: string | null;
+    timestamp: string;
+}
+export interface Email {
+    id: string;
+    recipient: string;
+    from: string;
+    subject: string;
+    status: MessageStatus;
+    attempts: number;
+    campaign_id: string | null;
+    last_error: string | null;
+    created_at: string;
+    reply_to?: string[];
+    headers?: Record<string, string>;
+    track_clicks?: boolean;
+    tags: Tags;
+    attachments?: {
+        filename: string;
+        content_type: string;
+        size: number;
+    }[];
+    content_purged_at?: string | null;
+    bounce?: BounceInfo | null;
+    html?: string | null;
+    text?: string | null;
+}
+export interface ListEmailsParams {
+    recipient?: string;
+    status?: MessageStatus | MessageStatus[];
+    since?: string;
+    until?: string;
+    campaign_id?: string;
+    limit?: number;
+    cursor?: string;
+}
+export interface Page<T> {
+    data: T[];
+    has_more: boolean;
+    next_cursor: string | null;
+}
+export interface CampaignInput extends SendEmailInput {
+}
+export interface Campaign {
+    id: string;
+    status: string;
+    [key: string]: unknown;
+}
+export interface Domain {
+    id: string;
+    domain: string;
+    status: "verified" | "pending" | "failed";
+    [key: string]: unknown;
+}
+export type WebhookEventName = "delivered" | "opened" | "clicked" | "bounced" | "deferred" | "complained" | "unsubscribed" | "failed" | "withdrawn" | "stuck" | "reputation.warning" | "reputation.paused" | "compliance.unsubscribe_missing";
+export interface Webhook {
+    id: string;
+    url: string;
+    events: WebhookEventName[];
+    active: boolean;
+    created_at: string;
+}
+export interface CreatedWebhook extends Webhook {
+    signing_secret: string;
+}
+export interface WebhookTestSpec {
+    event?: WebhookEventName | "test";
+    smtp_status?: string;
+    smtp_diagnostic?: string;
+    bounce_sub_type?: string;
+    reason_code?: string;
+    attempted?: boolean;
+    recipient?: string;
+    message_id?: string;
+    tags?: Tags;
+}
+export interface WebhookTestResult {
+    delivery_id: string;
+    event_id: string;
+    delivered: boolean;
+    response_code: number | null;
+    duration_ms: number;
+    error: string | null;
+}
+export type SuppressionReason = "hard_bounce" | "complaint" | "manual" | "unsubscribe";
+export interface Suppression {
+    id: string;
+    recipient: string;
+    reason: SuppressionReason;
+    source: string | null;
+    created_at: string;
+}
+export interface AccountStatus {
+    key: {
+        name: string | null;
+        scope: ApiKeyScope;
+    };
+    sending: {
+        status: "open" | "blocked";
+        reason: string | null;
+        reputation_warning: boolean;
+        frozen?: boolean;
+        frozen_at?: string;
+    };
+    rate_limit: {
+        limit: number;
+        remaining: number;
+        reset_seconds: number;
+    };
+    domains: {
+        domain: string;
+        status: "verified" | "pending" | "failed";
+    }[];
+    queue_processing: boolean;
+    compliance: {
+        unsubscribe: null | {
+            level: "warning" | "strong";
+            reason: string;
+            detected_at: string;
+        };
+    };
+}
+export interface Stats {
+    sent: number;
+    delivered: number;
+    bounced: number;
+    complained: number;
+    opened: number;
+    clicked: number;
+    unique_opens: number;
+    unique_clicks: number;
+    /** Estimated human opens: opens not flagged machine_open (Apple MPP, Gmail prefetch, scanners, too-fast opens). */
+    human_opens?: number;
+    unique_human_opens?: number;
+}
+export interface ProofInput {
+    return_ref: string;
+    recipient: string;
+    provider: string;
+    outcome: "delivered" | "bounced" | "complained";
+    occurred_at: string;
+    provider_message_id?: string;
+}
+/** One outcome per return_ref: bounced/complained supersede delivered (`superseded`); a contradicting report → 409 conflicting_outcome (BulError). */
+export interface ProofResponse {
+    accepted: true;
+    return_ref: string;
+    outcome: ProofInput["outcome"];
+    duplicate: boolean;
+    superseded?: "delivered";
+}
+export interface FailureReason {
+    code: string;
+    description: string;
+}
+interface BaseMessageEvent {
+    event_id: string;
+    message_id: string;
+    recipient: string;
+    campaign_id: string | null;
+    timestamp: string;
+    tags: Tags;
+    /** Present (true) on events sent by POST /v1/webhooks/{id}/test. */
+    test?: true;
+    /** GET /v1/events only. */
+    id?: string;
+    received_at?: string;
+}
+interface BounceFields {
+    bounce_type?: "hard" | "soft";
+    bounce_sub_type?: string;
+    smtp_status?: string;
+    smtp_diagnostic?: string;
+}
+export interface DeliveredEvent extends BaseMessageEvent {
+    event: "delivered";
+}
+export interface OpenedEvent extends BaseMessageEvent {
+    event: "opened";
+    /** Estimate: the open looks automatic (image prefetch / scanner), not a person. The event is still a real pixel load. */
+    machine_open?: boolean;
+    /** Rule, optionally followed by ":<ip owner>" for fast_open / scanner, e.g. "fast_open:netfree", "scanner:security_vendor". */
+    machine_open_reason?: "apple_mpp" | "google_prefetch" | "scanner" | "fast_open" | `${"scanner" | "fast_open"}:${string}` | null;
+}
+export interface ClickedEvent extends BaseMessageEvent {
+    event: "clicked";
+    clicked_url: string;
+}
+export interface BouncedEvent extends BaseMessageEvent, BounceFields {
+    event: "bounced";
+}
+export interface DeferredEvent extends BaseMessageEvent, BounceFields {
+    event: "deferred";
+}
+export interface ComplainedEvent extends BaseMessageEvent {
+    event: "complained";
+}
+export interface UnsubscribedEvent extends BaseMessageEvent {
+    event: "unsubscribed";
+}
+export interface FailedEvent extends BaseMessageEvent, BounceFields {
+    event: "failed";
+    reason: FailureReason;
+    /** false only for ambiguous_delivery — the message may have been delivered. */
+    safe_to_resend: boolean;
+    /** Deprecated text field kept for compatibility. */
+    error?: string | null;
+}
+export interface WithdrawnEvent extends BaseMessageEvent {
+    event: "withdrawn";
+    reason: {
+        code: "route_paused" | "recipient_not_proven" | "direct_unavailable" | string;
+        description: string;
+    };
+    attempted: boolean;
+    safe_to_resend: true;
+    /** Report the result after resending with your provider: POST /v1/recipients/proof. */
+    return_ref?: string;
+}
+export interface StuckEvent extends BaseMessageEvent {
+    event: "stuck";
+}
+export interface ReputationEvent {
+    event: "reputation.warning" | "reputation.paused";
+    event_id: string;
+    timestamp: string;
+    reasons: ("bounce_rate" | "complaint_rate")[];
+    sending_status: string;
+    window_hours: number;
+    volume: number;
+    bounced: number;
+    complained: number;
+    bounce_rate: number;
+    complaint_rate: number;
+    thresholds: Record<string, number>;
+    test?: true;
+}
+export interface ComplianceEvent {
+    event: "compliance.unsubscribe_missing";
+    event_id: string;
+    timestamp: string;
+    level: "warning" | "strong";
+    reason: string;
+    source: string;
+    recipients?: number;
+    subject?: string;
+    test?: true;
+}
+export interface TestEvent {
+    event: "test";
+    event_id: string;
+    timestamp: string;
+    test: true;
+    message_id: null;
+    [key: string]: unknown;
+}
+export type BulEvent = DeliveredEvent | OpenedEvent | ClickedEvent | BouncedEvent | DeferredEvent | ComplainedEvent | UnsubscribedEvent | FailedEvent | WithdrawnEvent | StuckEvent | ReputationEvent | ComplianceEvent | TestEvent;
+export interface ListEventsParams {
+    since?: string;
+    cursor?: string;
+    limit?: number;
+    type?: Exclude<WebhookEventName, "stuck" | "reputation.warning" | "reputation.paused" | "compliance.unsubscribe_missing">;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Bul API — types. Field names are snake_case, exactly as the API sends and receives them (https://bul.friman.app/docs).
+ */
+export {};

package/dist/webhooks.d.ts

@@ -0,0 +1,24 @@
+import type { BulEvent } from "./types";
+/**
+ * Webhook signature: `Bul-Signature` = hex HMAC-SHA256 of `${Bul-Timestamp}.${rawBody}` with the webhook's signing secret.
+ * Uses Web Crypto, so it runs on Node 18+, Bun, Deno and edge runtimes. Always verify the **raw** request body (before JSON parsing).
+ */
+type HeaderBag = Headers | Record<string, string | string[] | undefined>;
+export interface VerifyOptions {
+    /** Raw body exactly as received (string or bytes). */
+    rawBody: string | Uint8Array;
+    headers: HeaderBag;
+    secret: string;
+    /** Reject timestamps older/newer than this many seconds. Default 300 (5 minutes), as recommended in /docs. */
+    toleranceSeconds?: number;
+    /** For tests. */
+    now?: Date;
+}
+/** true if the signature is valid and the timestamp is fresh. */
+export declare function verifyWebhookSignature(opts: VerifyOptions): Promise<boolean>;
+/**
+ * Verify and parse a webhook. Throws WebhookVerificationError if the signature is invalid or stale.
+ * Deduplicate on `event.event_id` (identical across redeliveries and in GET /v1/events).
+ */
+export declare function constructWebhookEvent(opts: VerifyOptions): Promise<BulEvent>;
+export {};

package/dist/webhooks.js

@@ -0,0 +1,50 @@
+import { WebhookVerificationError } from "./errors";
+function header(headers, name) {
+    if (typeof headers.get === "function")
+        return headers.get(name);
+    const bag = headers;
+    const key = Object.keys(bag).find((k) => k.toLowerCase() === name.toLowerCase());
+    const v = key ? bag[key] : undefined;
+    return Array.isArray(v) ? (v[0] ?? null) : (v ?? null);
+}
+const enc = new TextEncoder();
+async function hmacHex(secret, data) {
+    const key = await crypto.subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const sig = new Uint8Array(await crypto.subtle.sign("HMAC", key, data));
+    return Array.from(sig, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+function constantTimeEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/** true if the signature is valid and the timestamp is fresh. */
+export async function verifyWebhookSignature(opts) {
+    const ts = header(opts.headers, "bul-timestamp");
+    const got = header(opts.headers, "bul-signature");
+    if (!ts || !got || !/^\d+$/.test(ts))
+        return false;
+    const now = (opts.now ?? new Date()).getTime() / 1000;
+    if (Math.abs(now - Number(ts)) > (opts.toleranceSeconds ?? 300))
+        return false;
+    const body = typeof opts.rawBody === "string" ? enc.encode(opts.rawBody) : opts.rawBody;
+    const prefix = enc.encode(`${ts}.`);
+    const data = new Uint8Array(new ArrayBuffer(prefix.length + body.length));
+    data.set(prefix, 0);
+    data.set(body, prefix.length);
+    const expected = await hmacHex(opts.secret, data);
+    return constantTimeEqual(got.trim().toLowerCase(), expected);
+}
+/**
+ * Verify and parse a webhook. Throws WebhookVerificationError if the signature is invalid or stale.
+ * Deduplicate on `event.event_id` (identical across redeliveries and in GET /v1/events).
+ */
+export async function constructWebhookEvent(opts) {
+    if (!(await verifyWebhookSignature(opts)))
+        throw new WebhookVerificationError("Invalid or expired Bul webhook signature");
+    const text = typeof opts.rawBody === "string" ? opts.rawBody : new TextDecoder().decode(opts.rawBody);
+    return JSON.parse(text);
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "bul-email",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Official JavaScript/TypeScript client for the Bul email API (bul.friman.app)",
+  "keywords": [
+    "email",
+    "email-api",
+    "transactional-email",
+    "bul",
+    "hebrew",
+    "israel",
+    "resend-alternative"
+  ],
+  "homepage": "https://bul.friman.app/docs#sdk",
+  "author": "BUL <support@friman.app>",
+  "bugs": {
+    "email": "support@friman.app"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "bun test",
+    "prepublishOnly": "tsc -p tsconfig.json"
+  },
+  "license": "MIT"
+}