@sendclipper/node 0.0.0-stage → 0.1.0

package/dist/cjs/version.d.ts

@@ -0,0 +1,3 @@
+/** Kept equal to package.json's `version` by `test/version.test.ts`. */
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/cjs/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/cjs/version.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VERSION = void 0;
+/** Kept equal to package.json's `version` by `test/version.test.ts`. */
+exports.VERSION = '0.1.0';
+//# sourceMappingURL=version.js.map

package/dist/cjs/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../src/version.ts"],"names":[],"mappings":";;;AAAA,wEAAwE;AAC3D,QAAA,OAAO,GAAG,OAAO,CAAC"}

package/dist/cjs/webhook-signature.d.ts

@@ -0,0 +1,38 @@
+import type { WebhookEvent } from './types.js';
+/** SendClipper's documented tolerance: five minutes. */
+export declare const WEBHOOK_TOLERANCE_SECONDS = 300;
+export declare const SIGNATURE_HEADER = "x-sendclipper-signature-v2";
+export type HeaderSource = Headers | Record<string, string | string[] | undefined>
+/** Just the `X-SendClipper-Signature-V2` value. */
+ | string;
+export interface VerifyWebhookParams {
+    /** The body EXACTLY as received: a string or the raw bytes. Never re-serialised JSON. */
+    payload: string | Uint8Array;
+    /** The request's headers (Node, Express or Fetch style), or the signature header's value. */
+    headers: HeaderSource;
+    /** The endpoint's `whsec_…` signing secret. */
+    secret: string;
+    /** Default 300. */
+    toleranceSeconds?: number;
+    /** For tests: the current time in seconds. */
+    nowSeconds?: number;
+}
+/**
+ * Verify a webhook delivery and return its parsed event.
+ *
+ * SendClipper signs `${timestamp}.${rawBody}` with HMAC-SHA256 and sends
+ * `X-SendClipper-Signature-V2: t=<seconds>,v1=<hex>[,v1=<hex>]`. During a
+ * secret rotation there are two `v1=` values; any match is accepted.
+ *
+ * @throws WebhookVerificationError when any check fails.
+ */
+export declare function verifyWebhook(params: VerifyWebhookParams): WebhookEvent;
+/** `hex(HMAC-SHA256(secret, `${timestamp}.${rawBody}`))`. Exported for tests of your own handler. */
+export declare function signPayload(secret: string, timestamp: number, rawBody: string): string;
+/** Build a valid header for a body, e.g. to test your endpoint locally. */
+export declare function signatureHeader(secret: string, rawBody: string, timestamp?: number): string;
+export declare function parseSignatureHeader(header: string): {
+    timestamp: number | null;
+    signatures: string[];
+};
+//# sourceMappingURL=webhook-signature.d.ts.map

package/dist/cjs/webhook-signature.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-signature.d.ts","sourceRoot":"","sources":["../../src/webhook-signature.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,wDAAwD;AACxD,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C,eAAO,MAAM,gBAAgB,+BAA+B,CAAC;AAE7D,MAAM,MAAM,YAAY,GACpB,OAAO,GACP,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;AAC/C,mDAAmD;GACjD,MAAM,CAAC;AAEX,MAAM,WAAW,mBAAmB;IAClC,yFAAyF;IACzF,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,6FAA6F;IAC7F,OAAO,EAAE,YAAY,CAAC;IACtB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,YAAY,CA6CvE;AAED,qGAAqG;AACrG,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEtF;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,SAAgC,GAAG,MAAM,CAElH;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,EAAE,CAAA;CAAE,CAWvG"}

