@bloomscorp/bloomsight-node 0.0.1-placeholder.0 → 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bloomscorp
+
+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,4 +1,137 @@
 # @bloomscorp/bloomsight-node
 
-This version is a placeholder that reserves the package name. Install the latest
-version: `npm install @bloomscorp/bloomsight-node`.
+Send [Bloomsight](https://bloomscorp.com) email templates from your Node.js backend.
+
+Bloomsight decides what every email says: you send a **template id and values**, never
+a subject or HTML. The template, its recipients and the mailbox it goes from are set up
+in your project's Bloomsight dashboard.
+
+- **Safe to retry.** Every send carries an idempotency key, so a retry, a timeout or a
+  restarted process never sends the same email twice.
+- **Retries for you** on network errors, `429` and `5xx`, honouring `Retry-After`.
+- **One error type**, `BloomsightError`, with a `code` to branch on. Your key never
+  appears in an error.
+- **Typed**, ESM and CommonJS, no runtime dependencies, Node 18+.
+- **Server only.** It refuses to start in a browser, where the key would be exposed.
+  For browser forms, use `@bloomscorp/bloomsight.js`.
+
+## Install
+
+```bash
+npm install @bloomscorp/bloomsight-node
+```
+
+## Set up
+
+1. In the Bloomsight dashboard, open the template and set its **sending channel** to
+   **API only**. A template that takes its recipient from the values (for example
+   `{{email}}`) must be API only, so nobody can trigger it from a web page.
+2. In **Project Settings → API keys**, create a key with the **`bloomsight-email`**
+   scope. Keep it in your server's environment, never in code or a browser.
+   A `blm_test_…` key checks everything and sends nothing: use it in development.
+
+## Send an email
+
+```ts
+import {Bloomsight, BloomsightError} from '@bloomscorp/bloomsight-node';
+
+const bloomsight = new Bloomsight({apiKey: process.env.BLOOMSIGHT_API_KEY!});
+
+const send = await bloomsight.sendMail({
+	templateId: '…',
+	engineId: '…',                       // the mailbox to send from
+	data: {name: 'Asha', email: 'asha@example.com', orderId: 'A-1042', lines: [{item: 'Saree', qty: 2}]},
+	idempotencyKey: 'order-A-1042-confirmation',   // optional; one is made for you
+});
+// { id, status: 'queued', missingVariables: [] }
+
+await bloomsight.getSend(send.id);       // queued → sending → sent | failed | unknown
+```
+
+A send is **queued** and goes out within about a second while the mailbox has budget.
+If the mailbox is at its daily limit, it waits and goes when the budget frees.
+
+`unknown` means the connection to the mail provider dropped mid-send, so it cannot be
+known whether it arrived. It is never retried automatically, because a duplicate order
+confirmation is worse than a missing one.
+
+**Pass your own `idempotencyKey`** for anything that must go once: the same key and body
+within 24 hours returns the original send (`replayed: true`); the same key with a
+different body throws `IDEMPOTENCY_CONFLICT`.
+
+## Send to a list
+
+```ts
+const batch = await bloomsight.sendBatch({
+	templateId, engineId, name: 'November offer',
+	recipients: subscribers.map(s => ({data: {email: s.email, name: s.name}})),   // up to 5,000
+});
+
+await bloomsight.getBatch(batch.id);     // progress: queued, sent, failed, …
+await bloomsight.pauseBatch(batch.id);
+await bloomsight.resumeBatch(batch.id);
+await bloomsight.cancelBatch(batch.id);
+```
+
+- Every row is checked first; one bad row refuses the whole batch, and the error's
+  `details.faults` lists the rows at fault.
+- Repeated addresses and addresses on the unsubscribe list are dropped.
+- Batches run at the mailbox's bulk share (70% of its daily limit), across days if
+  needed, so they never use up the budget your transactional email relies on.
+- Every batch email carries a one-click unsubscribe link (`List-Unsubscribe`). Show it
+  in the template too with `{{unsubscribeUrl}}`.
+- Bulk email must be included in the project's Bloomsight plan.
+
+## Unsubscribes and budgets
+
+```ts
+await bloomsight.listUnsubscribes({limit: 100});
+await bloomsight.addUnsubscribe('someone@example.com');      // e.g. opted out on your site
+await bloomsight.removeUnsubscribe('someone@example.com');   // only when they opt back in
+
+await bloomsight.getLimits();   // each mailbox: limits, used today, paused by its provider?
+```
+
+## Errors
+
+```ts
+try {
+	await bloomsight.sendMail({templateId, engineId, data});
+} catch (err) {
+	if (err instanceof BloomsightError) {
+		err.code;            // 'TEMPLATE_NOT_FOUND', 'TEMPLATE_PUBLIC_ONLY', 'INVALID_VARIABLES', …
+		err.status;          // HTTP status, when there was a response
+		err.retryAfter;      // seconds, when blooms.ai said when to try again
+		err.idempotencyKey;  // retry with this to stay safe
+		err.details;         // e.g. { faults } for INVALID_ROWS, { fits } for MONTHLY_LIMIT
+	}
+}
+```
+
+| Code | Meaning |
+|---|---|
+| `INVALID_API_KEY` | The key is missing, revoked or not a Bloomsight key |
+| `KEY_SCOPE` | The key does not list the `bloomsight-email` scope |
+| `TEMPLATE_NOT_FOUND`, `ENGINE_NOT_FOUND` | Not in this key's project |
+| `TEMPLATE_PUBLIC_ONLY` | The template's channel is "Browser forms"; set it to "API only" or "Both" |
+| `INVALID_VARIABLES` | A value name or size is not allowed (100 values, 5,000 characters each, 16 KB in all) |
+| `IDEMPOTENCY_CONFLICT` | The key was used with a different request |
+| `INVALID_ROWS`, `BULK_NOT_IN_PLAN`, `MONTHLY_LIMIT` | Batches |
+| `RATE_LIMITED` | Too many requests; retried for you, thrown when retries run out |
+| `NETWORK_FAILURE`, `TIMEOUT`, `BAD_RESPONSE` | blooms.ai could not be reached or answered oddly, after retries |
+
+## Options
+
+```ts
+new Bloomsight({
+	apiKey,                      // required
+	baseUrl: 'https://z.bloomscorp.com',
+	timeoutMs: 15000,            // per attempt
+	maxRetries: 3,
+	maxRetryWaitMs: 60000,       // a longer Retry-After is thrown, not waited out
+});
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,186 @@
+/**
+ * Request and response types for the Bloomsight email API
+ * (blooms.ai documentation/bloomsight/backend-sending.md §4, §7, §8).
+ */
+/** Template values: text, numbers, true/false, null, and lists/objects of those (up to 4 levels). */
+type TemplateValue = string | number | boolean | null | TemplateValue[] | {
+    [key: string]: TemplateValue;
+};
+type TemplateData = Record<string, TemplateValue>;
+interface BloomsightOptions {
+    /** A project API key with the `bloomsight-email` scope: `blm_live_…` or `blm_test_…`. */
+    apiKey: string;
+    /** Defaults to `https://z.bloomscorp.com`. */
+    baseUrl?: string;
+    /** Per attempt. Default 15 seconds. */
+    timeoutMs?: number;
+    /** Retries after the first attempt, for network errors, 429 and 5xx. Default 3. */
+    maxRetries?: number;
+    /** The longest `Retry-After` the library will wait out by itself. Default 60 seconds. */
+    maxRetryWaitMs?: number;
+    /** A `fetch` to use instead of the global one (tests, proxies). */
+    fetch?: typeof fetch;
+}
+interface SendMailInput {
+    templateId: string;
+    engineId: string;
+    data?: TemplateData;
+    /**
+     * Makes the send safe to repeat: the same key and body returns the original send
+     * for 24 hours. One is generated when you don't pass one; pass your own (for
+     * example `order-A-1042-confirmation`) so even a restarted process cannot send twice.
+     */
+    idempotencyKey?: string;
+}
+type SendStatus = 'queued' | 'paused' | 'sending' | 'sent' | 'failed' | 'unknown' | 'cancelled' | 'test';
+interface Send {
+    id: string;
+    status: SendStatus;
+    templateId?: string;
+    engineId?: string;
+    priority?: 'transactional' | 'bulk';
+    attempts?: number;
+    recipientCount?: number;
+    nextAttemptAt?: string | null;
+    errorCode?: string | null;
+    error?: string | null;
+    createdAt?: string;
+    finishedAt?: string | null;
+    /** True when sent with a `blm_test_…` key: checked, nothing sent. */
+    test?: boolean;
+    /** Template values the template uses that this send did not supply. */
+    missingVariables?: string[];
+    /** True when an Idempotency-Key matched an earlier send and nothing new was queued. */
+    replayed?: boolean;
+}
+interface BatchRecipient {
+    data: TemplateData;
+}
+interface SendBatchInput {
+    templateId: string;
+    engineId: string;
+    name?: string;
+    /** 1 to 5,000 rows. Each row's values follow the `sendMail` rules. */
+    recipients: BatchRecipient[];
+    idempotencyKey?: string;
+}
+interface BatchProgress {
+    queued: number;
+    paused: number;
+    sending: number;
+    sent: number;
+    failed: number;
+    unknown: number;
+    cancelled: number;
+}
+interface Batch {
+    id: string | null;
+    name?: string;
+    status: 'running' | 'paused' | 'cancelled' | 'done' | 'test';
+    templateId?: string;
+    engineId?: string;
+    rows: number;
+    accepted: number;
+    duplicates: number;
+    suppressed: number;
+    progress?: BatchProgress;
+    expectedFinishAt?: string | null;
+    createdAt?: string;
+    cancelledAt?: string | null;
+    test?: boolean;
+    replayed?: boolean;
+}
+interface MailboxLimits {
+    engineId: string;
+    name: string;
+    fromEmail: string;
+    /** `null` = not limited. */
+    limits: {
+        kind: 'workspace' | 'consumer' | 'smtp';
+        perMinute: number | null;
+        perDay: number | null;
+        recipientsPerDay: number | null;
+        uniqueRecipientsPerDay: number | null;
+        publicPerDay: number | null;
+        bulkPerDay: number | null;
+    };
+    used: {
+        minute: number;
+        day: number;
+        recipients: number;
+        unique: number;
+        public: number;
+        bulk: number;
+    };
+    heldForMs: number;
+}
+interface Unsubscribe {
+    address: string;
+    reason: 'unsubscribe' | 'manual' | 'api';
+    createdAt: string;
+}
+
+/** Internal seam for tests: how the client waits between attempts. */
+type Sleep = (ms: number) => Promise<void>;
+declare class Bloomsight {
+    #private;
+    constructor(options: BloomsightOptions);
+    /** True for a `blm_test_…` key: everything is checked and nothing is sent. */
+    get isTestKey(): boolean;
+    /**
+     * Queue one email. It goes out within about a second when the mailbox has
+     * budget; follow it with `getSend(id)`.
+     */
+    sendMail(input: SendMailInput): Promise<Send>;
+    getSend(id: string): Promise<Send>;
+    /** Send one template to many recipients. Checked whole first; one bad row refuses all. */
+    sendBatch(input: SendBatchInput): Promise<Batch>;
+    getBatch(id: string): Promise<Batch>;
+    pauseBatch(id: string): Promise<Batch>;
+    resumeBatch(id: string): Promise<Batch>;
+    /** Stops every email of the batch that has not started. Cannot be undone. */
+    cancelBatch(id: string): Promise<Batch>;
+    getLimits(): Promise<MailboxLimits[]>;
+    listUnsubscribes(options?: {
+        limit?: number;
+        before?: string;
+    }): Promise<Unsubscribe[]>;
+    /** Returns false when the address was already on the list. */
+    addUnsubscribe(address: string): Promise<boolean>;
+    /** Only when the person has opted back in. Returns false when it was not on the list. */
+    removeUnsubscribe(address: string): Promise<boolean>;
+    /** @internal test seam */
+    _setSleep(sleep: Sleep): void;
+}
+
+/**
+ * Every failure is a `BloomsightError`, so callers branch on `code`, never on text.
+ * Server codes pass through unchanged (`TEMPLATE_NOT_FOUND`, `KEY_SCOPE`,
+ * `IDEMPOTENCY_CONFLICT`, `INVALID_ROWS`, …). The library's own:
+ *   INVALID_API_KEY       the key is missing or not a Bloomsight key
+ *   BROWSER_NOT_ALLOWED   constructed in a browser, where the key would leak
+ *   NETWORK_FAILURE       blooms.ai could not be reached, after the retries
+ *   TIMEOUT               an attempt took longer than `timeoutMs`, after the retries
+ *   BAD_RESPONSE          blooms.ai answered with something that is not its JSON
+ */
+declare class BloomsightError extends Error {
+    readonly code: string;
+    /** HTTP status, when the failure came from a response. */
+    readonly status?: number;
+    /** Seconds to wait before trying again, when blooms.ai said so. */
+    readonly retryAfter?: number;
+    /** The Idempotency-Key the request carried: retry with it to stay safe. */
+    readonly idempotencyKey?: string;
+    /** Extra detail from the server, e.g. `faults` for INVALID_ROWS, `fits` for MONTHLY_LIMIT. */
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, extra?: {
+        status?: number;
+        retryAfter?: number;
+        idempotencyKey?: string;
+        details?: Record<string, unknown>;
+    });
+}
+
+declare const VERSION: string;
+
+export { type Batch, type BatchProgress, type BatchRecipient, Bloomsight, BloomsightError, type BloomsightOptions, type MailboxLimits, type Send, type SendBatchInput, type SendMailInput, type SendStatus, type TemplateData, type TemplateValue, type Unsubscribe, VERSION };

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+/**
+ * Request and response types for the Bloomsight email API
+ * (blooms.ai documentation/bloomsight/backend-sending.md §4, §7, §8).
+ */
+/** Template values: text, numbers, true/false, null, and lists/objects of those (up to 4 levels). */
+type TemplateValue = string | number | boolean | null | TemplateValue[] | {
+    [key: string]: TemplateValue;
+};
+type TemplateData = Record<string, TemplateValue>;
+interface BloomsightOptions {
+    /** A project API key with the `bloomsight-email` scope: `blm_live_…` or `blm_test_…`. */
+    apiKey: string;
+    /** Defaults to `https://z.bloomscorp.com`. */
+    baseUrl?: string;
+    /** Per attempt. Default 15 seconds. */
+    timeoutMs?: number;
+    /** Retries after the first attempt, for network errors, 429 and 5xx. Default 3. */
+    maxRetries?: number;
+    /** The longest `Retry-After` the library will wait out by itself. Default 60 seconds. */
+    maxRetryWaitMs?: number;
+    /** A `fetch` to use instead of the global one (tests, proxies). */
+    fetch?: typeof fetch;
+}
+interface SendMailInput {
+    templateId: string;
+    engineId: string;
+    data?: TemplateData;
+    /**
+     * Makes the send safe to repeat: the same key and body returns the original send
+     * for 24 hours. One is generated when you don't pass one; pass your own (for
+     * example `order-A-1042-confirmation`) so even a restarted process cannot send twice.
+     */
+    idempotencyKey?: string;
+}
+type SendStatus = 'queued' | 'paused' | 'sending' | 'sent' | 'failed' | 'unknown' | 'cancelled' | 'test';
+interface Send {
+    id: string;
+    status: SendStatus;
+    templateId?: string;
+    engineId?: string;
+    priority?: 'transactional' | 'bulk';
+    attempts?: number;
+    recipientCount?: number;
+    nextAttemptAt?: string | null;
+    errorCode?: string | null;
+    error?: string | null;
+    createdAt?: string;
+    finishedAt?: string | null;
+    /** True when sent with a `blm_test_…` key: checked, nothing sent. */
+    test?: boolean;
+    /** Template values the template uses that this send did not supply. */
+    missingVariables?: string[];
+    /** True when an Idempotency-Key matched an earlier send and nothing new was queued. */
+    replayed?: boolean;
+}
+interface BatchRecipient {
+    data: TemplateData;
+}
+interface SendBatchInput {
+    templateId: string;
+    engineId: string;
+    name?: string;
+    /** 1 to 5,000 rows. Each row's values follow the `sendMail` rules. */
+    recipients: BatchRecipient[];
+    idempotencyKey?: string;
+}
+interface BatchProgress {
+    queued: number;
+    paused: number;
+    sending: number;
+    sent: number;
+    failed: number;
+    unknown: number;
+    cancelled: number;
+}
+interface Batch {
+    id: string | null;
+    name?: string;
+    status: 'running' | 'paused' | 'cancelled' | 'done' | 'test';
+    templateId?: string;
+    engineId?: string;
+    rows: number;
+    accepted: number;
+    duplicates: number;
+    suppressed: number;
+    progress?: BatchProgress;
+    expectedFinishAt?: string | null;
+    createdAt?: string;
+    cancelledAt?: string | null;
+    test?: boolean;
+    replayed?: boolean;
+}
+interface MailboxLimits {
+    engineId: string;
+    name: string;
+    fromEmail: string;
+    /** `null` = not limited. */
+    limits: {
+        kind: 'workspace' | 'consumer' | 'smtp';
+        perMinute: number | null;
+        perDay: number | null;
+        recipientsPerDay: number | null;
+        uniqueRecipientsPerDay: number | null;
+        publicPerDay: number | null;
+        bulkPerDay: number | null;
+    };
+    used: {
+        minute: number;
+        day: number;
+        recipients: number;
+        unique: number;
+        public: number;
+        bulk: number;
+    };
+    heldForMs: number;
+}
+interface Unsubscribe {
+    address: string;
+    reason: 'unsubscribe' | 'manual' | 'api';
+    createdAt: string;
+}
+
+/** Internal seam for tests: how the client waits between attempts. */
+type Sleep = (ms: number) => Promise<void>;
+declare class Bloomsight {
+    #private;
+    constructor(options: BloomsightOptions);
+    /** True for a `blm_test_…` key: everything is checked and nothing is sent. */
+    get isTestKey(): boolean;
+    /**
+     * Queue one email. It goes out within about a second when the mailbox has
+     * budget; follow it with `getSend(id)`.
+     */
+    sendMail(input: SendMailInput): Promise<Send>;
+    getSend(id: string): Promise<Send>;
+    /** Send one template to many recipients. Checked whole first; one bad row refuses all. */
+    sendBatch(input: SendBatchInput): Promise<Batch>;
+    getBatch(id: string): Promise<Batch>;
+    pauseBatch(id: string): Promise<Batch>;
+    resumeBatch(id: string): Promise<Batch>;
+    /** Stops every email of the batch that has not started. Cannot be undone. */
+    cancelBatch(id: string): Promise<Batch>;
+    getLimits(): Promise<MailboxLimits[]>;
+    listUnsubscribes(options?: {
+        limit?: number;
+        before?: string;
+    }): Promise<Unsubscribe[]>;
+    /** Returns false when the address was already on the list. */
+    addUnsubscribe(address: string): Promise<boolean>;
+    /** Only when the person has opted back in. Returns false when it was not on the list. */
+    removeUnsubscribe(address: string): Promise<boolean>;
+    /** @internal test seam */
+    _setSleep(sleep: Sleep): void;
+}
+
+/**
+ * Every failure is a `BloomsightError`, so callers branch on `code`, never on text.
+ * Server codes pass through unchanged (`TEMPLATE_NOT_FOUND`, `KEY_SCOPE`,
+ * `IDEMPOTENCY_CONFLICT`, `INVALID_ROWS`, …). The library's own:
+ *   INVALID_API_KEY       the key is missing or not a Bloomsight key
+ *   BROWSER_NOT_ALLOWED   constructed in a browser, where the key would leak
+ *   NETWORK_FAILURE       blooms.ai could not be reached, after the retries
+ *   TIMEOUT               an attempt took longer than `timeoutMs`, after the retries
+ *   BAD_RESPONSE          blooms.ai answered with something that is not its JSON
+ */
+declare class BloomsightError extends Error {
+    readonly code: string;
+    /** HTTP status, when the failure came from a response. */
+    readonly status?: number;
+    /** Seconds to wait before trying again, when blooms.ai said so. */
+    readonly retryAfter?: number;
+    /** The Idempotency-Key the request carried: retry with it to stay safe. */
+    readonly idempotencyKey?: string;
+    /** Extra detail from the server, e.g. `faults` for INVALID_ROWS, `fits` for MONTHLY_LIMIT. */
+    readonly details?: Record<string, unknown>;
+    constructor(code: string, message: string, extra?: {
+        status?: number;
+        retryAfter?: number;
+        idempotencyKey?: string;
+        details?: Record<string, unknown>;
+    });
+}
+
+declare const VERSION: string;
+
+export { type Batch, type BatchProgress, type BatchRecipient, Bloomsight, BloomsightError, type BloomsightOptions, type MailboxLimits, type Send, type SendBatchInput, type SendMailInput, type SendStatus, type TemplateData, type TemplateValue, type Unsubscribe, VERSION };

