@agentisend/sdk-node 0.1.0

package/dist/client.d.ts

@@ -0,0 +1,426 @@
+import type { ApiKey, AutomationRun, ReceivedAttachment, ReceivedEmail, SentAttachment, RequestLogEntry, EventDefinition, EventFieldType, ApiKeyPermission, BatchItemResult, CreatedApiKey, CreatedWebhookEndpoint, DeadLetter, Deleted, Domain, DomainRegion, LegacyDomainRegion, Email, EventType, Limit, LimitPeriod, ListEmailsQuery, ListQuery, 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;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}
+export type FetchLike = (url: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+}) => Promise<FetchResponse>;
+export interface ClientOptions {
+    /** Defaults to AGENTISEND_BASE_URL, then https://api.agentisend.com. */
+    baseUrl?: string;
+    /** Injected for tests and for runtimes without a global fetch. */
+    fetch?: FetchLike;
+    timeoutMs?: number;
+    userAgent?: string;
+}
+export interface RequestOptions {
+    /**
+     * Makes a mutating call safe to retry: the same key with the same body
+     * replays the original response instead of doing the work twice. Supported on
+     * EVERY mutating endpoint, not just sends.
+     */
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Build an idempotency key in the shape that debugs well: `<what>/<which>`,
+ * e.g. `welcome-email/user_123`. Stable across retries by construction, because
+ * it is derived from the thing being done rather than from the moment.
+ */
+export declare function idempotencyKey(action: string, subject: string | number): string;
+interface RawRequest {
+    method: string;
+    path: string;
+    query?: Record<string, string | number | undefined>;
+    body?: unknown;
+    options?: RequestOptions;
+}
+/**
+ * A thin typed client. It adds authentication, JSON, the idempotency header and
+ * error shaping — and nothing else. Everything it can do is something the HTTP
+ * API can do, which is the property that lets an agent use either one.
+ */
+export declare class AgentiSend {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    private readonly userAgent;
+    constructor(apiKey?: string, options?: ClientOptions);
+    request<T>(raw: RawRequest): Promise<T>;
+    readonly emails: {
+        send: (payload: SendEmailPayload, options?: RequestOptions) => Promise<{
+            id: string;
+        }>;
+        /** Up to 500 items. Each one succeeds or fails on its own — read data[i].status. */
+        batch: (payloads: SendEmailPayload[], options?: RequestOptions) => Promise<{
+            data: BatchItemResult[];
+        }>;
+        get: (id: string) => Promise<Email>;
+        list: (query?: ListEmailsQuery) => Promise<Page<Email>>;
+        /** M5.10 — what this email carried, after it was sent. */
+        attachments: (id: string) => Promise<Page<SentAttachment>>;
+        /** Stop a scheduled or queued email. Sent mail is history, not cancellable. */
+        cancel: (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<{
+            id: string;
+            status: string;
+            scheduled_at: string;
+        }>;
+        /**
+         * What happened to one message and the calls that fix it — each action
+         * carries the method, path and body to send, so remediation is executed
+         * rather than interpreted.
+         */
+        explain: (id: string) => Promise<ExplainReport>;
+        /** Run every gate without sending or spending. Free, always. */
+        preflight: (payload: SendEmailPayload) => Promise<PreflightReport>;
+        /**
+         * Move a scheduled email. The same act as `reschedule`, under the verb a
+         * Resend integration already calls (M5.5).
+         */
+        update: (id: string, payload: {
+            scheduled_at: string;
+        }, options?: RequestOptions) => Promise<{
+            id: string;
+            status: string;
+            scheduled_at: string;
+        }>;
+    };
+    readonly apiKeys: {
+        create: (payload: {
+            name: string;
+            permission: ApiKeyPermission;
+            domain_scope?: string | null;
+        }, options?: RequestOptions) => Promise<CreatedApiKey>;
+        list: (query?: ListQuery) => Promise<Page<ApiKey>>;
+        /** Rename or re-scope a key. The token is unchanged (M5.5). */
+        update: (id: string, payload: {
+            name?: string;
+            domain_scope?: string | null;
+            scopes?: string[];
+        }, options?: RequestOptions) => Promise<ApiKey>;
+        delete: (id: string, options?: RequestOptions) => Promise<Deleted>;
+    };
+    readonly domains: {
+        create: (payload: {
+            name: string;
+            region?: DomainRegion | LegacyDomainRegion;
+            tracking?: boolean;
+            tracking_subdomain?: string;
+        }, options?: RequestOptions) => Promise<Domain>;
+        list: (query?: ListQuery) => Promise<Page<Domain>>;
+        get: (id: string) => Promise<Domain>;
+        verify: (id: string, options?: RequestOptions) => Promise<Domain>;
+        /** A8 + P3b: click/open tracking, or a new tracking_subdomain. Never removed. */
+        update: (id: string, payload: {
+            click_tracking?: boolean;
+            open_tracking?: boolean;
+            tracking_subdomain?: string;
+        }, options?: RequestOptions) => Promise<Domain>;
+        delete: (id: string, options?: RequestOptions) => Promise<Deleted>;
+    };
+    readonly webhooks: {
+        create: (payload: {
+            url: string;
+            events?: EventType[];
+            svix_compat?: boolean;
+        }, options?: RequestOptions) => Promise<CreatedWebhookEndpoint>;
+        list: (query?: ListQuery) => Promise<Page<WebhookEndpoint>>;
+        get: (id: string) => Promise<WebhookEndpoint>;
+        update: (id: string, payload: {
+            url?: string;
+            events?: EventType[];
+            disabled?: boolean;
+            svix_compat?: boolean;
+        }, options?: RequestOptions) => Promise<WebhookEndpoint>;
+        delete: (id: string, options?: RequestOptions) => Promise<Deleted>;
+        /** Re-send past events. Pass `since`, `event_id`, or both. */
+        replay: (id: string, range: {
+            since?: string;
+            event_id?: string;
+        }, options?: RequestOptions) => Promise<ReplayResult>;
+        deadLetters: (id: string, query?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<DeadLetter>>;
+    };
+    readonly limits: {
+        list: (query?: ListQuery) => Promise<Page<Limit>>;
+        get: (apiKeyId: string) => Promise<Limit>;
+        update: (apiKeyId: string, payload: {
+            budget_per_period?: number | null;
+            period?: LimitPeriod;
+            rate_ceiling_per_minute?: number | null;
+        }, options?: RequestOptions) => Promise<Limit>;
+        /** 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>;
+    };
+    /** M5.5 — the rest of the verb surface a Resend integration calls. */
+    /**
+     * M5.9 — what this account called, and what came back. The two filters that
+     * make a log useful: a date range and a status.
+     */
+    readonly logs: {
+        list: (query?: ListQuery & {
+            since?: string;
+            until?: string;
+            status?: number;
+            status_class?: "2xx" | "4xx" | "5xx";
+            method?: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
+            route?: string;
+            error_code?: string;
+            api_key_id?: string;
+        }) => Promise<Page<RequestLogEntry>>;
+        get: (id: string) => Promise<RequestLogEntry>;
+    };
+    /**
+     * M5.8 — mail sent TO your domains. Bodies come back as strings exactly as
+     * they arrived; nothing here renders or executes them.
+     */
+    readonly receiving: {
+        list: (query?: ListQuery & {
+            to?: string;
+            from?: string;
+            since?: string;
+            until?: string;
+        }) => Promise<Page<ReceivedEmail>>;
+        get: (id: string) => Promise<ReceivedEmail>;
+        attachments: (id: string) => Promise<Page<ReceivedAttachment>>;
+    };
+    /**
+     * M5.7 — the custom-event registry. Declaring an event's fields turns a
+     * mistyped payload from a silent 202 into a 400 that names the field.
+     */
+    readonly events: {
+        ingest: (payload: {
+            name: string;
+            contact_id?: string;
+            data?: Record<string, unknown>;
+        }, options?: RequestOptions) => Promise<{
+            fired: number;
+        }>;
+        list: (query?: ListQuery) => Promise<Page<EventDefinition>>;
+        get: (id: string) => Promise<EventDefinition>;
+        update: (id: string, payload: {
+            description?: string | null;
+            schema?: Record<string, EventFieldType>;
+            strict?: boolean;
+        }, options?: RequestOptions) => Promise<EventDefinition>;
+        delete: (id: string, options?: RequestOptions) => Promise<Deleted>;
+    };
+    /** M5.6 — what an automation actually did, after it did it. */
+    readonly automations: {
+        create: (payload: {
+            name: string;
+            trigger: Record<string, unknown>;
+            steps: Record<string, unknown>[];
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        list: (query?: ListQuery) => Promise<Page<Record<string, unknown>>>;
+        get: (id: string) => Promise<Record<string, unknown>>;
+        update: (id: string, payload: Record<string, unknown>, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        enable: (id: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        disable: (id: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        versions: (id: string) => Promise<Page<Record<string, unknown>>>;
+        runs: (automationId: string, query?: ListQuery & {
+            status?: "running" | "succeeded" | "failed";
+        }) => Promise<Page<AutomationRun>>;
+        run: (automationId: string, runId: string) => Promise<AutomationRun>;
+    };
+    /**
+     * M5.29 — the rest of each group.
+     *
+     * M5.5 filled the verbs a Resend integration calls and left the groups
+     * half-built: `contacts` could update but not create, `templates` could
+     * duplicate but not publish. A client that answers four of a resource's six
+     * verbs sends the caller back to raw fetch for the other two, which is the
+     * same as having none.
+     */
+    readonly contacts: {
+        create: (payload: {
+            email: string;
+            properties?: Record<string, unknown>;
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        list: (query?: ListQuery & {
+            email?: string;
+        }) => Promise<Page<Record<string, unknown>>>;
+        get: (id: string) => Promise<Record<string, unknown>>;
+        delete: (id: string, options?: RequestOptions) => Promise<Deleted>;
+        /** Edit by id. Properties merge; an explicit null removes one. */
+        update: (id: string, payload: {
+            email?: string;
+            status?: "active" | "unsubscribed";
+            properties?: Record<string, unknown>;
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+    };
+    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>>;
+        update: (id: string, payload: Record<string, unknown>, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        send: (id: 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: (id: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
+    };
+    readonly templates: {
+        create: (payload: {
+            name: string;
+            subject: string;
+            content: unknown;
+            variables?: unknown[];
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        list: (query?: ListQuery) => Promise<Page<Record<string, unknown>>>;
+        get: (id: string) => Promise<Record<string, unknown>>;
+        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: string;
+        }>;
+        versions: (id: string) => Promise<Page<Record<string, unknown>>>;
+        /** Copy a template into a fresh editable draft, history not included. */
+        duplicate: (id: string, payload?: {
+            name?: string;
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+    };
+    readonly suppressions: {
+        list: (query?: ListQuery) => Promise<Page<Record<string, unknown>>>;
+        add: (payload: {
+            email: string;
+            level?: "address" | "domain";
+        }, 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<{
+            data: SuppressionBatchItem[];
+        }>;
+        batchRemove: (emails: string[], options?: RequestOptions) => Promise<{
+            data: SuppressionBatchItem[];
+        }>;
+    };
+    /**
+     * F6 — segments are rule-based and evaluated live, so `members` is the
+     * current answer rather than a stored list that drifts.
+     */
+    readonly segments: {
+        create: (payload: {
+            name: string;
+            rules?: Record<string, unknown>[];
+        }, options?: RequestOptions) => Promise<Record<string, unknown>>;
+        list: (query?: ListQuery) => Promise<Page<Record<string, unknown>>>;
+        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>;
+        members: (id: string) => Promise<Page<Record<string, unknown>>>;
+    };
+    /**
+     * M4.9 — this account's own history. `action` takes a family (`api_key`) or
+     * an exact name (`api_key.rotated`); `from`/`to` are ISO instants.
+     */
+    readonly auditLog: {
+        list: (query?: ListQuery & {
+            actor?: string;
+            action?: string;
+            from?: string;
+            to?: string;
+        }) => Promise<Page<AuditEntry>>;
+    };
+    /**
+     * M4.8 — team, roles and invites. Three roles where Resend has two, and
+     * seats that are capped by plan and never billed per seat.
+     */
+    readonly team: {
+        /** Your own role on this account, and what the plan allows. */
+        me: () => Promise<{
+            user_id: string | null;
+            email: string | null;
+            role: "owner" | "admin" | "viewer" | null;
+            seats: {
+                plan: string;
+                used: number;
+                limit: number;
+                billed_per_seat: false;
+            };
+        }>;
+        listMembers: (query?: ListQuery) => Promise<Page<TeamMember>>;
+        setRole: (id: string, role: "owner" | "admin" | "viewer", options?: RequestOptions) => Promise<TeamMember>;
+        removeMember: (id: string, options?: RequestOptions) => Promise<{
+            id: string;
+            removed: true;
+        }>;
+        listInvites: (query?: ListQuery) => Promise<Page<TeamInvite>>;
+        /** Membership starts when they accept, so this returns the pending invitation. */
+        invite: (payload: {
+            email: string;
+            role?: "owner" | "admin" | "viewer";
+        }, options?: RequestOptions) => Promise<TeamInvite>;
+        cancelInvite: (id: string, options?: RequestOptions) => Promise<{
+            id: string;
+            cancelled: true;
+        }>;
+        /** Needs a signed-in session as the invited address, not an API key. */
+        acceptInvite: (token: string, options?: RequestOptions) => Promise<{
+            account_id: string;
+            account_name: string;
+            role: "owner" | "admin" | "viewer";
+            member_id: string;
+        }>;
+    };
+    /**
+     * M5.4 — subscription topics. A topic is what `topic_id` on a send names,
+     * and what the one-click header on that send turns off.
+     */
+    readonly topics: {
+        create: (payload: {
+            name: string;
+            description?: string;
+            default_subscribed?: boolean;
+        }, options?: RequestOptions) => Promise<Topic>;
+        list: (query?: ListQuery) => Promise<Page<Topic>>;
+        get: (id: string) => Promise<Topic>;
+        update: (id: string, payload: {
+            name?: string;
+            description?: string | null;
+            default_subscribed?: boolean;
+        }, options?: RequestOptions) => Promise<Topic>;
+        delete: (id: string, options?: RequestOptions) => Promise<Deleted>;
+        /** Every topic with this contact's standing on it. */
+        forContact: (contactId: string) => Promise<Page<ContactTopic>>;
+        /** Record answers. Absolute — nothing is inferred from what is left out. */
+        setForContact: (contactId: string, topics: {
+            topic_id: string;
+            subscribed: boolean;
+        }[], options?: RequestOptions) => Promise<Page<ContactTopic>>;
+    };
+    /** Public per-component health — the same document the status page renders. */
+    readonly status: () => Promise<ServiceStatus>;
+    readonly trust: {
+        /** What the platform currently thinks of this account, in a shape an agent can branch on. */
+        standing: () => Promise<TrustStanding>;
+    };
+    readonly billing: {
+        /**
+         * The plan this key's account runs under: tier, entitlements, subscription
+         * state, and what can be bought. Read-only by design — a key can learn its
+         * budget comes from Starter; only a signed-in human in the console can buy.
+         */
+        plan: () => Promise<BillingPlan>;
+    };
+}
+export {};