package/dist/cjs/webhook-signature.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SIGNATURE_HEADER = exports.WEBHOOK_TOLERANCE_SECONDS = void 0;
+exports.verifyWebhook = verifyWebhook;
+exports.signPayload = signPayload;
+exports.signatureHeader = signatureHeader;
+exports.parseSignatureHeader = parseSignatureHeader;
+const node_crypto_1 = require("node:crypto");
+const errors_js_1 = require("./errors.js");
+/** SendClipper's documented tolerance: five minutes. */
+exports.WEBHOOK_TOLERANCE_SECONDS = 300;
+exports.SIGNATURE_HEADER = 'x-sendclipper-signature-v2';
+/**
+ * Verify a webhook delivery and return its parsed event.
+ *
+ * SendClipper signs `${timestamp}.${rawBody}` with HMAC-SHA256 and sends
+ * `X-SendClipper-Signature-V2: t=<seconds>,v1=<hex>[,v1=<hex>]`. During a
+ * secret rotation there are two `v1=` values; any match is accepted.
+ *
+ * @throws WebhookVerificationError when any check fails.
+ */
+function verifyWebhook(params) {
+    const { secret } = params;
+    if (!secret)
+        throw new errors_js_1.WebhookVerificationError('missing_header', 'No webhook signing secret was given.');
+    if (typeof params.payload !== 'string' && !(params.payload instanceof Uint8Array)) {
+        throw new errors_js_1.WebhookVerificationError('invalid_payload', 'payload must be the raw request body (string or Buffer), not parsed JSON. ' +
+            'With Express use express.raw({ type: "application/json" }) on the webhook route.');
+    }
+    const rawBody = typeof params.payload === 'string' ? params.payload : Buffer.from(params.payload).toString('utf8');
+    const header = signatureHeaderOf(params.headers);
+    if (!header) {
+        throw new errors_js_1.WebhookVerificationError('missing_header', 'The request carries no X-SendClipper-Signature-V2 header.');
+    }
+    const { timestamp, signatures } = parseSignatureHeader(header);
+    if (timestamp === null || signatures.length === 0) {
+        throw new errors_js_1.WebhookVerificationError('malformed_header', 'X-SendClipper-Signature-V2 has no t= or no v1= value.');
+    }
+    const tolerance = params.toleranceSeconds ?? exports.WEBHOOK_TOLERANCE_SECONDS;
+    const now = params.nowSeconds ?? Math.floor(Date.now() / 1000);
+    if (Math.abs(now - timestamp) > tolerance) {
+        throw new errors_js_1.WebhookVerificationError('timestamp_out_of_tolerance', `The delivery was signed ${Math.abs(now - timestamp)} s from now, outside the ${tolerance} s tolerance.`);
+    }
+    const expected = signPayload(secret, timestamp, rawBody);
+    // ANY match, and every candidate is compared: a rotation sends two.
+    let matched = false;
+    for (const candidate of signatures) {
+        if (constantTimeEquals(expected, candidate))
+            matched = true;
+    }
+    if (!matched) {
+        throw new errors_js_1.WebhookVerificationError('signature_mismatch', 'The signature does not match this secret and body.');
+    }
+    try {
+        return JSON.parse(rawBody);
+    }
+    catch {
+        throw new errors_js_1.WebhookVerificationError('invalid_payload', 'The signed body is not JSON.');
+    }
+}
+/** `hex(HMAC-SHA256(secret, `${timestamp}.${rawBody}`))`. Exported for tests of your own handler. */
+function signPayload(secret, timestamp, rawBody) {
+    return (0, node_crypto_1.createHmac)('sha256', secret).update(`${timestamp}.${rawBody}`, 'utf8').digest('hex');
+}
+/** Build a valid header for a body, e.g. to test your endpoint locally. */
+function signatureHeader(secret, rawBody, timestamp = Math.floor(Date.now() / 1000)) {
+    return `t=${timestamp},v1=${signPayload(secret, timestamp, rawBody)}`;
+}
+function parseSignatureHeader(header) {
+    const result = { timestamp: null, signatures: [] };
+    for (const part of header.split(',')) {
+        const eq = part.indexOf('=');
+        if (eq < 0)
+            continue;
+        const key = part.slice(0, eq).trim();
+        const value = part.slice(eq + 1).trim();
+        if (key === 't' && /^\d+$/.test(value))
+            result.timestamp = Number(value);
+        else if (key === 'v1' && value)
+            result.signatures.push(value);
+    }
+    return result;
+}
+function signatureHeaderOf(source) {
+    if (typeof source === 'string')
+        return source;
+    if (typeof source.get === 'function')
+        return source.get(exports.SIGNATURE_HEADER) ?? undefined;
+    for (const [k, v] of Object.entries(source)) {
+        if (k.toLowerCase() === exports.SIGNATURE_HEADER)
+            return Array.isArray(v) ? v.join(',') : v;
+    }
+    return undefined;
+}
+function constantTimeEquals(a, b) {
+    const left = Buffer.from(a, 'utf8');
+    const right = Buffer.from(b, 'utf8');
+    if (left.length !== right.length)
+        return false;
+    return (0, node_crypto_1.timingSafeEqual)(left, right);
+}
+//# sourceMappingURL=webhook-signature.js.map