package/dist/index.js

@@ -0,0 +1,241 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Bloomsight: () => Bloomsight,
+  BloomsightError: () => BloomsightError,
+  VERSION: () => VERSION
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_node_crypto = require("crypto");
+
+// src/error.ts
+var BloomsightError = class extends Error {
+  code;
+  /** HTTP status, when the failure came from a response. */
+  status;
+  /** Seconds to wait before trying again, when blooms.ai said so. */
+  retryAfter;
+  /** The Idempotency-Key the request carried: retry with it to stay safe. */
+  idempotencyKey;
+  /** Extra detail from the server, e.g. `faults` for INVALID_ROWS, `fits` for MONTHLY_LIMIT. */
+  details;
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.name = "BloomsightError";
+    this.code = code;
+    this.status = extra.status;
+    this.retryAfter = extra.retryAfter;
+    this.idempotencyKey = extra.idempotencyKey;
+    this.details = extra.details;
+  }
+};
+
+// src/version.ts
+var VERSION = true ? "0.1.0" : "dev";
+
+// src/client.ts
+var DEFAULT_BASE = "https://z.bloomscorp.com";
+var KEY_PATTERN = /^blm_(live|test)_[0-9a-f]{64}$/;
+var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var Bloomsight = class {
+  #apiKey;
+  #base;
+  #timeoutMs;
+  #maxRetries;
+  #maxRetryWaitMs;
+  #fetch;
+  #sleep = realSleep;
+  constructor(options) {
+    if (typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined") {
+      throw new BloomsightError(
+        "BROWSER_NOT_ALLOWED",
+        "@bloomscorp/bloomsight-node runs on servers only: in a browser your API key would be exposed. Use bloomsight.js for browser forms."
+      );
+    }
+    const key = String(options?.apiKey ?? "").trim();
+    if (!KEY_PATTERN.test(key)) {
+      throw new BloomsightError(
+        "INVALID_API_KEY",
+        "apiKey must be a Bloomsight API key (blm_live_\u2026 or blm_test_\u2026). Create one with the bloomsight-email scope in Project Settings \u2192 API keys."
+      );
+    }
+    const f = options.fetch ?? globalThis.fetch;
+    if (typeof f !== "function") {
+      throw new BloomsightError("NO_FETCH", "No fetch is available. Use Node.js 18 or later, or pass `fetch` in the options.");
+    }
+    this.#apiKey = key;
+    this.#base = String(options.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "");
+    this.#timeoutMs = options.timeoutMs ?? 15e3;
+    this.#maxRetries = Math.max(0, options.maxRetries ?? 3);
+    this.#maxRetryWaitMs = options.maxRetryWaitMs ?? 6e4;
+    this.#fetch = f;
+  }
+  /** True for a `blm_test_…` key: everything is checked and nothing is sent. */
+  get isTestKey() {
+    return this.#apiKey.startsWith("blm_test_");
+  }
+  // ── Sending ──────────────────────────────────────────────────────────────
+  /**
+   * Queue one email. It goes out within about a second when the mailbox has
+   * budget; follow it with `getSend(id)`.
+   */
+  async sendMail(input) {
+    const { idempotencyKey, ...body } = input;
+    const { data, headers } = await this.#request({
+      method: "POST",
+      path: "/send",
+      body,
+      idempotencyKey: idempotencyKey ?? (0, import_node_crypto.randomUUID)()
+    });
+    return { ...data, replayed: headers.get("idempotent-replayed") === "true" };
+  }
+  async getSend(id) {
+    return (await this.#request({ method: "GET", path: `/sends/${encodeURIComponent(id)}` })).data;
+  }
+  /** Send one template to many recipients. Checked whole first; one bad row refuses all. */
+  async sendBatch(input) {
+    const { idempotencyKey, ...body } = input;
+    const { data, headers } = await this.#request({
+      method: "POST",
+      path: "/batches",
+      body,
+      idempotencyKey: idempotencyKey ?? (0, import_node_crypto.randomUUID)()
+    });
+    return { ...data, replayed: headers.get("idempotent-replayed") === "true" };
+  }
+  async getBatch(id) {
+    return (await this.#request({ method: "GET", path: `/batches/${encodeURIComponent(id)}` })).data;
+  }
+  async pauseBatch(id) {
+    return (await this.#request({ method: "POST", path: `/batches/${encodeURIComponent(id)}/pause` })).data;
+  }
+  async resumeBatch(id) {
+    return (await this.#request({ method: "POST", path: `/batches/${encodeURIComponent(id)}/resume` })).data;
+  }
+  /** Stops every email of the batch that has not started. Cannot be undone. */
+  async cancelBatch(id) {
+    return (await this.#request({ method: "POST", path: `/batches/${encodeURIComponent(id)}/cancel` })).data;
+  }
+  // ── Budgets and the unsubscribe list ─────────────────────────────────────
+  async getLimits() {
+    return (await this.#request({ method: "GET", path: "/limits" })).data;
+  }
+  async listUnsubscribes(options = {}) {
+    return (await this.#request({ method: "GET", path: "/unsubscribes", query: options })).data;
+  }
+  /** Returns false when the address was already on the list. */
+  async addUnsubscribe(address) {
+    return (await this.#request({ method: "POST", path: "/unsubscribes", body: { address } })).data.added;
+  }
+  /** Only when the person has opted back in. Returns false when it was not on the list. */
+  async removeUnsubscribe(address) {
+    try {
+      return (await this.#request({ method: "DELETE", path: `/unsubscribes/${encodeURIComponent(address)}` })).data.removed;
+    } catch (err) {
+      if (err instanceof BloomsightError && err.code === "NOT_ON_LIST") return false;
+      throw err;
+    }
+  }
+  // ── Transport ────────────────────────────────────────────────────────────
+  /** @internal test seam */
+  _setSleep(sleep) {
+    this.#sleep = sleep;
+  }
+  #redact(text) {
+    return String(text).split(this.#apiKey).join("blm_***");
+  }
+  async #request(req) {
+    const url = new URL(`${this.#base}/api/v1/bloomsight/email${req.path}`);
+    for (const [k, v] of Object.entries(req.query ?? {})) if (v !== void 0 && v !== null && v !== "") url.searchParams.set(k, String(v));
+    const headers = {
+      Authorization: `Bearer ${this.#apiKey}`,
+      Accept: "application/json",
+      "User-Agent": `bloomsight-node/${VERSION}`
+    };
+    if (req.body !== void 0) headers["Content-Type"] = "application/json";
+    if (req.idempotencyKey) headers["Idempotency-Key"] = req.idempotencyKey;
+    const body = req.body === void 0 ? void 0 : JSON.stringify(req.body);
+    const retryable = true;
+    let attempt = 0;
+    for (; ; ) {
+      let response;
+      try {
+        response = await this.#fetch(url, { method: req.method, headers, body, signal: AbortSignal.timeout(this.#timeoutMs) });
+      } catch (cause) {
+        const timedOut = cause?.name === "TimeoutError" || cause?.name === "AbortError";
+        if (retryable && attempt < this.#maxRetries) {
+          await this.#sleep(this.#backoff(attempt++));
+          continue;
+        }
+        throw new BloomsightError(
+          timedOut ? "TIMEOUT" : "NETWORK_FAILURE",
+          this.#redact(`${timedOut ? "blooms.ai did not answer in time" : "could not reach blooms.ai"}: ${cause?.message || cause}`),
+          { idempotencyKey: req.idempotencyKey }
+        );
+      }
+      let parsed = null;
+      try {
+        parsed = await response.json();
+      } catch {
+        parsed = null;
+      }
+      if (response.ok && parsed?.success === true) {
+        return { data: parsed.data, headers: response.headers };
+      }
+      const retryAfter = Number(response.headers.get("retry-after"));
+      const waitMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1e3 : null;
+      if (RETRY_STATUSES.has(response.status) && retryable && attempt < this.#maxRetries && (waitMs === null || waitMs <= this.#maxRetryWaitMs)) {
+        await this.#sleep(waitMs ?? this.#backoff(attempt));
+        attempt++;
+        continue;
+      }
+      if (!parsed || typeof parsed !== "object") {
+        throw new BloomsightError(
+          "BAD_RESPONSE",
+          `blooms.ai answered HTTP ${response.status} without its usual JSON`,
+          { status: response.status, idempotencyKey: req.idempotencyKey }
+        );
+      }
+      const { success, code, message, data, ...rest } = parsed;
+      throw new BloomsightError(code || `HTTP_${response.status}`, this.#redact(message || `request failed (HTTP ${response.status})`), {
+        status: response.status,
+        retryAfter: waitMs === null ? void 0 : retryAfter,
+        idempotencyKey: req.idempotencyKey,
+        details: Object.keys(rest).length ? rest : void 0
+      });
+    }
+  }
+  /** 0.5 s, 1 s, 2 s, 4 s … with up to 25% jitter, capped at 10 s. */
+  #backoff(attempt) {
+    const base = Math.min(1e4, 500 * 2 ** attempt);
+    return Math.round(base * (1 + Math.random() * 0.25));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Bloomsight,
+  BloomsightError,
+  VERSION
+});

package/dist/index.mjs

@@ -0,0 +1,212 @@
+// src/client.ts
+import { randomUUID } from "crypto";
+
+// src/error.ts
+var BloomsightError = class extends Error {
+  code;
+  /** HTTP status, when the failure came from a response. */
+  status;
+  /** Seconds to wait before trying again, when blooms.ai said so. */
+  retryAfter;
+  /** The Idempotency-Key the request carried: retry with it to stay safe. */
+  idempotencyKey;
+  /** Extra detail from the server, e.g. `faults` for INVALID_ROWS, `fits` for MONTHLY_LIMIT. */
+  details;
+  constructor(code, message, extra = {}) {
+    super(message);
+    this.name = "BloomsightError";
+    this.code = code;
+    this.status = extra.status;
+    this.retryAfter = extra.retryAfter;
+    this.idempotencyKey = extra.idempotencyKey;
+    this.details = extra.details;
+  }
+};
+
+// src/version.ts
+var VERSION = true ? "0.1.0" : "dev";
+
+// src/client.ts
+var DEFAULT_BASE = "https://z.bloomscorp.com";
+var KEY_PATTERN = /^blm_(live|test)_[0-9a-f]{64}$/;
+var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var Bloomsight = class {
+  #apiKey;
+  #base;
+  #timeoutMs;
+  #maxRetries;
+  #maxRetryWaitMs;
+  #fetch;
+  #sleep = realSleep;
+  constructor(options) {
+    if (typeof globalThis.window !== "undefined" && typeof globalThis.document !== "undefined") {
+      throw new BloomsightError(
+        "BROWSER_NOT_ALLOWED",
+        "@bloomscorp/bloomsight-node runs on servers only: in a browser your API key would be exposed. Use bloomsight.js for browser forms."
+      );
+    }
+    const key = String(options?.apiKey ?? "").trim();
+    if (!KEY_PATTERN.test(key)) {
+      throw new BloomsightError(
+        "INVALID_API_KEY",
+        "apiKey must be a Bloomsight API key (blm_live_\u2026 or blm_test_\u2026). Create one with the bloomsight-email scope in Project Settings \u2192 API keys."
+      );
+    }
+    const f = options.fetch ?? globalThis.fetch;
+    if (typeof f !== "function") {
+      throw new BloomsightError("NO_FETCH", "No fetch is available. Use Node.js 18 or later, or pass `fetch` in the options.");
+    }
+    this.#apiKey = key;
+    this.#base = String(options.baseUrl ?? DEFAULT_BASE).replace(/\/+$/, "");
+    this.#timeoutMs = options.timeoutMs ?? 15e3;
+    this.#maxRetries = Math.max(0, options.maxRetries ?? 3);
+    this.#maxRetryWaitMs = options.maxRetryWaitMs ?? 6e4;
+    this.#fetch = f;
+  }
+  /** True for a `blm_test_…` key: everything is checked and nothing is sent. */
+  get isTestKey() {
+    return this.#apiKey.startsWith("blm_test_");
+  }
+  // ── Sending ──────────────────────────────────────────────────────────────
+  /**
+   * Queue one email. It goes out within about a second when the mailbox has
+   * budget; follow it with `getSend(id)`.
+   */
+  async sendMail(input) {
+    const { idempotencyKey, ...body } = input;
+    const { data, headers } = await this.#request({
+      method: "POST",
+      path: "/send",
+      body,
+      idempotencyKey: idempotencyKey ?? randomUUID()
+    });
+    return { ...data, replayed: headers.get("idempotent-replayed") === "true" };
+  }
+  async getSend(id) {
+    return (await this.#request({ method: "GET", path: `/sends/${encodeURIComponent(id)}` })).data;
+  }
+  /** Send one template to many recipients. Checked whole first; one bad row refuses all. */
+  async sendBatch(input) {
+    const { idempotencyKey, ...body } = input;
+    const { data, headers } = await this.#request({
+      method: "POST",
+      path: "/batches",
+      body,
+      idempotencyKey: idempotencyKey ?? randomUUID()
+    });
+    return { ...data, replayed: headers.get("idempotent-replayed") === "true" };
+  }
+  async getBatch(id) {
+    return (await this.#request({ method: "GET", path: `/batches/${encodeURIComponent(id)}` })).data;
+  }
+  async pauseBatch(id) {
+    return (await this.#request({ method: "POST", path: `/batches/${encodeURIComponent(id)}/pause` })).data;
+  }
+  async resumeBatch(id) {
+    return (await this.#request({ method: "POST", path: `/batches/${encodeURIComponent(id)}/resume` })).data;
+  }
+  /** Stops every email of the batch that has not started. Cannot be undone. */
+  async cancelBatch(id) {
+    return (await this.#request({ method: "POST", path: `/batches/${encodeURIComponent(id)}/cancel` })).data;
+  }
+  // ── Budgets and the unsubscribe list ─────────────────────────────────────
+  async getLimits() {
+    return (await this.#request({ method: "GET", path: "/limits" })).data;
+  }
+  async listUnsubscribes(options = {}) {
+    return (await this.#request({ method: "GET", path: "/unsubscribes", query: options })).data;
+  }
+  /** Returns false when the address was already on the list. */
+  async addUnsubscribe(address) {
+    return (await this.#request({ method: "POST", path: "/unsubscribes", body: { address } })).data.added;
+  }
+  /** Only when the person has opted back in. Returns false when it was not on the list. */
+  async removeUnsubscribe(address) {
+    try {
+      return (await this.#request({ method: "DELETE", path: `/unsubscribes/${encodeURIComponent(address)}` })).data.removed;
+    } catch (err) {
+      if (err instanceof BloomsightError && err.code === "NOT_ON_LIST") return false;
+      throw err;
+    }
+  }
+  // ── Transport ────────────────────────────────────────────────────────────
+  /** @internal test seam */
+  _setSleep(sleep) {
+    this.#sleep = sleep;
+  }
+  #redact(text) {
+    return String(text).split(this.#apiKey).join("blm_***");
+  }
+  async #request(req) {
+    const url = new URL(`${this.#base}/api/v1/bloomsight/email${req.path}`);
+    for (const [k, v] of Object.entries(req.query ?? {})) if (v !== void 0 && v !== null && v !== "") url.searchParams.set(k, String(v));
+    const headers = {
+      Authorization: `Bearer ${this.#apiKey}`,
+      Accept: "application/json",
+      "User-Agent": `bloomsight-node/${VERSION}`
+    };
+    if (req.body !== void 0) headers["Content-Type"] = "application/json";
+    if (req.idempotencyKey) headers["Idempotency-Key"] = req.idempotencyKey;
+    const body = req.body === void 0 ? void 0 : JSON.stringify(req.body);
+    const retryable = true;
+    let attempt = 0;
+    for (; ; ) {
+      let response;
+      try {
+        response = await this.#fetch(url, { method: req.method, headers, body, signal: AbortSignal.timeout(this.#timeoutMs) });
+      } catch (cause) {
+        const timedOut = cause?.name === "TimeoutError" || cause?.name === "AbortError";
+        if (retryable && attempt < this.#maxRetries) {
+          await this.#sleep(this.#backoff(attempt++));
+          continue;
+        }
+        throw new BloomsightError(
+          timedOut ? "TIMEOUT" : "NETWORK_FAILURE",
+          this.#redact(`${timedOut ? "blooms.ai did not answer in time" : "could not reach blooms.ai"}: ${cause?.message || cause}`),
+          { idempotencyKey: req.idempotencyKey }
+        );
+      }
+      let parsed = null;
+      try {
+        parsed = await response.json();
+      } catch {
+        parsed = null;
+      }
+      if (response.ok && parsed?.success === true) {
+        return { data: parsed.data, headers: response.headers };
+      }
+      const retryAfter = Number(response.headers.get("retry-after"));
+      const waitMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1e3 : null;
+      if (RETRY_STATUSES.has(response.status) && retryable && attempt < this.#maxRetries && (waitMs === null || waitMs <= this.#maxRetryWaitMs)) {
+        await this.#sleep(waitMs ?? this.#backoff(attempt));
+        attempt++;
+        continue;
+      }
+      if (!parsed || typeof parsed !== "object") {
+        throw new BloomsightError(
+          "BAD_RESPONSE",
+          `blooms.ai answered HTTP ${response.status} without its usual JSON`,
+          { status: response.status, idempotencyKey: req.idempotencyKey }
+        );
+      }
+      const { success, code, message, data, ...rest } = parsed;
+      throw new BloomsightError(code || `HTTP_${response.status}`, this.#redact(message || `request failed (HTTP ${response.status})`), {
+        status: response.status,
+        retryAfter: waitMs === null ? void 0 : retryAfter,
+        idempotencyKey: req.idempotencyKey,
+        details: Object.keys(rest).length ? rest : void 0
+      });
+    }
+  }
+  /** 0.5 s, 1 s, 2 s, 4 s … with up to 25% jitter, capped at 10 s. */
+  #backoff(attempt) {
+    const base = Math.min(1e4, 500 * 2 ** attempt);
+    return Math.round(base * (1 + Math.random() * 0.25));
+  }
+};
+export {
+  Bloomsight,
+  BloomsightError,
+  VERSION
+};

package/package.json

@@ -1,10 +1,59 @@
 {
   "name": "@bloomscorp/bloomsight-node",
-  "version": "0.0.1-placeholder.0",
-  "description": "Placeholder that reserves the name. Install the latest version instead.",
+  "version": "0.1.0",
+  "description": "Send Bloomsight email templates from your Node.js backend, safely: idempotent, retried, typed.",
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "lint": "tsc --noEmit",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify:package": "node scripts/verify-package.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "bloomsight",
+    "bloomscorp",
+    "email",
+    "transactional-email",
+    "templates",
+    "node"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "license": "MIT",
   "author": "Bloomscorp",
   "homepage": "https://github.com/bloomscorp/bloomsight-node",
-  "repository": { "type": "git", "url": "https://github.com/bloomscorp/bloomsight-node" },
-  "files": ["README.md"]
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bloomscorp/bloomsight-node"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsup": "^8.1.0",
+    "typescript": "^5.5.0",
+    "vitest": "^1.6.0"
+  }
 }