sadasend 0.0.0-stage → 0.1.0

package/dist/client.js

@@ -0,0 +1,266 @@
+import { ConnectionError, SadaSendError, isRetryable, toError, } from './errors.js';
+import { DEFAULT_RETRY, delayFor, sleep } from './retry.js';
+const VERSION = '0.1.0';
+/**
+ * `process.env`, read without assuming it exists.
+ *
+ * This package runs in Cloudflare Workers, Vercel Edge and the browser, where
+ * there is no `process` at all — and it is compiled without Node or Bun's
+ * ambient types on purpose, so nothing here can quietly depend on a global the
+ * customer's runtime does not have.
+ */
+const env = (name) => globalThis
+    .process?.env?.[name];
+export class SadaSend {
+    #apiKey;
+    #baseUrl;
+    #timeoutMs;
+    #retry;
+    #fetch;
+    #channel;
+    #source;
+    #agentName;
+    constructor(apiKeyOrOptions, options = {}) {
+        const opts = typeof apiKeyOrOptions === 'object' && apiKeyOrOptions !== null
+            ? apiKeyOrOptions
+            : options;
+        const key = (typeof apiKeyOrOptions === 'string' ? apiKeyOrOptions : undefined)
+            ?? opts.apiKey
+            ?? env('SADASEND_API_KEY');
+        if (!key) {
+            throw new Error('No API key. Pass one to `new SadaSend(key)` or set SADASEND_API_KEY. '
+                + 'Keys are created in the dashboard under Keys and shown once.');
+        }
+        this.#apiKey = key;
+        this.#baseUrl = (opts.baseUrl ?? env('SADASEND_BASE_URL') ?? 'https://api.sadasend.com')
+            .replace(/\/+$/, '');
+        this.#timeoutMs = opts.timeoutMs ?? 30_000;
+        this.#retry = { ...DEFAULT_RETRY, ...opts.retry };
+        this.#fetch = opts.fetch ?? globalThis.fetch;
+        this.#channel = opts.channel ?? env('SADASEND_CHANNEL');
+        this.#source = opts.source ?? env('SADASEND_SOURCE');
+        this.#agentName = opts.agentName ?? env('SADASEND_AGENT_NAME');
+    }
+    /**
+     * Send an email.
+     *
+     * ```ts
+     * const r = await sadasend.emails.send({ from, to, subject, html });
+     * if (!r.ok) return console.error(r.error.message);
+     * ```
+     *
+     * `r.status` is `'pending_approval'` when the key is in approval mode — the
+     * message is real and waiting for a person, not lost. Treating that as a
+     * success is correct: the send was accepted.
+     */
+    emails = {
+        send: async (input) => {
+            const { idempotencyKey, channel, source, agentName, agent_name, headers, ...rest } = input;
+            const resolvedChannel = channel ?? this.#channel;
+            const resolvedSource = source ?? this.#source;
+            const resolvedAgent = agentName ?? agent_name ?? this.#agentName;
+            const outgoingHeaders = { ...(headers ?? {}) };
+            if (resolvedAgent)
+                outgoingHeaders['x-sadasend-agent'] = resolvedAgent;
+            if (resolvedSource)
+                outgoingHeaders['x-sadasend-source'] = resolvedSource;
+            const r = await this.#request('POST', '/emails', {
+                headers: outgoingHeaders,
+                body: {
+                    ...rest,
+                    ...(resolvedChannel ? { channel: resolvedChannel } : {}),
+                    ...(resolvedSource ? { source: resolvedSource } : {}),
+                    ...(resolvedAgent ? { agent_name: resolvedAgent } : {}),
+                    to: Array.isArray(rest.to) ? rest.to : [rest.to],
+                    scheduledAt: rest.scheduledAt instanceof Date ? rest.scheduledAt.toISOString() : rest.scheduledAt,
+                },
+                // Generated when absent, which is the point: without one, a retry
+                // after a timeout is a second email to a real person.
+                idempotencyKey: idempotencyKey ?? crypto.randomUUID(),
+            });
+            return r.ok ? { ok: true, ...r.data } : r;
+        },
+        batch: async (items, options = {}) => {
+            const body = {
+                emails: items.map((item) => {
+                    const { idempotencyKey, channel, source, agentName, agent_name, ...rest } = item;
+                    const resolvedChannel = channel ?? this.#channel;
+                    const resolvedSource = source ?? this.#source;
+                    const resolvedAgent = agentName ?? agent_name ?? this.#agentName;
+                    return {
+                        ...rest,
+                        ...(resolvedChannel ? { channel: resolvedChannel } : {}),
+                        ...(resolvedSource ? { source: resolvedSource } : {}),
+                        ...(resolvedAgent ? { agent_name: resolvedAgent } : {}),
+                        to: Array.isArray(rest.to) ? rest.to : [rest.to],
+                        scheduledAt: rest.scheduledAt instanceof Date ? rest.scheduledAt.toISOString() : rest.scheduledAt,
+                    };
+                }),
+            };
+            return this.#request('POST', '/emails/batch', {
+                body,
+                idempotencyKey: options.idempotencyKey ?? crypto.randomUUID(),
+            });
+        },
+        get: async (id) => {
+            const r = await this.#request('GET', `/emails/${encodeURIComponent(id)}`);
+            return r.ok ? { ok: true, data: normalise(r.data) } : r;
+        },
+        resend: (id, options = {}) => this.#request('POST', `/emails/${encodeURIComponent(id)}/resend`, {
+            idempotencyKey: options.idempotencyKey ?? crypto.randomUUID(),
+        }),
+        list: async (params = {}) => {
+            const { agentName, agent_name, ...rest } = params;
+            const r = await this.#request('GET', `/emails${query({ ...rest, ...(agentName || agent_name ? { agent_name: agentName ?? agent_name } : {}) })}`);
+            return r.ok
+                ? { ok: true, data: { ...r.data, messages: r.data.messages.map(normalise) } }
+                : r;
+        },
+        cancel: (id) => this.#request('DELETE', `/emails/${encodeURIComponent(id)}`),
+    };
+    account = {
+        get: () => this.#request('GET', '/account'),
+        stats: (params = {}) => this.#request('GET', `/account/stats${query(params)}`),
+        volume: (params = {}) => this.#request('GET', `/account/volume${query(params)}`),
+        checklist: () => this.#request('GET', '/account/checklist'),
+        circuitBreakers: () => this.#request('GET', '/account/circuit-breakers'),
+        staffAccess: (params = {}) => this.#request('GET', `/account/staff-access${query(params)}`),
+    };
+    domains = {
+        list: () => this.#request('GET', '/domains'),
+        records: (id) => this.#request('GET', `/domains/${encodeURIComponent(id)}/records`),
+        verify: (id) => this.#request('POST', `/domains/${encodeURIComponent(id)}/verify`),
+    };
+    suppressions = {
+        list: (params = {}) => this.#request('GET', `/suppressions${query(params)}`),
+        add: (address, reason = 'manual') => this.#request('POST', '/suppressions', { body: { address, reason } }),
+    };
+    templates = {
+        list: () => this.#request('GET', '/templates'),
+        get: (id) => this.#request('GET', `/templates/${encodeURIComponent(id)}`),
+        render: (id, variables = {}) => this.#request('POST', `/templates/${encodeURIComponent(id)}/render`, { body: { variables } }),
+        test: (id, options) => this.#request('POST', `/templates/${encodeURIComponent(id)}/test`, { body: options }),
+    };
+    keys = {
+        list: () => this.#request('GET', '/keys'),
+        approvals: () => this.#request('GET', '/keys/approvals'),
+    };
+    support = {
+        tickets: (params = {}) => this.#request('GET', `/support/tickets${query(params)}`),
+        ticket: (id) => this.#request('GET', `/support/tickets/${encodeURIComponent(id)}`),
+    };
+    team = {
+        get: () => this.#request('GET', '/team'),
+    };
+    tools = {
+        list: () => this.#request('GET', '/tools'),
+        check: (check, subject, selector) => this.#request('POST', `/tools/${encodeURIComponent(check)}`, { body: { subject, selector } }),
+    };
+    webhooks = {
+        list: () => this.#request('GET', '/webhooks'),
+        deliveries: (id, params = {}) => this.#request('GET', `/webhooks/${encodeURIComponent(id)}/deliveries${query(params)}`),
+    };
+    /* ------------------------------------------------------------ transport */
+    async #request(method, path, opts = {}) {
+        const url = `${this.#baseUrl}${path}`;
+        const headers = {
+            authorization: `Bearer ${this.#apiKey}`,
+            'user-agent': `sadasend-js/${VERSION}`,
+            ...(this.#agentName ? { 'x-sadasend-agent': this.#agentName } : {}),
+            ...(this.#source ? { 'x-sadasend-source': this.#source } : {}),
+            ...(opts.headers ?? {}),
+        };
+        if (opts.body !== undefined)
+            headers['content-type'] = 'application/json';
+        // The same key on every attempt, which is what makes retrying safe. A key
+        // regenerated per attempt is no key at all.
+        if (opts.idempotencyKey)
+            headers['idempotency-key'] = opts.idempotencyKey;
+        const payload = opts.body === undefined ? undefined : JSON.stringify(opts.body);
+        let lastConnectionFault;
+        for (let attempt = 1;; attempt++) {
+            let response;
+            try {
+                response = await this.#fetch(url, {
+                    method,
+                    headers,
+                    body: payload,
+                    signal: AbortSignal.timeout(this.#timeoutMs),
+                });
+            }
+            catch (cause) {
+                /**
+                 * No answer. Retried like a 5xx — with the idempotency key intact, so
+                 * an attempt that did reach the server returns its original result
+                 * instead of sending twice.
+                 */
+                lastConnectionFault = cause;
+                if (attempt > this.#retry.maxRetries) {
+                    throw new ConnectionError(`Could not reach ${this.#baseUrl} after ${attempt} attempt${attempt === 1 ? '' : 's'}.`, cause, attempt);
+                }
+                await sleep(delayFor(attempt, new SadaSendError('connection', 0, ''), this.#retry) ?? 0);
+                continue;
+            }
+            const text = await response.text();
+            const body = parseJson(text);
+            if (response.ok)
+                return { ok: true, data: body };
+            const error = toError(response.status, body, retryAfterSeconds(response));
+            if (!isRetryable(error) || attempt > this.#retry.maxRetries)
+                return { ok: false, error };
+            const wait = delayFor(attempt, error, this.#retry);
+            // `null` means the policy declined — a `Retry-After` longer than we will
+            // block for. The error carries the header, so the caller can schedule it.
+            if (wait === null)
+                return { ok: false, error };
+            await sleep(wait);
+        }
+        // Unreachable; the loop returns or throws. Referenced so a future edit that
+        // breaks out of the loop fails to compile rather than returning undefined.
+        void lastConnectionFault;
+    }
+}
+/**
+ * `to` is a union on the wire: the API returns a bare string for one recipient
+ * and an array for several (`m.to.length === 1 ? m.to[0] : m.to`). The contract
+ * fixed that shape from a UI that only ever renders one, and the dashboard
+ * consumes it as it is — so it is not the SDK's place to change the wire.
+ *
+ * It *is* the SDK's place not to pass the wart on. A union-typed field is a
+ * paper cut at every call site, and the bug it causes is silent: `to[0]` on a
+ * single-recipient message returns `"d"`. Always an array here.
+ */
+function normalise(m) {
+    return { ...m, to: Array.isArray(m.to) ? m.to : [m.to] };
+}
+function parseJson(text) {
+    try {
+        const v = JSON.parse(text);
+        return v !== null && typeof v === 'object' ? v : { value: v };
+    }
+    catch {
+        // A proxy's HTML error page, or an empty 502. Kept so the error message can
+        // show what actually arrived rather than "unexpected token < in JSON".
+        return { error: 'invalid_response', message: text.slice(0, 200) || 'The API returned an empty body.' };
+    }
+}
+function retryAfterSeconds(r) {
+    const raw = r.headers.get('retry-after');
+    if (!raw)
+        return undefined;
+    const n = Number(raw);
+    if (Number.isFinite(n))
+        return n;
+    // The header may also be an HTTP-date. Rare from our API, valid per RFC 9110.
+    const at = Date.parse(raw);
+    return Number.isNaN(at) ? undefined : Math.max(0, Math.ceil((at - Date.now()) / 1000));
+}
+function query(params) {
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(params))
+        if (v !== undefined)
+            q.set(k, String(v));
+    const s = q.toString();
+    return s ? `?${s}` : '';
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/errors.d.ts

@@ -0,0 +1,123 @@
+/**
+ * An error class per failure mode, and every one of them carries the fix.
+ *
+ * The standard is the one the free tools hold themselves to: a message that
+ * says what is wrong and nothing about what to do is a message that generates a
+ * support ticket. `DomainNotVerifiedError` carries the DNS records that are
+ * missing, because the person reading it is about to go and look them up.
+ *
+ * These are **not thrown** for guardrail refusals. A refusal is the product
+ * working — an agent stopped from mailing someone it should not — and throwing
+ * turns the normal case into an exception. They arrive inside the result union,
+ * where `instanceof` narrows them and the compiler makes you handle them.
+ */
+/** The DNS record shape `GET /domains/:id/records` and this error both use. */
+export type DnsRecord = {
+    type: string;
+    host: string;
+    value: string;
+    verdict?: 'pass' | 'fail' | 'pending' | 'inconclusive';
+    note?: string;
+};
+export declare class SadaSendError extends Error {
+    /** The machine-readable code. Stable; the message is not. */
+    readonly code: string;
+    readonly status: number;
+    /** `https://sadasend.com/docs/errors#<code>`, sent by the API. */
+    readonly docs?: string;
+    /** The whole body, for codes newer than this SDK. */
+    readonly body: Record<string, unknown>;
+    constructor(code: string, status: number, message: string, body?: Record<string, unknown>);
+}
+/** The key is not valid, or was revoked. Nothing to retry. */
+export declare class AuthenticationError extends SadaSendError {
+}
+/**
+ * The key has scopes, and `send` is not among them.
+ *
+ * Deliberately not retryable and deliberately not fixable in code: widening a
+ * key is a decision someone makes in the dashboard, on purpose.
+ */
+export declare class InsufficientScopeError extends SadaSendError {
+}
+/** The `from` address did not parse as an email address. */
+export declare class InvalidFromError extends SadaSendError {
+}
+export declare class DomainNotFoundError extends SadaSendError {
+}
+/**
+ * The domain exists but has not passed DNS verification — and the records are
+ * attached, so the fix is in the error rather than a page away.
+ */
+export declare class DomainNotVerifiedError extends SadaSendError {
+    get records(): DnsRecord[];
+}
+/**
+ * The guardrail that makes an agent safe to hand a key to. The allowlist is on
+ * the error because the interesting question is always "what *is* it allowed to
+ * mail, then".
+ */
+export declare class RecipientNotAllowlistedError extends SadaSendError {
+    get recipient(): string | undefined;
+    get allowlist(): string[];
+}
+/**
+ * The address is on the suppression list. The reason carries a judgement the
+ * caller should not make on its own: `unsubscribe` is a person's decision, and
+ * `hard_bounce` is an address that does not exist. Neither is "retry later",
+ * which is why this is not retryable.
+ */
+export declare class RecipientSuppressedError extends SadaSendError {
+    get recipient(): string | undefined;
+    get reason(): 'hard_bounce' | 'complaint' | 'unsubscribe' | 'manual' | undefined;
+}
+/** The same key with a different body. The first request stands. */
+export declare class IdempotencyKeyReusedError extends SadaSendError {
+}
+/**
+ * The first request with this key has not finished. Retrying returns *its*
+ * result rather than sending twice, so this one **is** retryable — and the
+ * client does retry it, which is the whole point of sending the key.
+ */
+export declare class IdempotencyInProgressError extends SadaSendError {
+}
+/**
+ * Rate limited — by this key's own limit, or by the account-wide throttle that
+ * a bounce or complaint rate above the published threshold applies.
+ *
+ * `retryAfterSeconds` comes from the `Retry-After` header the API already
+ * sends. The client waits exactly that long rather than guessing, because a
+ * guess that is too short is what turns a limit into an outage.
+ */
+export declare class RateLimitError extends SadaSendError {
+    readonly retryAfterSeconds?: number;
+    constructor(code: string, status: number, message: string, body: Record<string, unknown>, retryAfterSeconds?: number);
+    /** True when the account is throttled for reputation, not merely over a key limit. */
+    get isAccountThrottle(): boolean;
+}
+/** 5xx, or a body that was not the error envelope. Retryable. */
+export declare class ServerError extends SadaSendError {
+}
+/**
+ * The request never got an answer — DNS, TLS, a dropped socket, a timeout.
+ *
+ * This one **is thrown** rather than returned. It is not the API refusing
+ * anything; it is not knowing whether the API saw the request at all, and that
+ * is a genuinely different situation from a refusal with a reason.
+ */
+export declare class ConnectionError extends Error {
+    readonly cause: unknown;
+    readonly attempts: number;
+    constructor(message: string, cause: unknown, attempts: number);
+}
+export declare function toError(status: number, body: Record<string, unknown>, retryAfterSeconds?: number): SadaSendError;
+/**
+ * What is worth trying again.
+ *
+ * Every guardrail refusal is absent by design: an agent that retries past an
+ * allowlist is an agent that eventually gets through, and a client that retried
+ * `recipient_suppressed` would be automating the one thing the suppression list
+ * exists to stop.
+ */
+export declare function isRetryable(e: SadaSendError): boolean;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,cAAc,CAAC;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,qBAAa,aAAc,SAAQ,KAAK;IACtC,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;gBAE3B,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAQ9F;AAED,8DAA8D;AAC9D,qBAAa,mBAAoB,SAAQ,aAAa;CAAI;AAE1D;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,aAAa;CAAI;AAE7D,4DAA4D;AAC5D,qBAAa,gBAAiB,SAAQ,aAAa;CAAI;AAEvD,qBAAa,mBAAoB,SAAQ,aAAa;CAAI;AAE1D;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,aAAa;IACvD,IAAI,OAAO,IAAI,SAAS,EAAE,CAEzB;CACF;AAED;;;;GAIG;AACH,qBAAa,4BAA6B,SAAQ,aAAa;IAC7D,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAED,IAAI,SAAS,IAAI,MAAM,EAAE,CAExB;CACF;AAED;;;;;GAKG;AACH,qBAAa,wBAAyB,SAAQ,aAAa;IACzD,IAAI,SAAS,IAAI,MAAM,GAAG,SAAS,CAElC;IAED,IAAI,MAAM,IAAI,aAAa,GAAG,WAAW,GAAG,aAAa,GAAG,QAAQ,GAAG,SAAS,CAE/E;CACF;AAED,oEAAoE;AACpE,qBAAa,yBAA0B,SAAQ,aAAa;CAAI;AAEhE;;;;GAIG;AACH,qBAAa,0BAA2B,SAAQ,aAAa;CAAI;AAEjE;;;;;;;GAOG;AACH,qBAAa,cAAe,SAAQ,aAAa;IAC/C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;gBAExB,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,CAAC,EAAE,MAAM;IAMpH,sFAAsF;IACtF,IAAI,iBAAiB,IAAI,OAAO,CAE/B;CACF;AAED,iEAAiE;AACjE,qBAAa,WAAY,SAAQ,aAAa;CAAI;AAElD;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM;CAM9D;AAqBD,wBAAgB,OAAO,CACrB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,iBAAiB,CAAC,EAAE,MAAM,GACzB,aAAa,CAWf;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAIrD"}

package/dist/errors.js

@@ -0,0 +1,176 @@
+/**
+ * An error class per failure mode, and every one of them carries the fix.
+ *
+ * The standard is the one the free tools hold themselves to: a message that
+ * says what is wrong and nothing about what to do is a message that generates a
+ * support ticket. `DomainNotVerifiedError` carries the DNS records that are
+ * missing, because the person reading it is about to go and look them up.
+ *
+ * These are **not thrown** for guardrail refusals. A refusal is the product
+ * working — an agent stopped from mailing someone it should not — and throwing
+ * turns the normal case into an exception. They arrive inside the result union,
+ * where `instanceof` narrows them and the compiler makes you handle them.
+ */
+export class SadaSendError extends Error {
+    /** The machine-readable code. Stable; the message is not. */
+    code;
+    status;
+    /** `https://sadasend.com/docs/errors#<code>`, sent by the API. */
+    docs;
+    /** The whole body, for codes newer than this SDK. */
+    body;
+    constructor(code, status, message, body = {}) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+        this.status = status;
+        this.docs = typeof body.docs === 'string' ? body.docs : undefined;
+        this.body = body;
+    }
+}
+/** The key is not valid, or was revoked. Nothing to retry. */
+export class AuthenticationError extends SadaSendError {
+}
+/**
+ * The key has scopes, and `send` is not among them.
+ *
+ * Deliberately not retryable and deliberately not fixable in code: widening a
+ * key is a decision someone makes in the dashboard, on purpose.
+ */
+export class InsufficientScopeError extends SadaSendError {
+}
+/** The `from` address did not parse as an email address. */
+export class InvalidFromError extends SadaSendError {
+}
+export class DomainNotFoundError extends SadaSendError {
+}
+/**
+ * The domain exists but has not passed DNS verification — and the records are
+ * attached, so the fix is in the error rather than a page away.
+ */
+export class DomainNotVerifiedError extends SadaSendError {
+    get records() {
+        return Array.isArray(this.body.records) ? this.body.records : [];
+    }
+}
+/**
+ * The guardrail that makes an agent safe to hand a key to. The allowlist is on
+ * the error because the interesting question is always "what *is* it allowed to
+ * mail, then".
+ */
+export class RecipientNotAllowlistedError extends SadaSendError {
+    get recipient() {
+        return typeof this.body.recipient === 'string' ? this.body.recipient : undefined;
+    }
+    get allowlist() {
+        return Array.isArray(this.body.allowlist) ? this.body.allowlist : [];
+    }
+}
+/**
+ * The address is on the suppression list. The reason carries a judgement the
+ * caller should not make on its own: `unsubscribe` is a person's decision, and
+ * `hard_bounce` is an address that does not exist. Neither is "retry later",
+ * which is why this is not retryable.
+ */
+export class RecipientSuppressedError extends SadaSendError {
+    get recipient() {
+        return typeof this.body.recipient === 'string' ? this.body.recipient : undefined;
+    }
+    get reason() {
+        return this.body.reason;
+    }
+}
+/** The same key with a different body. The first request stands. */
+export class IdempotencyKeyReusedError extends SadaSendError {
+}
+/**
+ * The first request with this key has not finished. Retrying returns *its*
+ * result rather than sending twice, so this one **is** retryable — and the
+ * client does retry it, which is the whole point of sending the key.
+ */
+export class IdempotencyInProgressError extends SadaSendError {
+}
+/**
+ * Rate limited — by this key's own limit, or by the account-wide throttle that
+ * a bounce or complaint rate above the published threshold applies.
+ *
+ * `retryAfterSeconds` comes from the `Retry-After` header the API already
+ * sends. The client waits exactly that long rather than guessing, because a
+ * guess that is too short is what turns a limit into an outage.
+ */
+export class RateLimitError extends SadaSendError {
+    retryAfterSeconds;
+    constructor(code, status, message, body, retryAfterSeconds) {
+        super(code, status, message, body);
+        this.retryAfterSeconds = retryAfterSeconds
+            ?? (typeof body.retryAfterSeconds === 'number' ? body.retryAfterSeconds : undefined);
+    }
+    /** True when the account is throttled for reputation, not merely over a key limit. */
+    get isAccountThrottle() {
+        return this.code === 'account_throttled';
+    }
+}
+/** 5xx, or a body that was not the error envelope. Retryable. */
+export class ServerError extends SadaSendError {
+}
+/**
+ * The request never got an answer — DNS, TLS, a dropped socket, a timeout.
+ *
+ * This one **is thrown** rather than returned. It is not the API refusing
+ * anything; it is not knowing whether the API saw the request at all, and that
+ * is a genuinely different situation from a refusal with a reason.
+ */
+export class ConnectionError extends Error {
+    cause;
+    attempts;
+    constructor(message, cause, attempts) {
+        super(message);
+        this.name = 'ConnectionError';
+        this.cause = cause;
+        this.attempts = attempts;
+    }
+}
+/**
+ * Codes to classes. A code this SDK has not heard of becomes a plain
+ * `SadaSendError` with the body intact — an SDK a version behind should degrade
+ * to "less specific", never to "throws on parse".
+ */
+const BY_CODE = {
+    missing_api_key: AuthenticationError,
+    invalid_api_key: AuthenticationError,
+    unauthenticated: AuthenticationError,
+    insufficient_scope: InsufficientScopeError,
+    invalid_from: InvalidFromError,
+    domain_not_found: DomainNotFoundError,
+    domain_not_verified: DomainNotVerifiedError,
+    recipient_not_allowlisted: RecipientNotAllowlistedError,
+    recipient_suppressed: RecipientSuppressedError,
+    idempotency_key_reused: IdempotencyKeyReusedError,
+    idempotency_key_in_progress: IdempotencyInProgressError,
+};
+export function toError(status, body, retryAfterSeconds) {
+    const code = typeof body.error === 'string' ? body.error : `http_${status}`;
+    const message = typeof body.message === 'string'
+        ? body.message
+        : `The API returned ${status} with no error message.`;
+    if (status === 429)
+        return new RateLimitError(code, status, message, body, retryAfterSeconds);
+    if (status >= 500)
+        return new ServerError(code, status, message, body);
+    const Cls = BY_CODE[code];
+    return Cls ? new Cls(code, status, message, body) : new SadaSendError(code, status, message, body);
+}
+/**
+ * What is worth trying again.
+ *
+ * Every guardrail refusal is absent by design: an agent that retries past an
+ * allowlist is an agent that eventually gets through, and a client that retried
+ * `recipient_suppressed` would be automating the one thing the suppression list
+ * exists to stop.
+ */
+export function isRetryable(e) {
+    return e instanceof ServerError
+        || e instanceof RateLimitError
+        || e instanceof IdempotencyInProgressError;
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `sadasend` — the SadaSend client.
+ *
+ * Zero dependencies, and deliberately so: this is the one package a customer
+ * installs, and every dependency it carries is one they audit, resolve and
+ * eventually get a CVE notice about. Everything here is `fetch` and WebCrypto,
+ * both of which are in Node 18+, Bun, Deno, Cloudflare Workers and the browser.
+ */
+export { SadaSend } from './client.js';
+export type { AccountChecklist, AccountInfo, AccountStats, AccountVolume, AccountVolumeDay, ApiKeySummary, Attachment, BatchItemResult, BatchResult, ChecklistItem, CircuitBreaker, ClientOptions, DeliverabilityTool, HeldApproval, Message, MessageStatus, Result, SendInput, SendResult, StaffAccess, SupportTicketSummary, TeamMember, TemplateDetail, TemplateSummary, WebhookDelivery, WebhookEndpoint, } from './client.js';
+export { AuthenticationError, ConnectionError, DomainNotFoundError, DomainNotVerifiedError, IdempotencyInProgressError, IdempotencyKeyReusedError, InsufficientScopeError, InvalidFromError, RateLimitError, RecipientNotAllowlistedError, RecipientSuppressedError, SadaSendError, ServerError, isRetryable, } from './errors.js';
+export type { DnsRecord } from './errors.js';
+export { DEFAULT_RETRY } from './retry.js';
+export type { RetryPolicy } from './retry.js';
+export { DEFAULT_TOLERANCE_MS, SIGNATURE_HEADER, parseWebhook, verifyWebhook, } from './webhooks.js';
+export type { VerifyOptions, WebhookEvent, WebhookEventType } from './webhooks.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EACV,gBAAgB,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAC5E,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EACtE,cAAc,EAAE,aAAa,EAAE,kBAAkB,EAAE,YAAY,EAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAClE,oBAAoB,EAAE,UAAU,EAAE,cAAc,EAAE,eAAe,EACjE,eAAe,EAAE,eAAe,GACjC,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EAAE,eAAe,EAAE,mBAAmB,EAAE,sBAAsB,EACjF,0BAA0B,EAAE,yBAAyB,EAAE,sBAAsB,EAC7E,gBAAgB,EAAE,cAAc,EAAE,4BAA4B,EAAE,wBAAwB,EACxF,aAAa,EAAE,WAAW,EAAE,WAAW,GACxC,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC3C,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EACL,oBAAoB,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,GACpE,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * `sadasend` — the SadaSend client.
+ *
+ * Zero dependencies, and deliberately so: this is the one package a customer
+ * installs, and every dependency it carries is one they audit, resolve and
+ * eventually get a CVE notice about. Everything here is `fetch` and WebCrypto,
+ * both of which are in Node 18+, Bun, Deno, Cloudflare Workers and the browser.
+ */
+export { SadaSend } from './client.js';
+export { AuthenticationError, ConnectionError, DomainNotFoundError, DomainNotVerifiedError, IdempotencyInProgressError, IdempotencyKeyReusedError, InsufficientScopeError, InvalidFromError, RateLimitError, RecipientNotAllowlistedError, RecipientSuppressedError, SadaSendError, ServerError, isRetryable, } from './errors.js';
+export { DEFAULT_RETRY } from './retry.js';
+export { DEFAULT_TOLERANCE_MS, SIGNATURE_HEADER, parseWebhook, verifyWebhook, } from './webhooks.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAUvC,OAAO,EACL,mBAAmB,EAAE,eAAe,EAAE,mBAAmB,EAAE,sBAAsB,EACjF,0BAA0B,EAAE,yBAAyB,EAAE,sBAAsB,EAC7E,gBAAgB,EAAE,cAAc,EAAE,4BAA4B,EAAE,wBAAwB,EACxF,aAAa,EAAE,WAAW,EAAE,WAAW,GACxC,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAG3C,OAAO,EACL,oBAAoB,EAAE,gBAAgB,EAAE,YAAY,EAAE,aAAa,GACpE,MAAM,eAAe,CAAC"}