package/dist/cjs/webhook-signature.js.map

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

package/dist/esm/core.d.ts

@@ -0,0 +1,95 @@
+export declare const DEFAULT_BASE_URL = "https://sendclipper.com";
+export interface ClientOptions {
+    /** Defaults to `process.env.SENDCLIPPER_API_KEY`. A `sc_live_…` key. */
+    apiKey?: string;
+    /** Defaults to `process.env.SENDCLIPPER_BASE_URL`, then `https://sendclipper.com`. No `/v1`. */
+    baseUrl?: string;
+    /** Per attempt, in milliseconds. Default 30 000. */
+    timeoutMs?: number;
+    /**
+     * Retries after a network error, a 429 or a 5xx. Default 2. A mutation is
+     * only retried when it carries an `Idempotency-Key`, which the SDK adds to
+     * every JSON mutation, so a retried send can never go out twice.
+     */
+    maxRetries?: number;
+    /** Your own `fetch` (a proxy agent, a test double). Defaults to the global one. */
+    fetch?: typeof fetch;
+    /** Sent on every request. */
+    defaultHeaders?: Record<string, string>;
+}
+/** What an API refusal or a network failure looks like. */
+export interface ErrorResponse {
+    /** SendClipper's machine-readable code: `domain_not_verified`, `validation_failed`, `rate_limited`, `network_error`, … */
+    name: string;
+    /** A sentence meant for a person. */
+    message: string;
+    /** The HTTP status, or `null` when no answer arrived (network, timeout, abort). */
+    statusCode: number | null;
+    /** Extra, code-specific facts (e.g. the missing template tags). */
+    detail?: unknown;
+}
+/** Every API method resolves to this. Exactly one of `data` and `error` is set. */
+export type Result<T> = ({
+    data: T;
+    error: null;
+} | {
+    data: null;
+    error: ErrorResponse;
+}) & {
+    headers: Record<string, string> | null;
+};
+export type Query = Record<string, string | number | boolean | undefined | null>;
+export interface RequestOptions {
+    /** Your own key, reused when YOU retry the same logical call later. */
+    idempotencyKey?: string;
+    /** Override the client's timeout for this call. */
+    timeoutMs?: number;
+    /** Override the client's retry count for this call. */
+    maxRetries?: number;
+    /** Abort the call from outside. */
+    signal?: AbortSignal;
+    /** Extra headers for this call. */
+    headers?: Record<string, string>;
+}
+/** What a download resolves to. */
+export interface DownloadedFile {
+    bytes: Uint8Array;
+    contentType: string | null;
+    filename: string | null;
+}
+interface InternalRequest extends RequestOptions {
+    method: string;
+    path: string;
+    query?: Query;
+    body?: unknown;
+    form?: FormData;
+    as?: 'json' | 'text' | 'bytes';
+    /** Replaces the API key (the sandbox JSON door takes an `sc_sbx_` token). */
+    bearer?: string;
+}
+export declare class HttpClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly timeoutMs;
+    private readonly maxRetries;
+    private readonly fetchImpl;
+    private readonly defaultHeaders;
+    constructor(opts?: ClientOptions);
+    /**
+     * The public face of every API method: never throws for an API refusal or
+     * a network failure, it answers `{ data, error, headers }`.
+     */
+    call<T>(req: InternalRequest): Promise<Result<T>>;
+    /** Like `call()`, but throws `SendClipperApiError` / `SendClipperConnectionError`. */
+    request<T>(req: InternalRequest): Promise<{
+        data: T;
+        headers: Record<string, string>;
+    }>;
+    private fetchOnce;
+}
+/** `encodeURIComponent` for one path segment. */
+export declare function seg(value: string): string;
+/** Turn a `Result` back into a value, throwing its error. Used by the iterators. */
+export declare function unwrap<T>(res: Result<T>): T;
+export {};
+//# sourceMappingURL=core.d.ts.map

