@builtbyecho/reverbin 0.1.0

package/LICENSE

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

@@ -0,0 +1,166 @@
+# @builtbyecho/reverbin
+
+Zero-dependency Node.js ESM SDK for the Reverbin API: agent inboxes, threads, messages, approvals, signed webhooks, API keys, billing, and account lifecycle operations.
+
+## Install
+
+Install the public Node.js package from npm:
+
+```sh
+npm install @builtbyecho/reverbin
+```
+
+The SDK requires Node.js 20 or newer, uses Node's built-in `fetch`, and supports ESM imports only. Browser runtimes are not supported; never put a Reverbin API key in client-side code.
+
+## Authenticated client
+
+```js
+import { ReverbinClient } from '@builtbyecho/reverbin';
+
+const apiKey = process.env.REVERBIN_API_KEY;
+const inboxId = process.env.REVERBIN_INBOX_ID;
+if (!apiKey || !inboxId) throw new Error('REVERBIN_API_KEY and REVERBIN_INBOX_ID are required');
+
+const reverbin = new ReverbinClient({
+  baseUrl: process.env.REVERBIN_BASE_URL ?? 'https://api.reverbin.com',
+  apiKey,
+  timeoutMs: 30_000,
+});
+
+const threads = await reverbin.inboxes.threads(inboxId);
+const latest = threads.data[0];
+if (latest) {
+  await reverbin.threads.reply(latest.id, {
+    text: 'Received — I am handling this from the agent workflow.',
+  });
+}
+```
+
+Signup already creates the first inbox. Use the returned `REVERBIN_INBOX_ID`; call `reverbin.inboxes.create` only when the workflow needs another inbox and the account has quota.
+
+## Self-serve signup
+
+The public signup method does not require an API key. It does require a stable caller-owned idempotency key:
+
+```js
+import { randomUUID } from 'node:crypto';
+import { ReverbinClient } from '@builtbyecho/reverbin';
+
+const reverbin = new ReverbinClient();
+const result = await reverbin.signups.create({
+  idempotency_key: randomUUID(),
+  requester_email: 'builder@example.com',
+  agent_name: 'Support Agent',
+  agent_use_case: 'Handle customer support replies and escalate unusual requests.',
+  preferred_inbox_name: 'support-agent',
+});
+
+if (result.credentials_returned) {
+  // Store result.api_key.token now; it is returned once.
+  console.log(result.inbox.email_address);
+} else {
+  // Safe replay: identifiers and a recovery message, but no credentials.
+  console.log(result.message);
+}
+```
+
+Keep the original idempotency key with the request outcome. Reuse it only with the identical request body after a lost response.
+
+## Core method groups
+
+| Group | Methods |
+| --- | --- |
+| `signups` | `create` |
+| `inboxes` | `create`, `list`, `get`, `threads` |
+| `messages` | `compose`, `list` |
+| `threads` | `get`, `messages`, `reply`, `forward` |
+| `approvals` | `list`, `approve`, `reject` |
+| `webhooks` | `create`, `list`, `deliveries`, `rotateSecret`, `revoke` |
+| `apiKeys` | `create`, `list`, `rotate`, `revoke` |
+| `billing` | `plans`, `checkout`, `portal` |
+| `account` | `export`, `requestDeletion`, `cancelDeletion` |
+| `auditLogs` | `list` |
+| `signupRequests` | `create`, `list`, `update` for legacy operator-assisted workflows |
+
+See https://reverbin.com/docs/api for request and response contracts.
+
+## Pagination
+
+Collection methods return `{ data, next_cursor, has_more }`. Pass `next_cursor` back unchanged as `cursor` to the same method and parent resource:
+
+```js
+const first = await reverbin.inboxes.list({ limit: 25 });
+const second = first.has_more
+  ? await reverbin.inboxes.list({ limit: 25, cursor: first.next_cursor })
+  : null;
+```
+
+Cursors are opaque and tenant-, collection-, and parent-bound.
+
+## Timeouts, aborts, and errors
+
+Requests time out after 30 seconds by default. Configure `timeoutMs` on the client or per request, and pass a caller `AbortSignal` in method request options. The client does not retry requests automatically.
+
+```js
+import {
+  ReverbinApiError,
+  ReverbinClient,
+  ReverbinResponseError,
+  ReverbinTimeoutError,
+} from '@builtbyecho/reverbin';
+
+const controller = new AbortController();
+try {
+  await reverbin.inboxes.list(undefined, {
+    signal: controller.signal,
+    timeoutMs: 5_000,
+  });
+} catch (error) {
+  if (error instanceof ReverbinApiError) {
+    console.error(error.status, error.code, error.requestId, error.retryAfterSeconds, error.quota);
+  } else if (error instanceof ReverbinTimeoutError) {
+    console.error('Timed out after', error.timeoutMs);
+  } else if (error instanceof ReverbinResponseError) {
+    console.error('Malformed API response', error.status, error.requestId);
+  }
+}
+```
+
+API error details are recursively credential-redacted. Even so, do not log one-time signup, API-key, or webhook-secret responses.
+
+## Webhook signatures
+
+Register only a real reachable HTTPS endpoint, then store the returned secret immediately:
+
+```js
+const webhookUrl = process.env.REVERBIN_WEBHOOK_URL;
+if (!webhookUrl) throw new Error('REVERBIN_WEBHOOK_URL is required');
+
+const webhook = await reverbin.webhooks.create({
+  url: webhookUrl,
+  events: ['email.received', 'email.sent', 'email.failed'],
+});
+// Store webhook.secret now; it is returned once.
+```
+
+Verify the signature against the exact raw request bytes before parsing or acting on a webhook:
+
+```js
+import { verifyWebhookSignature } from '@builtbyecho/reverbin/webhook-signatures';
+
+const valid = verifyWebhookSignature(rawBody, signatureHeader, webhookSecret);
+```
+
+During credential-rotation grace, verify `x-echo-email-signature-previous` separately with the previous secret. The stable `x-echo-email-*` header prefix is retained for wire compatibility.
+
+## Retry and idempotency boundaries
+
+The SDK never retries automatically.
+
+- Signup, Stripe Checkout/Portal, API-key rotation, and webhook-secret rotation require explicit `idempotency_key` inputs. Reuse the same key only with the identical body after a lost response.
+- Do not blindly retry compose, reply, forward, approval decisions, inbox creation, webhook creation/revocation, API-key creation/revocation, or account mutations after an ambiguous response. Inspect resource, thread, audit, or delivery state first.
+- Signup replay prevents duplicate provisioning but intentionally omits one-time credentials.
+
+## Launch limitations
+
+Outbound attachments are not supported in the launch SDK. Compose, reply, and forward accept text plus optional HTML. Inbound attachments remain available in the authenticated human mail console.

