@mailsai/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,686 @@
+export type ClientOptions = {
+    apiKey?: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+};
+export type Tag = {
+    name: string;
+    value: string;
+};
+export type Attachment = {
+    filename: string;
+    content_base64: string;
+    content_type: string;
+};
+export type SendInput = {
+    to: string | string[];
+    cc?: string[];
+    bcc?: string[];
+    subject: string;
+    body?: string;
+    body_text?: string;
+    body_html?: string;
+    reply_to?: string;
+    in_reply_to_message_id?: string;
+    /** RFC Message-IDs to stitch this message into an existing thread (References header). */
+    references?: string[];
+    /** Up to 10 attachments, base64-encoded. */
+    attachments?: Attachment[];
+    metadata?: Record<string, string>;
+    pool_hint?: "clean" | "mixed";
+    scheduled_at?: string;
+    tags?: Tag[];
+    idempotency_key?: string;
+};
+export type SendResult = {
+    id: string;
+    agent_id: string;
+    thread_id?: string;
+    to: string[];
+    subject: string;
+    routing_pool: "clean" | "mixed" | "outbound";
+    classifier_score: number;
+    status: "queued" | "scheduled" | "sent";
+    cost_usd: number;
+    scheduled_at?: string;
+    tags?: Tag[];
+    created_at: string;
+};
+export type ReplyInput = {
+    body?: string;
+    body_text?: string;
+    body_html?: string;
+    reply_all?: boolean;
+    cc?: string[];
+    bcc?: string[];
+    tags?: Tag[];
+    scheduled_at?: string;
+};
+export type ForwardInput = {
+    to: string | string[];
+    cc?: string[];
+    bcc?: string[];
+    subject?: string;
+    body_text?: string;
+    body_html?: string;
+};
+export type ListResult<T> = {
+    data: T[];
+    has_more: boolean;
+    next_cursor?: string;
+};
+export type TypedEvent = {
+    id: string;
+    /**
+     * Event type. Inbound: `reply.received` (a genuine reply to one of your sends),
+     * `message.received` (an authenticated cold/first-contact inbound — NOT a reply),
+     * `message.received.unauthenticated` (SPF+DKIM both failed). Outbound lifecycle:
+     * `message.sent` / `message.delivered` / `message.bounced` / `message.complained` /
+     * `message.scheduled`. Plus `suppression.added`, `agent.paused`/`agent.resumed`,
+     * and `draft.*`. Use `agent.onReply` for replies and `agent.onMessage` for cold inbound.
+     */
+    type: string;
+    workspace_id: string;
+    agent_id?: string;
+    source_message_id?: string;
+    intent?: string;
+    urgency?: number;
+    injection_score?: number;
+    sender_reputation?: number;
+    /** Routing pool the source message used. Returned by events.list/get. */
+    routing_pool?: "clean" | "mixed" | "outbound";
+    entities?: Record<string, unknown>;
+    /** Only present on SSE stream events for some types; on list/get read `data.thread_id`. */
+    thread_id?: string;
+    test_mode: boolean;
+    data: Record<string, unknown>;
+    created_at: string | null;
+};
+export type AgentRow = {
+    id: string;
+    name: string;
+    email: string;
+    domain: string;
+    workspace_id: string;
+    status: "active" | "paused" | "archived";
+    created_at: string | null;
+};
+export type ThreadRow = {
+    id: string;
+    agent_id: string;
+    subject?: string;
+    last_message_at?: string;
+    message_count: number;
+    participants: string[];
+    labels: string[];
+    status: "open" | "closed" | "archived";
+    created_at: string | null;
+    updated_at: string | null;
+};
+export type ThreadDetail = ThreadRow & {
+    messages: Array<{
+        id: string;
+        direction: "outbound";
+        to: string[];
+        subject: string;
+        snippet: string;
+        status: string;
+        sent_at?: string;
+        scheduled_at?: string;
+        created_at: string | null;
+    } | {
+        id: string;
+        direction: "inbound";
+        from: string;
+        to: string;
+        subject?: string;
+        extracted_text?: string;
+        snippet: string;
+        received_at: string;
+        created_at: string | null;
+    }>;
+};
+export type ReceivedMessage = {
+    id: string;
+    agent_id: string;
+    thread_id?: string;
+    from: {
+        address: string;
+        name?: string;
+    };
+    to: string;
+    subject?: string;
+    extracted_text?: string;
+    body_text_excerpt?: string;
+    spf_pass?: boolean;
+    dkim_pass?: boolean;
+    received_at: string;
+};
+export type DraftRow = {
+    id: string;
+    agent_id: string;
+    to: string[];
+    subject?: string;
+    body_text?: string;
+    body_html?: string;
+    status: "draft" | "scheduled" | "sending" | "sent" | "failed" | "canceled";
+    send_at?: string;
+    sent_message_id?: string;
+    error_message?: string;
+    tags?: Tag[];
+    created_at: string | null;
+    updated_at: string | null;
+};
+export type SuppressionLookup = {
+    suppressed: boolean;
+    type?: "hard_bounce" | "complaint" | "unsubscribe";
+    scope?: string;
+    since?: string;
+    allowed?: {
+        id: string;
+        attestation: string;
+        created_at: string;
+    };
+};
+export type ApiKeyRow = {
+    id: string;
+    prefix: string;
+    name: string | null;
+    mode: "live" | "test";
+    scopes: string[];
+    agent_id: string | null;
+    last_used_at: string | null;
+    expires_at: string | null;
+    revoked_at: string | null;
+    created_at: string | null;
+};
+export type WebhookRow = {
+    id: string;
+    url: string;
+    event_types: string[];
+    description: string | null;
+    active: boolean;
+    created_at: string | null;
+};
+export type WebhookDelivery = {
+    id: string;
+    webhook_endpoint_id: string;
+    event_id: string;
+    attempt_number: number;
+    status: "pending" | "succeeded" | "failed" | "dlq";
+    http_status?: number;
+    response_body_excerpt?: string;
+    next_retry_at?: string;
+    delivered_at?: string;
+    created_at: string | null;
+};
+export type LogEntry = {
+    id: string;
+    category: string;
+    action: string;
+    target_resource_id?: string;
+    metadata?: Record<string, unknown>;
+    created_at: string | null;
+};
+export type MeResult = {
+    api_key: {
+        id: string;
+        prefix?: string;
+        name: string | null;
+        mode: "live" | "test";
+        scopes: string[];
+        agent_id: string | null;
+        last_used_at: string | null;
+        created_at: string | null;
+    };
+    workspace: {
+        id: string;
+        slug: string;
+        display_name: string;
+        tier: string;
+        tier_status: string;
+    } | null;
+    agent: {
+        id: string;
+        name: string;
+        email: string;
+    } | null;
+};
+export type UsageResult = {
+    workspace_id: string;
+    tier: string;
+    tier_status: string;
+    period_start: string;
+    period_end: string;
+    usage: {
+        sends: number;
+        parses: number;
+        webhook_deliveries: number;
+        sends_cost_usd: number;
+        parses_cost_usd: number;
+    };
+    caps: {
+        monthly_sends: number;
+        monthly_parses: number;
+        agents: number | "unlimited";
+        hourly: number;
+        daily: number;
+    };
+};
+declare class MailsError extends Error {
+    type: string;
+    code: string;
+    status: number;
+    requestId?: string;
+    param?: string;
+    constructor(opts: {
+        type: string;
+        code: string;
+        message: string;
+        status: number;
+        requestId?: string;
+        param?: string;
+    });
+}
+declare class MailsClient {
+    private apiKey;
+    private baseUrl;
+    private fetchImpl;
+    messages: MessagesResource;
+    received: ReceivedResource;
+    threads: ThreadsResource;
+    drafts: DraftsResource;
+    events: EventsResource;
+    agents: AgentsResource;
+    suppression: SuppressionResource;
+    api_keys: ApiKeysResource;
+    webhooks: WebhooksResource;
+    reputation: ReputationResource;
+    billing: BillingResource;
+    logs: LogsResource;
+    constructor(opts?: ClientOptions);
+    agent(name: string): Agent;
+    send(agent: string, input: SendInput): Promise<SendResult>;
+    createAgent(name: string, options?: {
+        domain?: string;
+        allowlist_domains?: string[];
+    }): Promise<AgentRow>;
+    listAgents(opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<ListResult<AgentRow>>;
+    me(): Promise<MeResult>;
+    request<T = unknown>(method: string, path: string, body?: unknown, headersIn?: Record<string, string>): Promise<T>;
+    private _request;
+    requestText(method: string, path: string, body?: unknown, headersIn?: Record<string, string>): Promise<string>;
+    stream(opts: {
+        since?: string;
+        event_types?: string[];
+        onEvent: (e: TypedEvent) => void;
+        onError?: (err: Error) => void;
+        signal?: AbortSignal;
+    }): AbortController;
+}
+declare class MessagesResource {
+    private c;
+    constructor(c: MailsClient);
+    send(agent: string, input: SendInput): Promise<SendResult>;
+    batch(messages: Array<Omit<SendInput, "idempotency_key"> & {
+        agent: string;
+    }>, opts?: {
+        idempotency_key?: string;
+    }): Promise<{
+        data: Array<SendResult | {
+            error: {
+                type: string;
+                code: string;
+                message: string;
+            };
+        }>;
+        batch_size: number;
+    }>;
+    reply(id: string, input: ReplyInput): Promise<SendResult & {
+        in_reply_to_message_id: string;
+    }>;
+    forward(id: string, input: ForwardInput): Promise<SendResult & {
+        forwarded_from: string;
+    }>;
+    cancel(id: string): Promise<{
+        id: string;
+        status: "canceled";
+        canceled_at: string;
+    }>;
+    reschedule(id: string, scheduled_at: string): Promise<{
+        id: string;
+        scheduled_at: string;
+        status: "scheduled";
+    }>;
+    raw(id: string): Promise<string>;
+    list(opts?: {
+        limit?: number;
+        cursor?: string;
+        agent_id?: string;
+        thread_id?: string;
+    }): Promise<ListResult<SendResult>>;
+    get(id: string): Promise<SendResult>;
+}
+declare class ReceivedResource {
+    private c;
+    constructor(c: MailsClient);
+    list(opts?: {
+        limit?: number;
+        cursor?: string;
+        agent_id?: string;
+        thread_id?: string;
+    }): Promise<ListResult<ReceivedMessage>>;
+    get(id: string): Promise<ReceivedMessage & {
+        raw_url: string;
+    }>;
+}
+declare class ThreadsResource {
+    private c;
+    constructor(c: MailsClient);
+    list(opts?: {
+        limit?: number;
+        cursor?: string;
+        agent_id?: string;
+        status?: "open" | "closed" | "archived";
+    }): Promise<ListResult<ThreadRow>>;
+    get(id: string): Promise<ThreadDetail>;
+    update(id: string, patch: {
+        labels?: string[];
+        status?: "open" | "closed" | "archived";
+    }): Promise<ThreadRow>;
+}
+declare class DraftsResource {
+    private c;
+    constructor(c: MailsClient);
+    create(input: {
+        agent: string;
+        to: string | string[];
+        cc?: string[];
+        bcc?: string[];
+        subject?: string;
+        body_text?: string;
+        body_html?: string;
+        reply_to?: string;
+        in_reply_to_message_id?: string;
+        send_at?: string;
+        tags?: Tag[];
+    }): Promise<DraftRow>;
+    list(opts?: {
+        limit?: number;
+        cursor?: string;
+        status?: string;
+    }): Promise<ListResult<DraftRow>>;
+    get(id: string): Promise<DraftRow>;
+    update(id: string, patch: Record<string, unknown>): Promise<DraftRow>;
+    remove(id: string): Promise<{
+        id: string;
+        deleted_at: string;
+    }>;
+    send(id: string, opts?: {
+        send_at?: string;
+    }): Promise<{
+        id: string;
+        status: string;
+        message_id?: string;
+        thread_id?: string;
+        sent_at?: string;
+        send_at?: string;
+    }>;
+}
+declare class EventsResource {
+    private c;
+    constructor(c: MailsClient);
+    list(opts?: {
+        limit?: number;
+        cursor?: string;
+        event_type?: string;
+        agent_id?: string;
+        since?: string;
+    }): Promise<ListResult<TypedEvent>>;
+    get(id: string): Promise<TypedEvent>;
+    redeliver(id: string): Promise<{
+        event_id: string;
+        webhook_endpoint_ids: string[];
+        scheduled_at: string;
+    }>;
+    stream(opts: {
+        since?: string;
+        event_types?: string[];
+        onEvent: (e: TypedEvent) => void;
+        onError?: (err: Error) => void;
+    }): AbortController;
+}
+declare class AgentsResource {
+    private c;
+    constructor(c: MailsClient);
+    create(name: string, opts?: {
+        domain?: string;
+        allowlist_domains?: string[];
+        blocklist_domains?: string[];
+        /**
+         * Run the costed LLM intent/entity extractor on this agent's inbound. The
+         * prompt-injection scan ALWAYS runs regardless; this only gates the extra
+         * classification pass (the metered "classify (opt-in)"). Default false.
+         */
+        classify_inbound?: boolean;
+    }): Promise<AgentRow>;
+    list(opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<ListResult<AgentRow>>;
+    get(id: string): Promise<AgentRow>;
+    update(id: string, patch: {
+        status?: "active" | "paused";
+        daily_send_limit?: number | null;
+        hourly_send_limit?: number | null;
+        allowlist_domains?: string[];
+        blocklist_domains?: string[];
+        classify_inbound?: boolean;
+    }): Promise<AgentRow>;
+    archive(id: string): Promise<{
+        id: string;
+        status: string;
+        archived_at: string;
+    }>;
+}
+declare class SuppressionResource {
+    private c;
+    constructor(c: MailsClient);
+    check(address: string): Promise<SuppressionLookup>;
+    list(opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<ListResult<{
+        id: string;
+        address: string;
+        attestation: string;
+        created_at: string;
+    }>>;
+    allow(address: string, attestation: string): Promise<{
+        id: string;
+        address: string;
+        attestation: string;
+        created_at: string;
+    }>;
+    revoke(id: string): Promise<{
+        id: string;
+        revoked_at: string;
+    }>;
+}
+declare class ApiKeysResource {
+    private c;
+    constructor(c: MailsClient);
+    create(input: {
+        name?: string;
+        agent_id?: string;
+        scopes?: ("send" | "read" | "manage")[];
+        mode?: "live" | "test";
+        expires_at?: string;
+    }): Promise<ApiKeyRow & {
+        key: string;
+    }>;
+    list(opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<ListResult<ApiKeyRow>>;
+    revoke(id: string): Promise<{
+        id: string;
+        revoked_at: string;
+    }>;
+}
+declare class WebhooksResource {
+    private c;
+    constructor(c: MailsClient);
+    create(input: {
+        url: string;
+        event_types?: string[];
+        description?: string;
+    }): Promise<WebhookRow & {
+        signing_secret: string;
+    }>;
+    list(opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<ListResult<WebhookRow>>;
+    update(id: string, patch: {
+        url?: string;
+        event_types?: string[];
+        description?: string;
+        active?: boolean;
+    }): Promise<WebhookRow>;
+    /** Send a signed test event to the endpoint to verify reachability + signature handling. */
+    test(id: string): Promise<{
+        ok: boolean;
+        http_status?: number;
+        error?: string;
+    }>;
+    remove(id: string): Promise<{
+        id: string;
+        deleted_at: string;
+    }>;
+    deliveries(webhookId: string, opts?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<ListResult<WebhookDelivery>>;
+    replayDelivery(deliveryId: string): Promise<{
+        delivery_id: string;
+        event_id: string;
+        scheduled: string[];
+        scheduled_at: string;
+    }>;
+    verify(body: string, signature: string, secret: string, toleranceSec?: number): TypedEvent | null;
+}
+declare class ReputationResource {
+    private c;
+    constructor(c: MailsClient);
+    get(agentId?: string): Promise<{
+        agent_id?: string;
+        workspace_id?: string;
+        reputation: number;
+        send_count_30d?: number;
+        bounce_count_30d?: number;
+        complaint_count_30d?: number;
+        reply_count_30d?: number;
+    }>;
+}
+declare class BillingResource {
+    private c;
+    constructor(c: MailsClient);
+    portal(returnUrl?: string): Promise<{
+        url: string;
+        mock: boolean;
+    }>;
+    usage(): Promise<UsageResult>;
+}
+declare class LogsResource {
+    private c;
+    constructor(c: MailsClient);
+    list(opts?: {
+        limit?: number;
+        cursor?: string;
+        category?: string;
+        action?: string;
+    }): Promise<ListResult<LogEntry>>;
+}
+declare class Agent {
+    private client;
+    private name;
+    private _id?;
+    constructor(client: MailsClient, name: string);
+    send(input: SendInput): Promise<SendResult>;
+    listReplies(opts?: {
+        limit?: number;
+        since?: string;
+    }): Promise<ListResult<TypedEvent>>;
+    /**
+     * List cold/first-contact inbound (`message.received`) for this agent — messages
+     * from senders that are NOT replies to one of your sends (new leads, support
+     * requests, strangers). Authenticated only; SPF+DKIM failures surface separately
+     * as `message.received.unauthenticated`. Mirrors {@link listReplies}.
+     */
+    listMessages(opts?: {
+        limit?: number;
+        since?: string;
+    }): Promise<ListResult<TypedEvent>>;
+    reputation(): Promise<{
+        agent_id?: string;
+        workspace_id?: string;
+        reputation: number;
+        send_count_30d?: number;
+        bounce_count_30d?: number;
+        complaint_count_30d?: number;
+        reply_count_30d?: number;
+    }>;
+    /**
+     * Subscribe to reply.received events for this agent. Opens an SSE stream
+     * filtered server-side to reply.received and dispatches to `callback` for
+     * events matching this agent. Resolves the agent name → id once on first
+     * matching event so subsequent events skip the lookup.
+     *
+     * @returns AbortController — call `.abort()` to stop listening. Caller can
+     *   also pass `opts.signal` to chain into an existing abort flow.
+     *
+     * @example
+     *   const ctrl = agent.onReply((event) => {
+     *     console.log(event.intent, event.entities);
+     *   });
+     *   // …later
+     *   ctrl.abort();
+     */
+    onReply(callback: (event: TypedEvent) => void | Promise<void>, opts?: {
+        onError?: (err: Error) => void;
+        since?: string;
+        signal?: AbortSignal;
+    }): AbortController;
+    /**
+     * Subscribe to cold/first-contact inbound (`message.received`) for this agent —
+     * new senders that are NOT replying to one of your sends. Same shape and
+     * agent-scoping as {@link onReply}; returns an AbortController.
+     *
+     * @example
+     *   const ctrl = agent.onMessage((event) => {
+     *     if (event.intent === "sales_inquiry") routeToCrm(event);
+     *   });
+     */
+    onMessage(callback: (event: TypedEvent) => void | Promise<void>, opts?: {
+        onError?: (err: Error) => void;
+        since?: string;
+        signal?: AbortSignal;
+    }): AbortController;
+    /** Shared agent-scoped SSE subscription used by onReply/onMessage. */
+    private subscribe;
+    private resolveId;
+}
+export declare function createClient(opts?: ClientOptions): MailsClient;
+export declare const mails: {
+    agent(name: string, opts?: ClientOptions): Agent;
+    send(agent: string, input: SendInput, opts?: ClientOptions): Promise<SendResult>;
+    webhooks: {
+        verify(body: string, signature: string, secret: string, toleranceSec?: number): TypedEvent | null;
+    };
+};
+export { MailsClient, Agent, MailsError };
+//# sourceMappingURL=index.d.ts.map