package/dist/esm/core.d.ts.map

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

package/dist/esm/core.js

@@ -0,0 +1,225 @@
+import { randomUUID } from 'node:crypto';
+import { SendClipperApiError, SendClipperConnectionError, toApiError } from './errors.js';
+import { VERSION } from './version.js';
+export const DEFAULT_BASE_URL = 'https://sendclipper.com';
+const RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);
+const MAX_RETRY_AFTER_MS = 60_000;
+export class HttpClient {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    maxRetries;
+    fetchImpl;
+    defaultHeaders;
+    constructor(opts = {}) {
+        const env = typeof process !== 'undefined' ? process.env : {};
+        this.apiKey = opts.apiKey ?? env.SENDCLIPPER_API_KEY;
+        this.baseUrl = (opts.baseUrl ?? env.SENDCLIPPER_BASE_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, '').replace(/\/v1$/, '');
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        this.maxRetries = Math.max(0, opts.maxRetries ?? 2);
+        const f = opts.fetch ?? globalThis.fetch;
+        if (typeof f !== 'function') {
+            throw new Error('@sendclipper/node needs a global fetch (Node.js 18 or newer) or a `fetch` option.');
+        }
+        this.fetchImpl = f;
+        this.defaultHeaders = opts.defaultHeaders ?? {};
+    }
+    /**
+     * The public face of every API method: never throws for an API refusal or
+     * a network failure, it answers `{ data, error, headers }`.
+     */
+    async call(req) {
+        try {
+            const { data, headers } = await this.request(req);
+            return { data, error: null, headers };
+        }
+        catch (err) {
+            if (err instanceof SendClipperApiError) {
+                return { data: null, error: errorResponseOf(err), headers: err.headers ? headersOf(err.headers) : null };
+            }
+            if (err instanceof SendClipperConnectionError) {
+                return { data: null, error: { name: 'network_error', message: err.message, statusCode: null }, headers: null };
+            }
+            if (req.signal?.aborted) {
+                return {
+                    data: null,
+                    error: { name: 'network_error', message: 'The request was aborted.', statusCode: null },
+                    headers: null,
+                };
+            }
+            throw err;
+        }
+    }
+    /** Like `call()`, but throws `SendClipperApiError` / `SendClipperConnectionError`. */
+    async request(req) {
+        const bearer = req.bearer ?? this.apiKey;
+        if (!bearer) {
+            throw new SendClipperApiError(401, 'api_key_missing', 'No SendClipper API key. Pass one to `new SendClipper("sc_live_…")` or set SENDCLIPPER_API_KEY.');
+        }
+        const url = new URL(`${this.baseUrl}/v1${req.path.startsWith('/') ? req.path : `/${req.path}`}`);
+        for (const [k, v] of Object.entries(req.query ?? {})) {
+            if (v !== undefined && v !== null && v !== '')
+                url.searchParams.set(k, String(v));
+        }
+        const headers = {
+            Authorization: `Bearer ${bearer}`,
+            Accept: req.as === 'json' || !req.as ? 'application/json' : '*/*',
+            'User-Agent': `sendclipper-node/${VERSION}`,
+            ...this.defaultHeaders,
+            ...(req.headers ?? {}),
+        };
+        let body;
+        if (req.form) {
+            body = req.form;
+        }
+        else if (req.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            body = JSON.stringify(req.body);
+        }
+        const isRead = req.method === 'GET' || req.method === 'HEAD';
+        // The API de-duplicates every JSON mutation on this header for 24 hours.
+        // A multipart body is not fingerprinted server-side, so it gets no key and
+        // is never retried.
+        if (!isRead && !req.form) {
+            headers['Idempotency-Key'] = req.idempotencyKey ?? `sc-node-${randomUUID()}`;
+        }
+        else if (req.idempotencyKey) {
+            headers['Idempotency-Key'] = req.idempotencyKey;
+        }
+        const canRetry = isRead || Boolean(headers['Idempotency-Key']);
+        const maxRetries = canRetry ? Math.max(0, req.maxRetries ?? this.maxRetries) : 0;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.fetchOnce(url, req.method, headers, body, req.timeoutMs ?? this.timeoutMs, req.signal);
+            }
+            catch (err) {
+                if (req.signal?.aborted)
+                    throw err;
+                if (attempt < maxRetries) {
+                    await sleep(backoffMs(attempt));
+                    continue;
+                }
+                throw err;
+            }
+            if (!res.ok && RETRYABLE_STATUS.has(res.status) && attempt < maxRetries) {
+                await res.body?.cancel().catch(() => undefined);
+                await sleep(retryAfterMs(res.headers) ?? backoffMs(attempt));
+                continue;
+            }
+            if (!res.ok) {
+                const err = toApiError(res.status, await res.text(), res.headers);
+                // Our own earlier attempt is still running server-side (a timeout
+                // that was not a failure). Its result is replayed once it finishes.
+                if (err.code === 'idempotency_key_in_flight' && attempt < maxRetries) {
+                    await sleep(retryAfterMs(res.headers) ?? backoffMs(attempt));
+                    continue;
+                }
+                throw err;
+            }
+            const responseHeaders = headersOf(res.headers);
+            if (req.as === 'bytes') {
+                const file = {
+                    bytes: new Uint8Array(await res.arrayBuffer()),
+                    contentType: res.headers.get('content-type'),
+                    filename: filenameOf(res.headers.get('content-disposition')),
+                };
+                return { data: file, headers: responseHeaders };
+            }
+            const text = await res.text();
+            if (req.as === 'text' || !text)
+                return { data: (req.as === 'text' ? text : null), headers: responseHeaders };
+            try {
+                return { data: JSON.parse(text), headers: responseHeaders };
+            }
+            catch {
+                return { data: text, headers: responseHeaders };
+            }
+        }
+    }
+    async fetchOnce(url, method, headers, body, timeoutMs, outer) {
+        const ctrl = new AbortController();
+        const onAbort = () => ctrl.abort(outer?.reason);
+        if (outer) {
+            if (outer.aborted)
+                ctrl.abort(outer.reason);
+            else
+                outer.addEventListener('abort', onAbort, { once: true });
+        }
+        const timer = setTimeout(() => ctrl.abort(new Error('timeout')), timeoutMs);
+        try {
+            return await this.fetchImpl(url, { method, headers, body, signal: ctrl.signal });
+        }
+        catch (err) {
+            if (outer?.aborted)
+                throw err;
+            const timedOut = ctrl.signal.aborted;
+            throw new SendClipperConnectionError(timedOut
+                ? `SendClipper did not answer within ${timeoutMs} ms (${method} ${url.pathname}).`
+                : `Could not reach SendClipper at ${this.baseUrl}: ${err.message}`, err);
+        }
+        finally {
+            clearTimeout(timer);
+            outer?.removeEventListener('abort', onAbort);
+        }
+    }
+}
+function backoffMs(attempt) {
+    const base = Math.min(8_000, 500 * 2 ** attempt);
+    return base / 2 + Math.random() * (base / 2);
+}
+function retryAfterMs(headers) {
+    const raw = headers.get('retry-after');
+    if (!raw)
+        return undefined;
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.min(MAX_RETRY_AFTER_MS, seconds * 1000);
+    const at = Date.parse(raw);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.min(MAX_RETRY_AFTER_MS, Math.max(0, at - Date.now()));
+}
+function filenameOf(disposition) {
+    if (!disposition)
+        return null;
+    const star = /filename\*\s*=\s*(?:UTF-8'')?([^;]+)/i.exec(disposition);
+    if (star?.[1]) {
+        try {
+            return decodeURIComponent(star[1].trim().replace(/^"|"$/g, ''));
+        }
+        catch {
+            /* fall through to the plain form */
+        }
+    }
+    const plain = /filename\s*=\s*"?([^";]+)"?/i.exec(disposition);
+    return plain?.[1]?.trim() ?? null;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** `encodeURIComponent` for one path segment. */
+export function seg(value) {
+    return encodeURIComponent(value);
+}
+function headersOf(h) {
+    const out = {};
+    h.forEach((value, key) => {
+        out[key] = value;
+    });
+    return out;
+}
+function errorResponseOf(err) {
+    const e = { name: err.code, message: err.message, statusCode: err.status };
+    if (err.detail !== undefined)
+        e.detail = err.detail;
+    return e;
+}
+/** Turn a `Result` back into a value, throwing its error. Used by the iterators. */
+export function unwrap(res) {
+    if (res.error) {
+        throw new SendClipperApiError(res.error.statusCode ?? 0, res.error.name, res.error.message, res.error.detail);
+    }
+    return res.data;
+}
+//# sourceMappingURL=core.js.map

