@agentisend/sdk-node 0.2.0 → 0.4.0

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { ApiKey, AutomationRun, ReceivedAttachment, ReceivedEmail, ReceivedThread, SentAttachment, RequestLogEntry, EventDefinition, EventFieldType, ApiKeyPermission, BatchItemResult, CreatedApiKey, CreatedWebhookEndpoint, DeadLetter, Deleted, Domain, DomainRegion, LegacyDomainRegion, Email, EventType, Limit, LimitPeriod, ListEmailsQuery, ListQuery, MetricsQuery, ExplainReport, Page, PreflightReport, ReplayResult, ContactTopic, SendEmailPayload, ServiceStatus, SuppressionBatchItem, AuditEntry, TeamInvite, TeamMember, Topic, BillingPlan, TrustStanding, WebhookEndpoint } from './types.js';
+import type { ApiKey, AutomationRun, ReceivedAttachment, ReceivedEmail, ReceivedThread, SentAttachment, RequestLogEntry, EventDefinition, EventFieldType, ApiKeyPermission, BatchItemResult, CreatedApiKey, CreatedWebhookEndpoint, DeadLetter, Deleted, Domain, DomainRegion, DomainSetup, LegacyDomainRegion, Email, EventType, Limit, LimitPeriod, ListEmailsQuery, ListQuery, MetricsQuery, ExplainReport, Page, PreflightReport, ReplayResult, ContactTopic, SendEmailPayload, ServiceStatus, SuppressionBatchItem, AuditEntry, TeamInvite, TeamMember, Topic, BillingPlan, TrustStanding, WebhookEndpoint } from './types.js';
 export declare const DEFAULT_BASE_URL = "https://api.agentisend.com";
 export interface FetchResponse {
     status: number;
@@ -6,6 +6,8 @@ export interface FetchResponse {
         get(name: string): string | null;
     };
     text(): Promise<string>;
+    /** Read for downloads (an attachment, an .eml). Falls back to text() when absent. */
+    arrayBuffer?(): Promise<ArrayBuffer>;
 }
 export type FetchLike = (url: string, init: {
     method: string;
@@ -19,6 +21,7 @@ export interface ClientOptions {
     /** Injected for tests and for runtimes without a global fetch. */
     fetch?: FetchLike;
     timeoutMs?: number;
+    /** Defaults to `agentisend-node/<SDK version> node/<Node version>`. */
     userAgent?: string;
 }
 export interface RequestOptions {
@@ -29,6 +32,12 @@ export interface RequestOptions {
      */
     idempotencyKey?: string;
     signal?: AbortSignal;
+    /**
+     * Extra request headers, merged in after idempotency-key. Used for
+     * `x-batch-validation` on `emails.batch` (RESENDCOMPAT-5/-6) — never for
+     * `authorization`, `accept` or `content-type`, which this client owns.
+     */
+    headers?: Record<string, string>;
 }
 /**
  * Build an idempotency key in the shape that debugs well: `<what>/<which>`,
@@ -55,7 +64,17 @@ export declare class AgentiSend {
     private readonly timeoutMs;
     private readonly userAgent;
     constructor(apiKey?: string, options?: ClientOptions);
+    private send;
     request<T>(raw: RawRequest): Promise<T>;
+    /**
+     * A response that is not JSON: an attachment, an .eml, the CSV export. A
+     * refusal still arrives as the JSON error envelope and throws the same
+     * AgentiSendError that request() throws.
+     */
+    requestBytes(raw: Omit<RawRequest, 'body'>): Promise<Uint8Array>;
+    /** The same download, decoded as UTF-8: an .eml, raw MIME, a CSV. */
+    requestText(raw: Omit<RawRequest, 'body'>): Promise<string>;
+    private fail;
     readonly emails: {
         send: (payload: SendEmailPayload, options?: RequestOptions) => Promise<{
             id: string;
@@ -75,8 +94,15 @@ export declare class AgentiSend {
             id: string;
             status: string;
         }>;
+        /** Delete a sent email and its events for good. A scheduled one must be cancelled first. */
+        remove: (id: string, options?: RequestOptions) => Promise<{
+            id: string;
+            status: string;
+        }>;
         /** Move an email to a new time. Works from scheduled AND canceled. */
-        reschedule: (id: string, scheduledAt: string, options?: RequestOptions) => Promise<{
+        reschedule: (id: string, scheduledAt: string, options?: RequestOptions & {
+            timezone?: string;
+        }) => Promise<{
             id: string;
             status: string;
             scheduled_at: string;
@@ -89,6 +115,41 @@ export declare class AgentiSend {
         explain: (id: string) => Promise<ExplainReport>;
         /** Run every gate without sending or spending. Free, always. */
         preflight: (payload: SendEmailPayload) => Promise<PreflightReport>;
+        /** Deliverability lint without sending: a 0-100 placement score and every finding with its fix. */
+        lint: (payload: {
+            from: string;
+            to: string[];
+            subject?: string;
+            html?: string;
+            text?: string;
+            headers?: Record<string, string>;
+        }) => Promise<Record<string, unknown>>;
+        /** Every event recorded for one message, oldest first. */
+        events: (id: string, query?: ListQuery) => Promise<Page<Record<string, unknown>>>;
+        /** The exact RFC 5322 source of this message, as text. */
+        mime: (id: string) => Promise<string>;
+        /** The same message as a .eml file. */
+        eml: (id: string) => Promise<string>;
+        /** One attachment's bytes, as they were sent. */
+        attachment: (id: string, attachmentId: string) => Promise<Uint8Array>;
+        /** Cancel scheduled or queued messages by id, or everything scheduled before a time. */
+        bulkCancel: (payload: {
+            ids?: string[];
+            before?: string;
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /** The message log as CSV, with the same filters as list. */
+        export: (query?: {
+            status?: string;
+            q?: string;
+            from?: string;
+            to?: string;
+            domain?: string;
+            bounce_class?: string;
+            api_key_id?: string;
+            template_id?: string;
+            since?: string;
+            until?: string;
+        }) => Promise<string>;
         /**
          * Move a scheduled email. The same act as `reschedule`, under the verb a
          * Resend integration already calls (M5.5).
@@ -115,6 +176,16 @@ export declare class AgentiSend {
             scopes?: string[];
         }, options?: RequestOptions) => Promise<ApiKey>;
         delete: (id: string, options?: RequestOptions) => Promise<Deleted>;
+        /**
+         * Issue a new token for this key. The old one keeps working for
+         * `grace_hours` (0, 1 or 24) so a deploy can pick up the new one.
+         */
+        rotate: (id: string, payload: {
+            grace_hours: 0 | 1 | 24;
+        }, options?: RequestOptions) => Promise<CreatedApiKey & {
+            rotated_at: string;
+            previous_key_expires_at: string | null;
+        }>;
     };
     readonly domains: {
         create: (payload: {
@@ -122,23 +193,52 @@ export declare class AgentiSend {
             region?: DomainRegion | LegacyDomainRegion;
             tracking?: boolean;
             tracking_subdomain?: string;
+            return_path_subdomain?: string;
+            open_tracking?: boolean;
+            click_tracking?: boolean;
+            tls_mode?: "opportunistic" | "enforced";
         }, options?: RequestOptions) => Promise<Domain>;
         list: (query?: ListQuery) => Promise<Page<Domain>>;
         get: (id: string) => Promise<Domain>;
+        /** One-shot DNS sheet: zone file, copy-paste commands, provider. */
+        setup: (id: string) => Promise<DomainSetup>;
         verify: (id: string, options?: RequestOptions) => Promise<Domain>;
-        /** A8 + P3b: click/open tracking, or a new tracking_subdomain. Never removed. */
+        /** A8 + P3b: click/open tracking, TLS mode, or a new tracking_subdomain. Never removed. */
         update: (id: string, payload: {
             click_tracking?: boolean;
             open_tracking?: boolean;
             tracking_subdomain?: string;
+            tls_mode?: "opportunistic" | "enforced";
         }, options?: RequestOptions) => Promise<Domain>;
         delete: (id: string, options?: RequestOptions) => Promise<Deleted>;
+        /**
+         * Long-poll until the domain is verified or failed, or `timeout` seconds
+         * (0-25) pass; 0 is a snapshot. It does not re-check DNS: the server checks
+         * on its own, and `next_poll_seconds` says when to ask again.
+         */
+        wait: (id: string, query?: {
+            timeout?: number;
+        }) => Promise<{
+            id: string;
+            name: string;
+            status: string;
+            progress: unknown;
+            reason: string | null;
+            deadline: string;
+            next_poll_seconds: number | null;
+        }>;
+        /** Newest-first timeline: each DNS check, each record found or lost, verified, deleted. */
+        events: (id: string, query?: ListQuery) => Promise<Page<Record<string, unknown>>>;
+        /** Alias of setup: detects the DNS provider and returns the exact records to add. */
+        connect: (id: string) => Promise<DomainSetup>;
     };
     readonly webhooks: {
         create: (payload: {
             url: string;
             events?: EventType[];
             svix_compat?: boolean;
+            /** `resend` stores Resend's envelope (`created_at`, `data.to`, `data.bounce`). */
+            payload_format?: "native" | "resend";
         }, options?: RequestOptions) => Promise<CreatedWebhookEndpoint>;
         list: (query?: ListQuery) => Promise<Page<WebhookEndpoint>>;
         get: (id: string) => Promise<WebhookEndpoint>;
@@ -158,6 +258,21 @@ export declare class AgentiSend {
             limit?: number;
             cursor?: string;
         }) => Promise<Page<DeadLetter>>;
+        /** Every delivery to this endpoint, with each attempt and what the receiver answered. */
+        deliveries: (id: string, query?: ListQuery & {
+            id?: string;
+            event_type?: EventType;
+            status?: "pending" | "retrying" | "delivered" | "dead_lettered";
+            since?: string;
+            until?: string;
+        }) => Promise<Page<Record<string, unknown>>>;
+        /** A new signing secret, returned once. The previous one keeps verifying for 24 hours. */
+        rotateSecret: (id: string, options?: RequestOptions) => Promise<{
+            id: string;
+            secret: string;
+            rotated_at: string;
+            previous_secret_expires_at: string;
+        }>;
     };
     readonly limits: {
         list: (query?: ListQuery) => Promise<Page<Limit>>;
@@ -170,6 +285,16 @@ export declare class AgentiSend {
         /** Stops the key sending, immediately. Takes effect on its next request. */
         kill: (apiKeyId: string, reason?: string, options?: RequestOptions) => Promise<Limit>;
         resume: (apiKeyId: string, options?: RequestOptions) => Promise<Limit>;
+        /**
+         * Stop every key on the account sending, in one call. Undoing it is a
+         * person's decision, made in the console; no key can resume it.
+         */
+        killAll: (reason?: string, options?: RequestOptions) => Promise<{
+            paused: boolean;
+            affected_key_ids: string[];
+            reason: string | null;
+            at: string;
+        }>;
     };
     /** M5.5 — the rest of the verb surface a Resend integration calls. */
     /**
@@ -186,6 +311,8 @@ export declare class AgentiSend {
             route?: string;
             error_code?: string;
             api_key_id?: string;
+            q?: string;
+            source?: "api" | "console" | "all";
         }) => Promise<Page<RequestLogEntry>>;
         get: (id: string) => Promise<RequestLogEntry>;
     };
@@ -201,6 +328,11 @@ export declare class AgentiSend {
             until?: string;
         }) => Promise<Page<ReceivedEmail>>;
         get: (id: string) => Promise<ReceivedEmail>;
+        /** Delete one received email for good. */
+        remove: (id: string, options?: RequestOptions) => Promise<{
+            id: string;
+            status: string;
+        }>;
         threads: (query?: ListQuery) => Promise<Page<ReceivedThread>>;
         reply: (id: string, body: {
             html?: string;
@@ -219,6 +351,10 @@ export declare class AgentiSend {
             }[];
         }>;
         attachments: (id: string) => Promise<Page<ReceivedAttachment>>;
+        /** One received attachment's bytes, served as an inert download. */
+        attachment: (id: string, attachmentId: string) => Promise<Uint8Array>;
+        /** The message exactly as it arrived, headers and all. */
+        raw: (id: string) => Promise<string>;
     };
     /**
      * M5.7 — the custom-event registry. Declaring an event's fields turns a
@@ -284,17 +420,76 @@ export declare class AgentiSend {
             status?: "active" | "unsubscribed";
             properties?: Record<string, unknown>;
         }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /** Up to 1,000 contacts. Each item succeeds or fails on its own. */
+        batch: (payload: {
+            contacts: Record<string, unknown>[];
+        }, options?: RequestOptions) => Promise<{
+            data: Record<string, unknown>[];
+        }>;
+        /** CSV in `csv`. Finishes in this response. `on_conflict` defaults to skip. */
+        importCsv: (payload: {
+            csv: string;
+            column_map?: Record<string, string>;
+            on_conflict?: "skip" | "upsert";
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /** Segments whose rules include this contact. The id may be an email. */
+        segments: (id: string) => Promise<Page<Record<string, unknown>>>;
+        /** Refused: membership is the segment's rules. Names PATCH /segments/:id. */
+        addSegment: (id: string, segmentId: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /** Refused: membership is the segment's rules. Names PATCH /segments/:id. */
+        removeSegment: (id: string, segmentId: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /** Lift a marketing unsubscribe after the person opts back in. */
+        resubscribe: (id: string, payload: {
+            consent_source: string;
+            consent_at: string;
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+    };
+    /** Property names and types already stored on the account. */
+    readonly contactProperties: {
+        list: () => Promise<Page<Record<string, unknown>>>;
+        get: (id: string) => Promise<Record<string, unknown>>;
+    };
+    /**
+     * The same contact list, at the paths the official SDK uses when a call
+     * names an audience. This account has one contact list.
+     */
+    readonly audiences: {
+        createContact: (audienceId: string, payload: {
+            email: string;
+            properties?: Record<string, unknown>;
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        listContacts: (audienceId: string, query?: ListQuery & {
+            email?: string;
+        }) => Promise<Page<Record<string, unknown>>>;
+        getContact: (audienceId: string, id: string) => Promise<Record<string, unknown>>;
+        updateContact: (audienceId: string, id: string, payload: Record<string, unknown>, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        deleteContact: (audienceId: string, id: string, options?: RequestOptions) => Promise<Deleted>;
     };
     readonly broadcasts: {
         create: (payload: Record<string, unknown>, options?: RequestOptions) => Promise<Record<string, unknown>>;
         list: (query?: ListQuery) => Promise<Page<Record<string, unknown>>>;
         get: (id: string) => Promise<Record<string, unknown>>;
+        /** Sent, delivered, opened, clicked, bounced, complained and unsubscribed. A test send is not included. */
+        stats: (id: string) => Promise<Record<string, unknown>>;
+        /** The rendered message. Nothing is sent. */
+        preview: (id: string) => Promise<{
+            subject: string;
+            html: string;
+        }>;
         update: (id: string, payload: Record<string, unknown>, options?: RequestOptions) => Promise<Record<string, unknown>>;
-        send: (id: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /**
+         * Send now, or pass `scheduledAt` to schedule it instead (the same time
+         * grammar PATCH /broadcasts/:id accepts). Returns 200 when the broadcast
+         * has finished sending or was scheduled, and 202 while it is still
+         * sending. A 202 has status sending.
+         */
+        send: (id: string, payload?: {
+            scheduledAt?: string;
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
         /** Archive, not delete: a sent broadcast is history worth keeping (F14). */
         archive: (id: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
         messages: (id: string, query?: ListQuery) => Promise<Page<Record<string, unknown>>>;
-        /** Cancel a scheduled broadcast: it returns to draft, editable again. */
+        /** Cancel a scheduled broadcast, or stop one that is still sending. Mail already handed off is not pulled back. A scheduled broadcast returns to draft. */
         cancel: (id: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
     };
     readonly templates: {
@@ -309,10 +504,34 @@ export declare class AgentiSend {
         update: (id: string, payload: Record<string, unknown>, options?: RequestOptions) => Promise<Record<string, unknown>>;
         /** Snapshot the draft as an immutable version. Nothing already sent changes. */
         publish: (id: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
-        render: (id: string, values?: Record<string, unknown>, versionNumber?: number) => Promise<{
+        /**
+         * `rendered` is the HTML; `text` is the plain-text part a markdown
+         * template yields. `preview: true` shows a missing required variable as
+         * `{{name}}` and lists it in `missing_variables` instead of failing.
+         */
+        render: (id: string, values?: Record<string, unknown>, versionNumber?: number | "draft", options?: {
+            preview?: boolean;
+        }) => Promise<{
             rendered: string;
+            subject: string;
+            text: string | null;
+            missing_variables: string[];
         }>;
+        /**
+         * Delete a template and its versions. Sent mail keeps its body and its
+         * template reference. Refused while a broadcast that has not been sent
+         * still uses it.
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<Deleted>;
         versions: (id: string) => Promise<Page<Record<string, unknown>>>;
+        version: (id: string, versionNumber: number) => Promise<Record<string, unknown>>;
+        /** Structured diff between two versions, or between a version and the draft. */
+        diff: (id: string, from: number | "draft", to: number | "draft") => Promise<Record<string, unknown>>;
+        /**
+         * Start a new draft from an older version. History is never rewritten; the
+         * live version stays until that draft is published.
+         */
+        rollback: (id: string, toVersion: number, options?: RequestOptions) => Promise<Record<string, unknown>>;
         /** Copy a template into a fresh editable draft, history not included. */
         duplicate: (id: string, payload?: {
             name?: string;
@@ -323,7 +542,10 @@ export declare class AgentiSend {
         add: (payload: {
             email: string;
             level?: "address" | "domain";
+            origin?: "bounce" | "complaint" | "manual";
         }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /** The id or the address. */
+        get: (id: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
         remove: (id: string, options?: RequestOptions) => Promise<Deleted>;
         /** Up to 500 at a time. Each item succeeds or fails on its own. */
         batchAdd: (emails: string[], level?: "address" | "domain", options?: RequestOptions) => Promise<{
@@ -346,6 +568,10 @@ export declare class AgentiSend {
         get: (id: string) => Promise<Record<string, unknown>>;
         update: (id: string, payload: Record<string, unknown>, options?: RequestOptions) => Promise<Record<string, unknown>>;
         delete: (id: string, options?: RequestOptions) => Promise<Deleted>;
+        /** The account contact list. An audience id on this path does not select a second list. */
+        contacts: (id: string, query?: ListQuery & {
+            email?: string;
+        }) => Promise<Page<Record<string, unknown>>>;
         members: (id: string) => Promise<Page<Record<string, unknown>>>;
     };
     /**
@@ -429,9 +655,102 @@ export declare class AgentiSend {
     };
     /** Public per-component health — the same document the status page renders. */
     readonly status: () => Promise<ServiceStatus>;
+    /** Daily uptime per component over the last 90 days, or `days`. A day nobody measured has no samples. */
+    readonly statusHistory: (query?: {
+        days?: number;
+    }) => Promise<Record<string, unknown>>;
+    /**
+     * Sending-domain DNS check. No API key. Ten checks a minute from one
+     * network. Returns the records to publish; stores nothing.
+     */
+    readonly dnsCheck: (domain: string) => Promise<Record<string, unknown>>;
+    /** Send, delivery and engagement figures with a daily series, over a window. */
+    readonly metrics: (query?: MetricsQuery & {
+        group_by?: string;
+        event?: "sent" | "delivered" | "bounced" | "complained" | "opened" | "clicked";
+        domain?: string;
+        api_key_id?: string;
+    }) => Promise<Record<string, unknown>>;
+    /** This period's usage per key: budget, consumed, remaining, rate window, last used. */
+    readonly usage: () => Promise<Record<string, unknown>>;
+    readonly account: {
+        /** Lifecycle status, the reason for it, and when the account was created. */
+        get: () => Promise<Record<string, unknown>>;
+        /**
+         * Set the postal address printed in every broadcast footer. `null` clears
+         * it. A broadcast is not sent until the account has one.
+         */
+        update: (payload: {
+            postal_address: string | null;
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+    };
     readonly trust: {
         /** What the platform currently thinks of this account, in a shape an agent can branch on. */
         standing: () => Promise<TrustStanding>;
+        /** The published enforcement thresholds, as numbers. */
+        thresholds: () => Promise<Record<string, unknown>>;
+        /** Appeal the current standing. The reason is recorded verbatim; a person answers by `sla_deadline_at`. */
+        appeal: (reason: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /** The remediation checklist, with what has been ticked. */
+        remediation: () => Promise<Record<string, unknown>>;
+        /** Tick or untick one checklist item. Returns the whole checklist. */
+        setRemediation: (payload: {
+            key: string;
+            done: boolean;
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+    };
+    /**
+     * Sends held for a person to approve, and what they decided. Approving or
+     * rejecting is done in the console; a key can list, never decide.
+     */
+    readonly agentActions: {
+        list: (query?: ListQuery & {
+            before?: string;
+            state?: "pending" | "approved" | "rejected" | "killed";
+        }) => Promise<Page<Record<string, unknown>>>;
+    };
+    /** Conditions this account should know about: a spent budget, a kill switch, a lost domain. */
+    readonly notifications: {
+        list: (query?: ListQuery & {
+            before?: string;
+            state?: "open" | "resolved";
+            unread?: "true" | "false";
+        }) => Promise<Page<Record<string, unknown>>>;
+        read: (id: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        readAll: (options?: RequestOptions) => Promise<Record<string, unknown>>;
+        preferences: () => Promise<Record<string, unknown>>;
+        setPreferences: (preferences: {
+            type: string;
+            email?: boolean;
+            in_app?: boolean;
+        }[], options?: RequestOptions) => Promise<Record<string, unknown>>;
+    };
+    readonly dedicatedIps: {
+        list: (query?: ListQuery) => Promise<Page<Record<string, unknown>>>;
+        /** Provision a dedicated IP. It starts warming on the published curve. */
+        provision: (payload: {
+            ip: string;
+            region: string;
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        release: (id: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /** The published warmup curve: how volume moves, and when. */
+        ramp: () => Promise<Record<string, unknown>>;
+        /** Which route this message would take right now, by the same math the send path uses. */
+        routeDecision: (messageId: string) => Promise<Record<string, unknown>>;
+    };
+    readonly deliverability: {
+        /** Every sending domain with its standing over the window, worst first. */
+        domains: (query?: {
+            window_days?: number;
+        }) => Promise<Record<string, unknown>>;
+        domain: (id: string) => Promise<Record<string, unknown>>;
+        /** Persist today's rates as a snapshot. Idempotent per domain per day. */
+        snapshot: (id: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        /** Aggregate authentication reports: aligned and failing volume per day, and every address sending as you. */
+        dmarc: (query?: {
+            domain?: string;
+            window_days?: number;
+        }) => Promise<Record<string, unknown>>;
     };
     readonly billing: {
         /**
@@ -440,6 +759,8 @@ export declare class AgentiSend {
          * budget comes from Starter; only a signed-in human in the console can buy.
          */
         plan: () => Promise<BillingPlan>;
+        /** Plan, usage against each published limit, and what the next tier changes. Buying stays in the console. */
+        get: () => Promise<Record<string, unknown>>;
     };
 }
 export {};