package/dist/client.d.ts

@@ -0,0 +1,428 @@
+export declare const REVERBIN_DEFAULT_BASE_URL = "https://api.reverbin.com";
+export declare const REVERBIN_DEFAULT_TIMEOUT_MS = 30000;
+export declare const REVERBIN_MAX_TIMEOUT_MS = 120000;
+export type ReverbinClientOptions = {
+    baseUrl?: string;
+    apiKey?: string;
+    fetch?: typeof globalThis.fetch;
+    timeoutMs?: number;
+};
+export type RequestOptions = {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+export type PageOptions = {
+    limit?: number;
+    cursor?: string;
+};
+export type ListResponse<T> = {
+    data: T[];
+    next_cursor: string | null;
+    has_more: boolean;
+};
+export type DataResponse<T> = {
+    data: T[];
+};
+export type ReverbinPolicy = {
+    reply_only?: boolean;
+    require_approval_for_new_recipients?: boolean;
+    require_approval_for_external_domains?: boolean;
+    max_outbound_per_hour?: number;
+    max_outbound_per_day?: number;
+    allowed_domains?: string[];
+    blocked_domains?: string[];
+    allowed_recipients?: string[];
+    blocked_recipients?: string[];
+    allow_attachments?: boolean;
+    allow_links?: boolean;
+    risk_threshold?: 'low' | 'medium' | 'high';
+};
+export type CreateInboxInput = {
+    email_address: string;
+    display_name?: string;
+    agent_id?: string;
+    policy?: ReverbinPolicy;
+};
+export type Inbox = {
+    id: string;
+    email_address: string;
+    display_name?: string | null;
+    status?: string;
+    policy?: ReverbinPolicy;
+    created_at?: string;
+    updated_at?: string;
+    [key: string]: unknown;
+};
+export type MessageDeliveryStatus = 'received' | 'queued' | 'sending' | 'sent' | 'failed' | 'delayed' | 'delivered' | 'bounced' | 'complained';
+export type Message = {
+    id: string;
+    inbox_id?: string;
+    thread_id?: string;
+    direction: 'inbound' | 'outbound';
+    delivery_status?: MessageDeliveryStatus;
+    from_email?: string;
+    from_name?: string | null;
+    to_json?: string[];
+    cc_json?: string[];
+    bcc_json?: string[];
+    subject: string;
+    text_body?: string;
+    html_body?: string | null;
+    created_at?: string;
+    sent_at?: string | null;
+    received_at?: string | null;
+    [key: string]: unknown;
+};
+export type Thread = {
+    id: string;
+    inbox_id: string;
+    subject: string;
+    last_message_at?: string;
+    created_at?: string;
+    updated_at?: string;
+    [key: string]: unknown;
+};
+export type ThreadDetail = Thread & {
+    messages: Message[];
+    messages_next_cursor: string | null;
+    messages_has_more: boolean;
+};
+export type ReplyInput = {
+    to?: string[];
+    subject?: string;
+    text: string;
+    html?: string | null;
+};
+export type ComposeInput = {
+    inbox_id: string;
+    to: string[];
+    subject: string;
+    text: string;
+    html?: string | null;
+};
+export type ForwardInput = {
+    to: string[];
+    subject: string;
+    text: string;
+    html?: string | null;
+};
+export type OutboundResult = {
+    thread_id?: string;
+    message_id?: string;
+    send_intent_id?: string;
+    approval_id?: string;
+    status: 'pending' | 'queued' | 'sent' | 'failed';
+    provider_result?: unknown;
+    error?: string;
+    decision?: string;
+    reasons?: string[];
+    risk_flags?: string[];
+};
+export type CreateWebhookInput = {
+    url: string;
+    events?: string[];
+};
+export type WebhookEndpoint = {
+    id: string;
+    url: string;
+    events: string[];
+    status: string;
+    version: number;
+    created_at?: string;
+};
+export type CreatedWebhookEndpoint = WebhookEndpoint & {
+    secret: string;
+    secret_returned_once: true;
+};
+export type WebhookDelivery = {
+    id: string;
+    endpoint_id: string;
+    generation: number;
+    event_type: string;
+    payload_json: unknown;
+    status: string;
+    attempts: number;
+    last_error: string | null;
+    created_at: string;
+    delivered_at: string | null;
+};
+export declare const REVERBIN_API_SCOPES: readonly ["inboxes:read", "inboxes:write", "threads:read", "threads:reply", "webhooks:read", "webhooks:write", "webhook-deliveries:read", "approvals:read", "approvals:write", "billing:read", "billing:write", "audit:read", "account:read", "account:write", "api-keys:read", "api-keys:write"];
+export type ApiScope = typeof REVERBIN_API_SCOPES[number];
+export type ApiKeyMetadata = {
+    id: string;
+    name: string;
+    scopes: ApiScope[];
+    version: number;
+    created_at: string;
+    expires_at: string | null;
+    last_used_at: string | null;
+    rotated_at: string | null;
+    revoked_at: string | null;
+};
+export type CreatedApiKey = ApiKeyMetadata & {
+    token: string;
+    token_returned_once: true;
+};
+export type CreateApiKeyInput = {
+    name: string;
+    scopes?: ApiScope[];
+    expires_at?: string | null;
+};
+export type CredentialRotationInput = {
+    expected_version: number;
+    idempotency_key: string;
+};
+export type Approval = {
+    id: string;
+    inbox_id: string;
+    thread_id: string;
+    status: 'pending' | 'approved' | 'rejected' | string;
+    proposed_to_json?: string[];
+    subject?: string;
+    body_text?: string;
+    body_html?: string | null;
+    risk_flags_json?: string[];
+    policy_reasons_json?: string[];
+    created_at?: string;
+    decided_at?: string | null;
+    [key: string]: unknown;
+};
+export type AgentSignupInput = {
+    idempotency_key: string;
+    requester_email: string;
+    agent_name: string;
+    agent_use_case: string;
+    preferred_inbox_name: string;
+    webhook_url?: string;
+};
+export type AgentSignupCreatedResult = {
+    status: 'provisioned';
+    credentials_returned: true;
+    signup_request_id: string;
+    tenant_id: string;
+    agent: {
+        id: string;
+        name: string;
+    };
+    inbox: Inbox;
+    api_key: {
+        id: string;
+        token: string;
+        scopes: ApiScope[];
+        version: number;
+        returned_once: true;
+    };
+    webhook?: CreatedWebhookEndpoint | null;
+    quickstart: {
+        base_url: string;
+        inbox_email: string;
+        next_steps: string[];
+    };
+};
+export type AgentSignupReplayResult = {
+    status: 'provisioned';
+    credentials_returned: false;
+    signup_request_id: string;
+    tenant_id: string;
+    agent: {
+        id: string;
+        name: string;
+    };
+    inbox: Inbox;
+    message: string;
+};
+export type AgentSignupResult = AgentSignupCreatedResult | AgentSignupReplayResult;
+export type SignupVerificationCheck = {
+    key: string;
+    label: string;
+    required: boolean;
+    status: 'pending' | 'passed' | 'failed';
+    evidence?: string;
+};
+export type SignupRequest = {
+    id: string;
+    requester_email: string;
+    requester_name?: string | null;
+    agent_use_case: string;
+    preferred_inbox_name?: string | null;
+    webhook_url?: string | null;
+    status: string;
+    verification_json?: SignupVerificationCheck[];
+    notes?: string | null;
+    verification_summary?: unknown;
+    created_at?: string;
+    updated_at?: string;
+    [key: string]: unknown;
+};
+export type CreateSignupRequestInput = {
+    requester_email: string;
+    requester_name?: string;
+    agent_use_case: string;
+    preferred_inbox_name?: string;
+    webhook_url?: string;
+    notes?: string;
+};
+export type UpdateSignupRequestInput = {
+    status?: 'pending' | 'approved' | 'rejected' | 'provisioned';
+    verification?: SignupVerificationCheck[];
+    notes?: string;
+};
+export type BillingPlanKey = 'free' | 'developer' | 'startup' | 'enterprise';
+export type BillingPlan = {
+    key: BillingPlanKey;
+    label: string;
+    price_monthly_usd: number | null;
+    max_inboxes: number;
+    emails_per_month: number | null;
+    max_webhooks: number;
+};
+export type CreateCheckoutInput = {
+    plan: 'developer' | 'startup';
+    idempotency_key: string;
+    success_url?: string;
+    cancel_url?: string;
+};
+export type BillingSession = {
+    id: string;
+    url: string | null;
+    provider: string;
+    plan?: 'developer' | 'startup';
+    link_enabled_by_stripe?: boolean;
+};
+export type CreateBillingPortalInput = {
+    idempotency_key: string;
+    return_url?: string;
+};
+export type AuditLog = {
+    id: string;
+    action: string;
+    target_type?: string;
+    target_id?: string;
+    metadata_json?: unknown;
+    created_at: string;
+    [key: string]: unknown;
+};
+export type AccountExport = {
+    exported_at?: string;
+    limit_per_collection?: number;
+    tenant?: Record<string, unknown>;
+    [collection: string]: unknown;
+};
+export type AccountDeletionPending = {
+    id: string;
+    account_status: 'deletion_pending';
+    deletion_requested_at: string;
+    deletion_due_at: string;
+};
+export type AccountDeletionCancelled = {
+    id: string;
+    account_status: 'active';
+    deletion_requested_at: null;
+    deletion_due_at: null;
+};
+export type QuotaMetadata = {
+    limit: number;
+    used: number;
+    resetAt: string | null;
+};
+type ErrorMetadata = {
+    requestId?: string;
+    retryAfterSeconds?: number;
+    apiKey?: string;
+};
+export declare class ReverbinApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly requestId?: string;
+    readonly retryAfterSeconds?: number;
+    readonly quota?: QuotaMetadata;
+    readonly details: unknown;
+    constructor(status: number, body: unknown, metadata?: ErrorMetadata);
+    /** @deprecated Prefer `details`; this alias remains for pre-1.0 compatibility. */
+    get body(): unknown;
+    toJSON(): {
+        name: string;
+        message: string;
+        status: number;
+        code: string;
+        requestId: string | undefined;
+        retryAfterSeconds: number | undefined;
+        quota: QuotaMetadata | undefined;
+        details: unknown;
+    };
+}
+export declare class ReverbinResponseError extends Error {
+    readonly status: number;
+    readonly code = "invalid_json_response";
+    readonly requestId?: string;
+    constructor(status: number, requestId?: string);
+}
+export declare class ReverbinTimeoutError extends Error {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+export declare class ReverbinClient {
+    #private;
+    readonly baseUrl: string;
+    constructor(options?: ReverbinClientOptions);
+    readonly signups: {
+        create: (input: AgentSignupInput, options?: RequestOptions) => Promise<AgentSignupResult>;
+    };
+    readonly inboxes: {
+        create: (input: CreateInboxInput, options?: RequestOptions) => Promise<Inbox>;
+        list: (page?: PageOptions, options?: RequestOptions) => Promise<ListResponse<Inbox>>;
+        get: (id: string, options?: RequestOptions) => Promise<Inbox>;
+        threads: (id: string, page?: PageOptions, options?: RequestOptions) => Promise<ListResponse<Thread>>;
+    };
+    readonly messages: {
+        compose: (input: ComposeInput, options?: RequestOptions) => Promise<OutboundResult>;
+        list: (threadId: string, page?: PageOptions, options?: RequestOptions) => Promise<ListResponse<Message>>;
+    };
+    readonly threads: {
+        get: (id: string, page?: PageOptions, options?: RequestOptions) => Promise<ThreadDetail>;
+        messages: (id: string, page?: PageOptions, options?: RequestOptions) => Promise<ListResponse<Message>>;
+        reply: (id: string, input: ReplyInput, options?: RequestOptions) => Promise<OutboundResult>;
+        forward: (id: string, input: ForwardInput, options?: RequestOptions) => Promise<OutboundResult>;
+    };
+    readonly approvals: {
+        list: (page?: PageOptions, options?: RequestOptions) => Promise<ListResponse<Approval>>;
+        approve: (id: string, options?: RequestOptions) => Promise<OutboundResult>;
+        reject: (id: string, options?: RequestOptions) => Promise<Approval>;
+    };
+    readonly webhooks: {
+        create: (input: CreateWebhookInput, options?: RequestOptions) => Promise<CreatedWebhookEndpoint>;
+        list: (page?: PageOptions, options?: RequestOptions) => Promise<ListResponse<WebhookEndpoint>>;
+        deliveries: (page?: PageOptions, options?: RequestOptions) => Promise<ListResponse<WebhookDelivery>>;
+        rotateSecret: (id: string, input: CredentialRotationInput, options?: RequestOptions) => Promise<CreatedWebhookEndpoint>;
+        revoke: (id: string, options?: RequestOptions) => Promise<void>;
+    };
+    readonly apiKeys: {
+        list: (page?: PageOptions, options?: RequestOptions) => Promise<ListResponse<ApiKeyMetadata>>;
+        create: (input: CreateApiKeyInput, options?: RequestOptions) => Promise<CreatedApiKey>;
+        rotate: (id: string, input: CredentialRotationInput, options?: RequestOptions) => Promise<CreatedApiKey>;
+        revoke: (id: string, options?: RequestOptions) => Promise<{
+            id: string;
+            status: "revoked";
+        }>;
+    };
+    readonly account: {
+        export: (options?: RequestOptions) => Promise<AccountExport>;
+        requestDeletion: (confirmation: "DELETE", options?: RequestOptions) => Promise<AccountDeletionPending>;
+        cancelDeletion: (options?: RequestOptions) => Promise<AccountDeletionCancelled>;
+    };
+    readonly billing: {
+        plans: (options?: RequestOptions) => Promise<DataResponse<BillingPlan>>;
+        checkout: (input: CreateCheckoutInput, options?: RequestOptions) => Promise<BillingSession>;
+        portal: (input: CreateBillingPortalInput, options?: RequestOptions) => Promise<BillingSession>;
+    };
+    readonly auditLogs: {
+        list: (page?: PageOptions, options?: RequestOptions) => Promise<ListResponse<AuditLog>>;
+    };
+    readonly signupRequests: {
+        create: (input: CreateSignupRequestInput, options?: RequestOptions) => Promise<SignupRequest>;
+        list: (page?: PageOptions, options?: RequestOptions) => Promise<ListResponse<SignupRequest>>;
+        update: (id: string, input: UpdateSignupRequestInput, options?: RequestOptions) => Promise<SignupRequest>;
+    };
+    private request;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,391 @@
+export const REVERBIN_DEFAULT_BASE_URL = 'https://api.reverbin.com';
+export const REVERBIN_DEFAULT_TIMEOUT_MS = 30_000;
+export const REVERBIN_MAX_TIMEOUT_MS = 120_000;
+export const REVERBIN_API_SCOPES = [
+    'inboxes:read',
+    'inboxes:write',
+    'threads:read',
+    'threads:reply',
+    'webhooks:read',
+    'webhooks:write',
+    'webhook-deliveries:read',
+    'approvals:read',
+    'approvals:write',
+    'billing:read',
+    'billing:write',
+    'audit:read',
+    'account:read',
+    'account:write',
+    'api-keys:read',
+    'api-keys:write',
+];
+const REDACTED = '[REDACTED]';
+const SENSITIVE_KEY = /authorization|api[_-]?key|token|secret|password|credential/i;
+const REVERBIN_TOKEN = /\brvb_[A-Za-z0-9_-]{8,}\b/g;
+const REVERBIN_TOKEN_PATTERN = /\brvb_[A-Za-z0-9_-]{8,}\b/;
+function sanitizeErrorString(value, apiKey) {
+    const withoutKnownKey = apiKey ? value.split(apiKey).join(REDACTED) : value;
+    return withoutKnownKey.replace(REVERBIN_TOKEN, REDACTED);
+}
+function sanitizeErrorValue(value, apiKey, depth = 0) {
+    if (depth > 8)
+        return '[TRUNCATED]';
+    if (typeof value === 'string')
+        return sanitizeErrorString(value, apiKey);
+    if (Array.isArray(value))
+        return value.map((item) => sanitizeErrorValue(item, apiKey, depth + 1));
+    if (!value || typeof value !== 'object')
+        return value;
+    const output = {};
+    for (const [key, child] of Object.entries(value)) {
+        output[key] = SENSITIVE_KEY.test(key) ? REDACTED : sanitizeErrorValue(child, apiKey, depth + 1);
+    }
+    return output;
+}
+function errorRecord(body) {
+    return body && typeof body === 'object' && !Array.isArray(body) ? body : undefined;
+}
+function safeErrorCode(body, apiKey) {
+    const record = errorRecord(body);
+    const candidate = record?.error ?? record?.code;
+    return typeof candidate === 'string'
+        && (!apiKey || !candidate.includes(apiKey))
+        && !REVERBIN_TOKEN_PATTERN.test(candidate)
+        && /^[a-zA-Z0-9_.:-]{1,120}$/.test(candidate)
+        ? candidate
+        : 'http_error';
+}
+function quotaMetadata(body) {
+    const record = errorRecord(body);
+    if (!record || !Number.isFinite(record.limit) || !Number.isFinite(record.used))
+        return undefined;
+    return {
+        limit: Number(record.limit),
+        used: Number(record.used),
+        resetAt: typeof record.reset_at === 'string' && Number.isFinite(Date.parse(record.reset_at)) ? record.reset_at : null,
+    };
+}
+export class ReverbinApiError extends Error {
+    status;
+    code;
+    requestId;
+    retryAfterSeconds;
+    quota;
+    details;
+    constructor(status, body, metadata = {}) {
+        const code = safeErrorCode(body, metadata.apiKey);
+        super(`Reverbin API request failed (${status} ${code})`);
+        this.name = 'ReverbinApiError';
+        this.status = status;
+        this.code = code;
+        this.requestId = metadata.requestId ? sanitizeErrorString(metadata.requestId, metadata.apiKey) : undefined;
+        this.retryAfterSeconds = metadata.retryAfterSeconds;
+        this.quota = quotaMetadata(body);
+        this.details = sanitizeErrorValue(body, metadata.apiKey);
+    }
+    /** @deprecated Prefer `details`; this alias remains for pre-1.0 compatibility. */
+    get body() {
+        return this.details;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            status: this.status,
+            code: this.code,
+            requestId: this.requestId,
+            retryAfterSeconds: this.retryAfterSeconds,
+            quota: this.quota,
+            details: this.details,
+        };
+    }
+}
+export class ReverbinResponseError extends Error {
+    status;
+    code = 'invalid_json_response';
+    requestId;
+    constructor(status, requestId) {
+        super(`Reverbin API returned malformed JSON (status ${status})`);
+        this.name = 'ReverbinResponseError';
+        this.status = status;
+        this.requestId = requestId;
+    }
+}
+export class ReverbinTimeoutError extends Error {
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Reverbin API request timed out after ${timeoutMs}ms`);
+        this.name = 'ReverbinTimeoutError';
+        this.timeoutMs = timeoutMs;
+    }
+}
+function validateTimeout(value, fallback) {
+    const timeoutMs = value ?? fallback;
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > REVERBIN_MAX_TIMEOUT_MS) {
+        throw new TypeError(`timeoutMs must be an integer from 1 through ${REVERBIN_MAX_TIMEOUT_MS}`);
+    }
+    return timeoutMs;
+}
+function normalizeBaseUrl(value) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new TypeError('baseUrl must be an absolute HTTP or HTTPS URL');
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new TypeError('baseUrl must use HTTP or HTTPS');
+    }
+    if (url.username || url.password)
+        throw new TypeError('baseUrl must not contain credentials');
+    if (url.search || url.hash)
+        throw new TypeError('baseUrl must not contain a query or fragment');
+    url.pathname = `${url.pathname.replace(/\/+$/, '')}/`;
+    return url;
+}
+function normalizeApiKey(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || value.length > 4_096 || value !== value.trim() || /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new TypeError('apiKey must be a non-empty value without surrounding whitespace');
+    }
+    return value;
+}
+function encodedId(value, label) {
+    if (typeof value !== 'string' || !value.trim() || /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new TypeError(`${label} must be a non-empty identifier`);
+    }
+    return encodeURIComponent(value);
+}
+function idempotencyKey(value) {
+    if (typeof value !== 'string' || value !== value.trim() || value.length < 1 || value.length > 200 || /[\u0000-\u001f\u007f]/.test(value)) {
+        throw new TypeError('idempotency_key must contain 1 to 200 non-control characters');
+    }
+    return value;
+}
+function pagePath(path, options) {
+    if (!options)
+        return path;
+    const params = new URLSearchParams();
+    if (options.limit !== undefined) {
+        if (!Number.isSafeInteger(options.limit) || options.limit < 1 || options.limit > 100) {
+            throw new TypeError('limit must be an integer from 1 through 100');
+        }
+        params.set('limit', String(options.limit));
+    }
+    if (options.cursor !== undefined) {
+        if (typeof options.cursor !== 'string' || !options.cursor || options.cursor.length > 2048) {
+            throw new TypeError('cursor must be a non-empty opaque string no longer than 2048 characters');
+        }
+        params.set('cursor', options.cursor);
+    }
+    const query = params.toString();
+    return query ? `${path}?${query}` : path;
+}
+function retryAfterSeconds(response, body) {
+    const value = response.headers.get('retry-after');
+    if (value) {
+        const seconds = Number(value);
+        if (Number.isFinite(seconds) && seconds >= 0)
+            return Math.ceil(seconds);
+        const at = Date.parse(value);
+        if (Number.isFinite(at))
+            return Math.max(0, Math.ceil((at - Date.now()) / 1_000));
+    }
+    const bodyValue = errorRecord(body)?.retry_after_seconds;
+    return Number.isFinite(bodyValue) && Number(bodyValue) >= 0 ? Math.ceil(Number(bodyValue)) : undefined;
+}
+function requestId(response, body, apiKey) {
+    const header = response.headers.get('x-request-id') ?? response.headers.get('request-id');
+    if (header)
+        return sanitizeErrorString(header.slice(0, 200), apiKey);
+    const value = errorRecord(body)?.request_id;
+    return typeof value === 'string' ? sanitizeErrorString(value.slice(0, 200), apiKey) : undefined;
+}
+function composedSignal(callerSignal, timeoutMs) {
+    const controller = new AbortController();
+    let timedOut = false;
+    const abortFromCaller = () => controller.abort(callerSignal?.reason);
+    if (callerSignal?.aborted)
+        abortFromCaller();
+    else
+        callerSignal?.addEventListener('abort', abortFromCaller, { once: true });
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    timer.unref?.();
+    return {
+        signal: controller.signal,
+        didTimeOut: () => timedOut,
+        cleanup: () => {
+            clearTimeout(timer);
+            callerSignal?.removeEventListener('abort', abortFromCaller);
+        },
+    };
+}
+async function parseResponseBody(response, responseRequestId) {
+    if (response.status === 204 || response.status === 205)
+        return undefined;
+    const text = await response.text();
+    if (!text)
+        return null;
+    const contentType = response.headers.get('content-type')?.toLowerCase() ?? '';
+    if (contentType.includes('application/json') || contentType.includes('+json')) {
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new ReverbinResponseError(response.status, responseRequestId);
+        }
+    }
+    if (response.ok)
+        throw new ReverbinResponseError(response.status, responseRequestId);
+    return text;
+}
+export class ReverbinClient {
+    baseUrl;
+    #baseUrl;
+    #apiKey;
+    #fetchImpl;
+    #timeoutMs;
+    constructor(options = {}) {
+        this.#baseUrl = normalizeBaseUrl(options.baseUrl ?? REVERBIN_DEFAULT_BASE_URL);
+        this.baseUrl = this.#baseUrl.href.replace(/\/$/, '');
+        this.#apiKey = normalizeApiKey(options.apiKey);
+        this.#timeoutMs = validateTimeout(options.timeoutMs, REVERBIN_DEFAULT_TIMEOUT_MS);
+        const fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof fetchImpl !== 'function')
+            throw new TypeError('fetch is not available; pass ReverbinClient({ fetch })');
+        this.#fetchImpl = fetchImpl;
+    }
+    signups = {
+        create: (input, options) => this.request('/v1/agent-signups', {
+            ...options,
+            method: 'POST',
+            body: {
+                requester_email: input.requester_email,
+                agent_name: input.agent_name,
+                agent_use_case: input.agent_use_case,
+                preferred_inbox_name: input.preferred_inbox_name,
+                ...(input.webhook_url === undefined ? {} : { webhook_url: input.webhook_url }),
+            },
+            idempotencyKey: idempotencyKey(input.idempotency_key),
+        }),
+    };
+    inboxes = {
+        create: (input, options) => this.request('/v1/inboxes', { ...options, method: 'POST', body: input }),
+        list: (page, options) => this.request(pagePath('/v1/inboxes', page), options),
+        get: (id, options) => this.request(`/v1/inboxes/${encodedId(id, 'inbox id')}`, options),
+        threads: (id, page, options) => this.request(pagePath(`/v1/inboxes/${encodedId(id, 'inbox id')}/threads`, page), options),
+    };
+    messages = {
+        compose: (input, options) => this.request('/v1/messages', { ...options, method: 'POST', body: input }),
+        list: (threadId, page, options) => this.request(pagePath(`/v1/threads/${encodedId(threadId, 'thread id')}/messages`, page), options),
+    };
+    threads = {
+        get: (id, page, options) => this.request(pagePath(`/v1/threads/${encodedId(id, 'thread id')}`, page), options),
+        messages: (id, page, options) => this.request(pagePath(`/v1/threads/${encodedId(id, 'thread id')}/messages`, page), options),
+        reply: (id, input, options) => this.request(`/v1/threads/${encodedId(id, 'thread id')}/reply`, { ...options, method: 'POST', body: input }),
+        forward: (id, input, options) => this.request(`/v1/threads/${encodedId(id, 'thread id')}/forward`, { ...options, method: 'POST', body: input }),
+    };
+    approvals = {
+        list: (page, options) => this.request(pagePath('/v1/approvals', page), options),
+        approve: (id, options) => this.request(`/v1/approvals/${encodedId(id, 'approval id')}/approve`, { ...options, method: 'POST' }),
+        reject: (id, options) => this.request(`/v1/approvals/${encodedId(id, 'approval id')}/reject`, { ...options, method: 'POST' }),
+    };
+    webhooks = {
+        create: (input, options) => this.request('/v1/webhooks', { ...options, method: 'POST', body: input }),
+        list: (page, options) => this.request(pagePath('/v1/webhooks', page), options),
+        deliveries: (page, options) => this.request(pagePath('/v1/webhook-deliveries', page), options),
+        rotateSecret: (id, input, options) => this.request(`/v1/webhooks/${encodedId(id, 'webhook id')}/rotate-secret`, {
+            ...options,
+            method: 'POST',
+            body: { expected_version: input.expected_version },
+            idempotencyKey: idempotencyKey(input.idempotency_key),
+        }),
+        revoke: (id, options) => this.request(`/v1/webhooks/${encodedId(id, 'webhook id')}`, { ...options, method: 'DELETE' }),
+    };
+    apiKeys = {
+        list: (page, options) => this.request(pagePath('/v1/api-keys', page), options),
+        create: (input, options) => this.request('/v1/api-keys', { ...options, method: 'POST', body: input }),
+        rotate: (id, input, options) => this.request(`/v1/api-keys/${encodedId(id, 'API key id')}/rotate`, {
+            ...options,
+            method: 'POST',
+            body: { expected_version: input.expected_version },
+            idempotencyKey: idempotencyKey(input.idempotency_key),
+        }),
+        revoke: (id, options) => this.request(`/v1/api-keys/${encodedId(id, 'API key id')}/revoke`, { ...options, method: 'POST' }),
+    };
+    account = {
+        export: (options) => this.request('/v1/account/export', options),
+        requestDeletion: (confirmation, options) => this.request('/v1/account/deletion-request', { ...options, method: 'POST', body: { confirmation } }),
+        cancelDeletion: (options) => this.request('/v1/account/deletion-request/cancel', { ...options, method: 'POST' }),
+    };
+    billing = {
+        plans: (options) => this.request('/v1/billing/plans', options),
+        checkout: (input, options) => this.request('/v1/billing/checkout', {
+            ...options,
+            method: 'POST',
+            body: {
+                plan: input.plan,
+                ...(input.success_url === undefined ? {} : { success_url: input.success_url }),
+                ...(input.cancel_url === undefined ? {} : { cancel_url: input.cancel_url }),
+            },
+            idempotencyKey: idempotencyKey(input.idempotency_key),
+        }),
+        portal: (input, options) => this.request('/v1/billing/portal', {
+            ...options,
+            method: 'POST',
+            body: input.return_url === undefined ? {} : { return_url: input.return_url },
+            idempotencyKey: idempotencyKey(input.idempotency_key),
+        }),
+    };
+    auditLogs = {
+        list: (page, options) => this.request(pagePath('/v1/audit-logs', page), options),
+    };
+    signupRequests = {
+        create: (input, options) => this.request('/v1/signup-requests', { ...options, method: 'POST', body: input }),
+        list: (page, options) => this.request(pagePath('/v1/signup-requests', page), options),
+        update: (id, input, options) => this.request(`/v1/signup-requests/${encodedId(id, 'signup request id')}`, { ...options, method: 'PATCH', body: input }),
+    };
+    async request(path, options = {}) {
+        const timeoutMs = validateTimeout(options.timeoutMs, this.#timeoutMs);
+        const composed = composedSignal(options.signal, timeoutMs);
+        const headers = { accept: 'application/json' };
+        if (this.#apiKey)
+            headers.authorization = `Bearer ${this.#apiKey}`;
+        if (options.idempotencyKey)
+            headers['idempotency-key'] = options.idempotencyKey;
+        if (options.body !== undefined)
+            headers['content-type'] = 'application/json';
+        const url = new URL(path.replace(/^\/+/, ''), this.#baseUrl);
+        try {
+            const response = await this.#fetchImpl(url, {
+                method: options.method ?? 'GET',
+                headers,
+                body: options.body === undefined ? undefined : JSON.stringify(options.body),
+                signal: composed.signal,
+            });
+            const headerRequestId = requestId(response, undefined, this.#apiKey);
+            const body = await parseResponseBody(response, headerRequestId);
+            if (!response.ok) {
+                throw new ReverbinApiError(response.status, body, {
+                    requestId: requestId(response, body, this.#apiKey),
+                    retryAfterSeconds: retryAfterSeconds(response, body),
+                    apiKey: this.#apiKey,
+                });
+            }
+            return body;
+        }
+        catch (error) {
+            if (composed.didTimeOut())
+                throw new ReverbinTimeoutError(timeoutMs);
+            throw error;
+        }
+        finally {
+            composed.cleanup();
+        }
+    }
+}

package/dist/webhook-signatures.d.ts

@@ -0,0 +1,6 @@
+export type WebhookPayload = string | Uint8Array;
+/**
+ * Verify Reverbin's `sha256=<hex>` signature over the exact raw request body.
+ * Call this once per candidate secret/header during a webhook-secret rotation grace period.
+ */
+export declare function verifyWebhookSignature(rawBody: WebhookPayload, signature: string | null | undefined, secret: string): boolean;

package/dist/webhook-signatures.js

@@ -0,0 +1,17 @@
+import { createHmac, timingSafeEqual } from 'node:crypto';
+/**
+ * Verify Reverbin's `sha256=<hex>` signature over the exact raw request body.
+ * Call this once per candidate secret/header during a webhook-secret rotation grace period.
+ */
+export function verifyWebhookSignature(rawBody, signature, secret) {
+    if (typeof secret !== 'string' || secret.length === 0) {
+        throw new TypeError('webhook secret must be a non-empty string');
+    }
+    const expected = createHmac('sha256', secret).update(rawBody).digest();
+    const validFormat = typeof signature === 'string' && /^sha256=[0-9a-f]{64}$/.test(signature);
+    const supplied = validFormat
+        ? Buffer.from(signature.slice('sha256='.length), 'hex')
+        : Buffer.alloc(expected.length);
+    const equal = timingSafeEqual(expected, supplied);
+    return validFormat && equal;
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@builtbyecho/reverbin",
+  "version": "0.1.0",
+  "description": "Node.js ESM SDK for Reverbin agent inboxes, threads, messages, approvals, webhooks, credentials, billing, and account lifecycle APIs.",
+  "type": "module",
+  "main": "./dist/client.js",
+  "types": "./dist/client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./webhook-signatures": {
+      "types": "./dist/webhook-signatures.d.ts",
+      "import": "./dist/webhook-signatures.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Wdustin1/reverbin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Wdustin1/reverbin/issues"
+  },
+  "homepage": "https://reverbin.com",
+  "license": "MIT",
+  "keywords": [
+    "agents",
+    "email",
+    "inbox",
+    "reverbin",
+    "sdk",
+    "typescript",
+    "webhooks"
+  ]
+}