package/dist/esm/core.js.map

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

package/dist/esm/errors.d.ts

@@ -0,0 +1,34 @@
+/** Base class for everything this SDK throws on purpose. */
+export declare class SendClipperError extends Error {
+    constructor(message: string);
+}
+/**
+ * The API answered with a non-2xx status. `code` is the API's own
+ * machine-readable reason (`domain_not_verified`, `template_variables_missing`,
+ * `rate_limited`, …) and is the field to branch on; `message` is a sentence
+ * meant for a person.
+ */
+export declare class SendClipperApiError extends SendClipperError {
+    readonly status: number;
+    readonly code: string;
+    readonly detail?: unknown | undefined;
+    readonly headers?: Headers | undefined;
+    constructor(status: number, code: string, message: string, detail?: unknown | undefined, headers?: Headers | undefined);
+}
+/** The request never got an answer: DNS, TLS, a reset socket or the timeout. */
+export declare class SendClipperConnectionError extends SendClipperError {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** `webhooks.verify()` refused a delivery. `reason` says which check failed. */
+export declare class WebhookVerificationError extends SendClipperError {
+    readonly reason: 'missing_header' | 'malformed_header' | 'timestamp_out_of_tolerance' | 'signature_mismatch' | 'invalid_payload';
+    constructor(reason: 'missing_header' | 'malformed_header' | 'timestamp_out_of_tolerance' | 'signature_mismatch' | 'invalid_payload', message: string);
+}
+/**
+ * The API answers refusals in two shapes: the house envelope
+ * `{ error: { code, message, detail? } }` and Nest's default
+ * `{ statusCode, message: string | string[], error }` (request validation).
+ */
+export declare function toApiError(status: number, text: string, headers?: Headers): SendClipperApiError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/esm/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,qBAAa,gBAAiB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,gBAAgB;IAErD,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAErB,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO;IACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO;gBAJjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACN,MAAM,CAAC,EAAE,OAAO,YAAA,EAChB,OAAO,CAAC,EAAE,OAAO,YAAA;CAK7B;AAED,gFAAgF;AAChF,qBAAa,0BAA2B,SAAQ,gBAAgB;IAG5D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBADxB,OAAO,EAAE,MAAM,EACN,KAAK,CAAC,EAAE,OAAO,YAAA;CAK3B;AAED,gFAAgF;AAChF,qBAAa,wBAAyB,SAAQ,gBAAgB;IAE1D,QAAQ,CAAC,MAAM,EACX,gBAAgB,GAChB,kBAAkB,GAClB,4BAA4B,GAC5B,oBAAoB,GACpB,iBAAiB;gBALZ,MAAM,EACX,gBAAgB,GAChB,kBAAkB,GAClB,4BAA4B,GAC5B,oBAAoB,GACpB,iBAAiB,EACrB,OAAO,EAAE,MAAM;CAKlB;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,mBAAmB,CAyC/F"}