@pidgeon-ai/sdk 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -72,10 +72,79 @@ interface Thread {
     subject: string | null;
     status: 'open' | 'waiting' | 'resolved' | 'human_review';
     owner_type: 'human' | 'automation' | 'agent';
+    /**
+     * Which person is answering. Null is the unassigned queue.
+     *
+     * It composes with `owner_type` rather than replacing it: that says which
+     * *kind* of thing is answering, and this says which human. A thread with
+     * `status: 'human_review'` and no assignee is a handover nobody has taken.
+     */
+    assignee_id: string | null;
+    assigned_at: string | null;
     message_count: number;
     last_message_at: string | null;
     created_at: string;
 }
+/**
+ * A person in the workspace, for assigning conversations to.
+ *
+ * No avatar: it is a pointer at an image on somebody else's host, and an
+ * integration has no use for one.
+ */
+/**
+ * One folder of a mailbox, and what is in it.
+ *
+ * Null rather than zero where the product does not count that folder — zero
+ * would be a claim, and the counts query answers what a sidebar needs rather
+ * than everything that could be counted.
+ */
+interface Mailbox {
+    folder: 'inbox' | 'starred' | 'sent' | 'drafts' | 'scheduled' | 'snoozed' | 'archive' | 'spam' | 'trash';
+    total: number | null;
+    unread: number | null;
+}
+/**
+ * A conversation in a folder listing — the newest message in each thread.
+ *
+ * Deliberately not a `Message`: it has no body, because a list of forty
+ * conversations does not want forty bodies. `GET /messages?thread_id=` opens
+ * one.
+ */
+interface MessageListItem {
+    id: string;
+    thread_id: string;
+    direction: string;
+    /** Who the row is about: the sender in inbox, the recipient in sent. */
+    from: string;
+    from_name: string;
+    subject: string | null;
+    preview: string | null;
+    is_read: boolean;
+    is_starred: boolean;
+    is_draft: boolean;
+    is_spam: boolean;
+    has_attachments: boolean;
+    attachment_count: number;
+    message_count: number;
+    assignee_id: string | null;
+    timestamp: string;
+}
+/** Every state change the API can apply to a conversation. */
+type MessageActionName = 'read' | 'unread' | 'star' | 'unstar' | 'archive' | 'unarchive' | 'delete' | 'restore' | 'spam' | 'not_spam' | 'delete_forever';
+/** A file uploaded ahead of a send. Expires in a day if never used. */
+interface UploadedAttachment {
+    id: string;
+    filename: string;
+    content_type: string;
+    size: number;
+}
+interface Member {
+    id: string;
+    email: string;
+    name: string | null;
+    role: 'owner' | 'member';
+    joined_at: string;
+}
 interface Webhook {
     id: string;
     url: string;
@@ -97,18 +166,113 @@ interface Event {
     data: Record<string, unknown>;
     created_at: string;
 }
+/**
+ * Where mail to an address goes.
+ *
+ * An address resolves in one of three ways and the first match wins: it *is*
+ * an address of its own, a rule points it somewhere, or the domain's
+ * catch-all takes it. So a rule never overrides a real address — creating one
+ * for an address that already exists is refused rather than silently ignored.
+ */
 interface RoutingRule {
     id: string;
-    /** The address or pattern this rule matches. */
+    /** The address this rule matches, or `*@domain` for the catch-all. */
     match: string;
-    /** `exact` for an address, `catch_all` for the domain's fallback. */
-    match_type: string;
+    /** `address` for one address, `catch_all` for the domain's fallback. */
+    match_type: 'address' | 'catch_all';
     /** `identity` for an inbox, `webhook` for a URL. */
-    destination_type: string;
+    destination_type: 'identity' | 'webhook';
+    /** The address or the endpoint URL — what to show somebody. */
     destination: string;
-    status: string;
+    /** The id of that address or endpoint — what to pass back. */
+    destination_id: string | null;
+    /** `disabled` keeps the rule and stops it firing. */
+    status: 'active' | 'disabled';
     domain: string;
+    domain_id: string;
+    created_at: string;
+}
+/**
+ * One attempt to hand an event to one endpoint.
+ *
+ * `status` is ours: `pending` is queued, `sending` is in flight, `delivered`
+ * succeeded, `failed` is still being retried and `dead` has stopped being.
+ * `response_status` is your server's answer, where there was one — a network
+ * failure leaves it null and puts the reason in `error`.
+ */
+interface Delivery {
+    id: string;
+    event_id: string;
+    event_type: string;
+    status: string;
+    attempts: number;
+    /** The HTTP status your endpoint answered with, or null if it did not. */
+    response_status: number | null;
+    error: string | null;
     created_at: string;
+    delivered_at: string | null;
+}
+/**
+ * A key, as a record. Never the secret — that is returned once, on create.
+ *
+ * `identity_ids` is the key's scope: the addresses it reaches, and the
+ * ceiling on what a key it mints may reach.
+ */
+interface ApiKey {
+    id: string;
+    name: string;
+    /** Enough to recognise it in a list. Not enough to use. */
+    prefix: string;
+    identity_ids: string[];
+    /** The key that minted this one, where a key did. */
+    created_by_key_id: string | null;
+    last_used_at: string | null;
+    revoked_at: string | null;
+    created_at: string;
+}
+/**
+ * A credential for one mailbox, over IMAP and SMTP.
+ *
+ * The secret comes back once, on create, as `password` — grouped for typing
+ * into a mail client — beside the `username` it must be paired with. A
+ * password presented for the wrong address is a failed login.
+ */
+interface AppPassword {
+    id: string;
+    name: string;
+    prefix: string;
+    last_used_at: string | null;
+    revoked_at: string | null;
+    created_at: string;
+}
+/**
+ * One DNS record a domain needs, and whether it is published yet.
+ *
+ * `status` is `connected` when it is right, `waiting` when nothing is there,
+ * `incorrect` when something else is, and `not_required` for a record this
+ * provider does not need. `found` is what we actually read — a record with
+ * the right name and the wrong value looks identical to a missing one until
+ * you can see it.
+ */
+interface DnsRecord {
+    /** `ownership`, `mx`, `spf`, `dkim` or `dmarc`. */
+    type: string;
+    /** `TXT`, `MX` or `CNAME`. */
+    record_type: string;
+    name: string;
+    value: string;
+    priority: number | null;
+    status: 'connected' | 'waiting' | 'incorrect' | 'not_required';
+    found: string | null;
+    /** One sentence, written for the person who has to publish it. */
+    description: string;
+    checked_at: string | null;
+}
+interface Workspace {
+    id: string;
+    name: string;
+    plan: string;
+    status: string;
 }
 interface Domain {
     id: string;
@@ -130,7 +294,34 @@ interface Page<T> {
     data: T[];
     has_more: boolean;
     next_cursor: string | null;
+    /**
+     * Where a delta should start, on the listings that support one.
+     *
+     * Keep it when you finish the initial load and hand it to
+     * `mailboxes.changes`. It is taken before the rows are read, so anything
+     * that changed while you were paging comes back in the first delta rather
+     * than falling into the gap.
+     */
+    sync_cursor?: string;
 }
+/**
+ * One thing that happened to a mailbox since a cursor.
+ *
+ * A change carries the whole conversation, in the same shape a listing row
+ * has — so a client holds one type rather than two. A deletion carries the
+ * id and nothing else, because there is nothing else left: the message is
+ * gone, and a record of what it said would make "delete" mean "delete most
+ * of it".
+ */
+type MailboxChange = ({
+    deleted: false;
+    folder: Mailbox['folder'];
+    changed_at: string;
+} & MessageListItem) | {
+    deleted: true;
+    id: string;
+    changed_at: string;
+};
 
 /**
  * The Pidgeon client.
@@ -168,7 +359,21 @@ declare class Pidgeon {
     #private;
     constructor(options: PidgeonOptions);
     identities: {
-        list: () => Promise<Identity[]>;
+        /**
+         * A page of addresses, alphabetically.
+         *
+         * `cursor` is the last address on the page before it, not a timestamp —
+         * this is the one list that is not ordered by time, because it is read
+         * by somebody looking for a particular address.
+         *
+         * It returned every address and no page before this, which made
+         * `const { data } = await pidgeon.identities.list()` — the line in our
+         * own quickstart — resolve to `undefined`.
+         */
+        list: (options?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Identity>>;
         get: (id: string) => Promise<Identity>;
         create: (input: {
             domain_id: string;
@@ -192,6 +397,66 @@ declare class Pidgeon {
         listInThread: (threadId: string, options?: {
             limit?: number;
         }) => Promise<Page<Message>>;
+        /**
+         * Change one conversation: read, starred, or which folder it is in.
+         *
+         * Returns an `undo` you can hand to `messages.undo`.
+         */
+        update: (id: string, input: {
+            /**
+             * Readable, and **not writable with an API key**. Read state belongs
+             * to a person; setting it here is refused rather than silently
+             * dropped. Archive the conversation, or track what you have seen
+             * with `mailboxes.changes`.
+             */
+            is_read?: boolean;
+            is_starred?: boolean;
+            folder?: "inbox" | "archive" | "spam" | "trash";
+        }) => Promise<{
+            id: string;
+            undo: unknown[];
+        }>;
+        /** One action, up to 200 conversations. */
+        act: (messageIds: string[], action: MessageActionName) => Promise<{
+            applied: number;
+            undo: unknown[];
+        }>;
+        /**
+         * Put an action back.
+         *
+         * Unusual for an API to have, and the argument is that software makes
+         * mistakes at a speed a person does not: an agent that archived the
+         * wrong forty conversations should be able to say so.
+         */
+        undo: (undo: unknown[]) => Promise<{
+            restored: number;
+        }>;
+        /**
+         * Search one mailbox, narrowed.
+         *
+         * Full text in `q`, and six filters beside it. Everything is optional
+         * except having *something*: a filter with no words is a legitimate
+         * search — "everything unread from Marcus" is a question — and neither
+         * words nor filters is not.
+         *
+         * `in` is the only way to look in Trash, which a plain search skips on
+         * purpose. Results say which folder each hit is in.
+         */
+        search: (identityId: string, options?: {
+            q?: string;
+            /** One folder. Omit for everywhere except Trash. */
+            in?: string;
+            /** Substring of the sender's address or display name. */
+            from?: string;
+            /** Substring of any recipient. */
+            to?: string;
+            has_attachment?: boolean;
+            is_unread?: boolean;
+            is_starred?: boolean;
+            limit?: number;
+        }) => Promise<Page<MessageListItem & {
+            folder: string;
+        }>>;
         send: (input: {
             from: string;
             to: string | string[];
@@ -199,6 +464,10 @@ declare class Pidgeon {
             bcc?: string | string[];
             subject?: string;
             text?: string;
+            /** An HTML body. `text` stays required — see the docs for why. */
+            html?: string;
+            /** Ids from `attachments.upload`. */
+            attachment_ids?: string[];
             in_reply_to?: string | null;
         }) => Promise<{
             id: string;
@@ -214,11 +483,129 @@ declare class Pidgeon {
             id: string;
             url: string;
         }>;
+        /**
+         * Upload a file, then name its id in `messages.send`.
+         *
+         * An upload expires in a day: it is a file no message refers to yet, so
+         * the window is long enough for a retry and short enough that a crashed
+         * client does not leave its files with us.
+         */
+        upload: (identityId: string, file: File | Blob, filename?: string) => Promise<UploadedAttachment>;
+    };
+    mailboxes: {
+        /** The folders of one address, with their counts. */
+        list: (identityId: string) => Promise<Page<Mailbox>>;
+        /**
+         * One folder, a page at a time.
+         *
+         * `cursor` is the `next_cursor` of the page before it and is opaque —
+         * it carries the sort key and the id together, because several messages
+         * can share a millisecond. Do not construct one.
+         */
+        list_folder: (folder: Mailbox["folder"], identityId: string, options?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<MessageListItem>>;
+        /**
+         * What changed since you last looked.
+         *
+         * Per mailbox, not per folder: a message moving from the inbox to the
+         * archive is one event, and the row says where it went. Arrivals are in
+         * it too, so this is the only thing you need to poll.
+         *
+         * `since` is the `sync_cursor` from a listing, or the `next_cursor` from
+         * a previous call to this. It is **not** a page cursor — the two are
+         * different orders and passing one for the other is refused rather than
+         * guessed at.
+         *
+         * Throws `resync` when the cursor is older than the window in which we
+         * keep the record of what was deleted. List the folders again.
+         */
+        changes: (identityId: string, since: string, options?: {
+            limit?: number;
+        }) => Promise<Page<MailboxChange>>;
+        /**
+         * Empty the trash, permanently.
+         *
+         * Only the trash. It takes attachments and archived originals with it and
+         * there is no undo — `messages.undo` replays column values, and these
+         * rows are gone.
+         *
+         * `messages.act(ids, 'delete_forever')` does the same to a list you name,
+         * and caps at 200. This needs no ids.
+         */
+        empty_trash: (identityId: string) => Promise<{
+            folder: string;
+            deleted: number;
+        }>;
+    };
+    workspace: {
+        /** Which account this key is for, and which plan sets its limits. */
+        get: () => Promise<Workspace>;
+        /**
+         * The people here, so a conversation can be assigned to one of them.
+         *
+         * Read-only. Inviting somebody is mail to a person and removing somebody
+         * hands on their mailboxes; neither is a thing to do without a human
+         * deciding it.
+         */
+        members: () => Promise<Page<Member>>;
+    };
+    /**
+     * A credential per customer, minted by this one.
+     *
+     * `identity_ids` is required and must be a subset of what this key already
+     * reaches — a key cannot delegate reach it does not have. Hand the new key
+     * to the tenant it was scoped for, and revoke it when they leave.
+     *
+     * **Revoking takes the keys it made with it**, transitively. That is what
+     * makes rotating a leaked key true: its first useful move would otherwise
+     * be to mint a second one and keep it.
+     */
+    keys: {
+        list: () => Promise<ApiKey[]>;
+        /** The response carries `token`, once. Store it before you discard it. */
+        create: (input: {
+            name: string;
+            identity_ids: string[];
+        }) => Promise<ApiKey & {
+            token: string;
+        }>;
+        /** Revokes it and everything it minted. A key may revoke itself. */
+        revoke: (id: string) => Promise<{
+            id: string;
+        }>;
+    };
+    /**
+     * Working IMAP and SMTP credentials for one address.
+     *
+     * What lets you hand a customer a mailbox they can open in Apple Mail. The
+     * address you may issue one for is an address this key can already send
+     * from — the credential reads the inbox and sends as it, so issuing one is
+     * handing over exactly that.
+     *
+     * `username` and `password` are useless apart: a password presented for the
+     * wrong address is a failed login, not a successful one.
+     */
+    appPasswords: {
+        list: (identityId: string) => Promise<AppPassword[]>;
+        create: (input: {
+            identity_id: string;
+            name: string;
+        }) => Promise<AppPassword & {
+            username: string;
+            password: string;
+        }>;
+        revoke: (id: string) => Promise<{
+            id: string;
+        }>;
     };
     threads: {
         list: (options?: {
             identity_id?: string;
             status?: string;
+            /** A person's id, or `'unassigned'` for the queue nobody has taken. */
+            assignee_id?: string;
             limit?: number;
             cursor?: string;
         }) => Promise<Page<Thread>>;
@@ -226,6 +613,8 @@ declare class Pidgeon {
         update: (id: string, input: {
             status?: "open" | "waiting" | "resolved" | "human_review";
             owner_type?: "human" | "automation" | "agent";
+            /** A person's id to hand it to, or `null` to put it back in the queue. */
+            assignee_id?: string | null;
         }) => Promise<Thread>;
         /** Hand the conversation to a person. The takeover primitive, named. */
         handOff: (id: string) => Promise<Thread>;
@@ -243,6 +632,25 @@ declare class Pidgeon {
         delete: (id: string) => Promise<{
             id: string;
         }>;
+        /**
+         * Turn an endpoint off, or back on.
+         *
+         * We disable one ourselves after enough consecutive failures. Without
+         * this you would have to delete and recreate it, which changes the
+         * signing secret every receiver is verifying against.
+         */
+        update: (id: string, input: {
+            status: "active" | "disabled";
+        }) => Promise<Webhook>;
+        /** What happened to each event we tried to hand this endpoint. */
+        deliveries: (webhookId: string, options?: {
+            limit?: number;
+        }) => Promise<Delivery[]>;
+        /** Queue one up again. Not idempotent — sending twice is the point. */
+        replay: (deliveryId: string) => Promise<{
+            id: string;
+            status: string;
+        }>;
     };
     events: {
         list: (options?: {
@@ -253,9 +661,88 @@ declare class Pidgeon {
         }) => Promise<Page<Event>>;
         get: (id: string) => Promise<Event>;
     };
+    /**
+     * Domains, and the one step this API cannot perform for you.
+     *
+     * We cannot write records in somebody else's zone. What we can do is make
+     * the human step **delegable**: `create` hands back the records alongside
+     * the domain, so you show them to your own customer in your own interface
+     * and never send anybody to a Pidgeon screen. Then poll `verify`, or
+     * subscribe to `domain.verified` and do not poll at all.
+     *
+     * `dns_complete` is not a detail: the DKIM records come from what the mail
+     * provider issued, so a list returned before provisioning finished looks
+     * complete and is missing three CNAMEs. Publishing that gives you a domain
+     * that verifies and cannot sign mail.
+     */
     domains: {
-        /** Read-only. Adding and verifying a domain is a DNS-and-a-human task. */
         list: () => Promise<Domain[]>;
+        get: (id: string) => Promise<Domain & {
+            dns_records: DnsRecord[];
+            dns_complete: boolean;
+        }>;
+        create: (input: {
+            domain: string;
+        }) => Promise<Domain & {
+            dns_records: DnsRecord[];
+            dns_complete: boolean;
+        }>;
+        /** Idempotent and safe to poll. Calling it on a verified domain re-checks. */
+        verify: (id: string) => Promise<{
+            verified: boolean;
+            mail_configured: boolean;
+            message: string;
+            dns_records: DnsRecord[];
+            dns_complete: boolean;
+        }>;
+        /** Takes its addresses, their mail, their rules and their webhooks with it. */
+        delete: (id: string) => Promise<{
+            id: string;
+        }>;
+        /**
+         * The catch-all switch — the one thing about a domain that can change.
+         *
+         * Catch-all is two gates: this, and a `catch_all` routing rule saying
+         * where the mail goes. Turning this on without the rule does nothing, so
+         * that turning it off later does not throw away where the mail was going.
+         */
+        update: (id: string, input: {
+            catch_all_enabled: boolean;
+        }) => Promise<Domain>;
+    };
+    /**
+     * Where mail to an address goes.
+     *
+     * The piece that makes per-customer addresses work without a person in the
+     * loop: `acme@yourdomain.com` routed into one inbox you already have, or
+     * into a webhook with no inbox at all. An address always beats a rule, so a
+     * rule never shadows a real address — creating one that would is refused.
+     *
+     * The destination must be an address you could already send from, because
+     * routing an address to a mailbox also lets that mailbox send as it.
+     */
+    routing: {
+        list: (options?: {
+            domain_id?: string;
+        }) => Promise<RoutingRule[]>;
+        create: (input: {
+            match_type: "address";
+            local_part: string;
+            destination_identity_id?: string;
+            destination_webhook_id?: string;
+        } | {
+            match_type: "catch_all";
+            domain_id: string;
+            destination_identity_id?: string;
+            destination_webhook_id?: string;
+        }) => Promise<RoutingRule>;
+        /** Stop a rule firing without forgetting where it pointed. */
+        update: (id: string, input: {
+            status: "active" | "disabled";
+        }) => Promise<RoutingRule>;
+        delete: (id: string) => Promise<{
+            id: string;
+        }>;
     };
 }
 
@@ -299,4 +786,4 @@ declare function verifyWebhook(input: {
     now?: Date;
 }): Promise<WebhookEnvelope>;
 
-export { type Address, type Attachment, type Domain, type Event, type Identity, type Message, type Page, Pidgeon, PidgeonError, type PidgeonOptions, type RoutingRule, SIGNATURE_HEADER, TIMESTAMP_HEADER, type Thread, type Webhook, type WebhookEnvelope, verifyWebhook };
+export { type Address, type ApiKey, type AppPassword, type Attachment, type Delivery, type DnsRecord, type Domain, type Event, type Identity, type Mailbox, type MailboxChange, type Member, type Message, type MessageActionName, type MessageListItem, type Page, Pidgeon, PidgeonError, type PidgeonOptions, type RoutingRule, SIGNATURE_HEADER, TIMESTAMP_HEADER, type Thread, type UploadedAttachment, type Webhook, type WebhookEnvelope, type Workspace, verifyWebhook };