@pidgeon-ai/sdk 1.3.0 → 1.5.0

package/CHANGELOG.md

@@ -9,6 +9,93 @@ call shapes, the result shape — not to the API behind it.
 
 ## Unreleased
 
+## 1.5.0 — a container your customers live in
+
+**Additive.** Every account has exactly one pod already, every address is in
+it, and a caller who never mentions a pod cannot tell this release from the
+last one.
+
+**Added.** `podsList`, `podsCreate`, `podsGet`, `podsUpdate`, the `Pod` type,
+`pod_id` on an address, and `pod_id` as a filter on `identitiesList`.
+
+A **pod** holds addresses and domains: one of your customers, a client, or
+just test kept apart from production. It has a name and an optional
+`client_id` that is your own id for it, carried and never parsed.
+
+**It is organisational and not a boundary**, and the types say so because the
+risk in shipping the container before the isolation is a reader assuming the
+isolation. A pod carries no sending reputation of its own — one SES tenant
+per _account_, unchanged — and **a key is still a list of address ids**,
+never something scoped to a pod.
+
+**No delete.** The verb that destroys a container full of mailboxes is worth
+making somebody ask for, and nothing yet moves addresses between pods, so it
+would either refuse every non-empty pod or destroy mail.
+
+## 1.4.0 — things the prose promised and the types did not have
+
+**Additive, and two corrections to descriptions that were wrong.**
+
+The rest of what a field test found on 15 October building a shared mailroom.
+Everything below was either returned and undeclared, or described in the
+documentation and absent from the product.
+
+**Added to `Message`.**
+
+- `headers`, which `skill.md` and the MCP `get_message` tool have both
+  promised for months — "its body **and its headers**" — against a schema
+  with no such property. It is a subset and the description says which:
+  `message-id`, `in-reply-to`, `references`, `date`, `reply-to`,
+  `return-path`, the four list and auto-reply headers, `x-mailer` and
+  `x-priority`. The whole envelope is `GET /messages/{id}/raw`. The
+  threading three are new to the kept set, because _will my reply land in
+  the right conversation_ is the question people open this for and nothing
+  answered it for mail between two Pidgeon addresses.
+- `authentication` — `spf`, `dkim`, `dmarc`. `/docs/rules` has said since it
+  was written that if you need to be certain who sent something you should
+  _"read the authentication results on the message rather than its `From:`"_.
+  There were none in the contract: no such field anywhere. The columns have
+  been written since inbound mail existed. **Null means not reported, not
+  failed** — rendering an absent verdict as a failed one is worse than
+  showing nothing.
+- `delivered_to` is the envelope recipient on every message. It was null
+  unless routing had moved the mail, while `message.received` carried it
+  every time, so the event and the read disagreed about the same message.
+
+**Added to `Thread`.** `folder`, `from`, `from_name`, `preview` and
+`has_attachments`, from the newest message. `GET /threads` is the only
+workspace-wide listing and a row could say which conversations exist without
+being able to draw one — so a merged inbox had to come from
+`GET /mailboxes/{folder}`, which takes one address and one folder. Three
+addresses and four folders is twelve calls for one screen, against a free
+plan's 120 requests a minute. It is one call now.
+
+**Added to `MailboxChange`.** `identity_id`, which was null on every row of
+the only endpoint whose first required parameter is the mailbox.
+
+**New error codes.** `blocked` and `not_permitted`, both `403`.
+`/docs/rules`: _"a refusal tells you which kind it was… an agent debugging a
+send needs to know which."_ Both answered `forbidden` and neither word
+appeared in the response, so the only way to tell was to match the sentence.
+The fix is different for each — remove a rule, or change the send policy —
+which is the whole reason to separate them.
+
+**Corrected.** Two descriptions that described something the API does not do:
+
+- `rejected` on a send is **what the provider would not accept at hand-off**,
+  not a recipient your own rules forbid. That refuses the whole send with
+  `403`, and nothing goes to anybody. The old sentence told callers to handle
+  a partial send that never happens, and not to expect the exception they
+  actually get.
+- `is_read` on `PATCH /messages/{id}`, and `read`/`unread` on
+  `POST /messages/actions`, are declared refused for an API key. They always
+  were — read state belongs to a person — but three surfaces advertised them
+  with no hint, including the MCP tool, whose description argued for a
+  capability it does not have to the one consumer that cannot check first.
+
+**Widened.** `colour` on a label now has to be one of the eight; the
+refusal's sentence is unchanged.
+
 ## 1.3.0 — a day of API that never reached a registry
 
 **Additive, and one fix that was a blocker.**

package/dist/index.cjs

@@ -105,10 +105,15 @@ __export(index_exports, {
   messagesUndo: () => messagesUndo,
   messagesUpdate: () => messagesUpdate,
   metricsQuery: () => metricsQuery,
+  podsCreate: () => podsCreate,
+  podsGet: () => podsGet,
+  podsList: () => podsList,
+  podsUpdate: () => podsUpdate,
   routingCreate: () => routingCreate,
   routingDelete: () => routingDelete,
   routingList: () => routingList,
   routingUpdate: () => routingUpdate,
+  streamEvents: () => streamEvents,
   threadsGet: () => threadsGet,
   threadsLabelsCreate: () => threadsLabelsCreate,
   threadsLabelsDelete: () => threadsLabelsDelete,
@@ -175,7 +180,7 @@ function createSseClient({
   ...options
 }) {
   let lastEventId;
-  const sleep = sseSleepFn ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const sleep2 = sseSleepFn ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
   const createStream = async function* () {
     let retryDelay = sseDefaultRetryDelay ?? 3e3;
     let attempt = 0;
@@ -279,7 +284,7 @@ function createSseClient({
           break;
         }
         const backoff = Math.min(retryDelay * 2 ** (attempt - 1), sseMaxRetryDelay ?? 3e4);
-        await sleep(backoff);
+        await sleep2(backoff);
       }
     }
   };
@@ -1058,6 +1063,34 @@ var identitiesSuspendTenant = (options) => (options.client ?? client).post({
   url: "/tenants/{id}/suspend",
   ...options
 });
+var podsList = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/pods",
+  ...options
+});
+var podsCreate = (options) => (options.client ?? client).post({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/pods",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
+var podsGet = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/pods/{id}",
+  ...options
+});
+var podsUpdate = (options) => (options.client ?? client).patch({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/pods/{id}",
+  ...options,
+  headers: {
+    "Content-Type": "application/json",
+    ...options.headers
+  }
+});
 var labelsList = (options) => (options.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
   url: "/labels",
@@ -1647,6 +1680,105 @@ function constantTimeEqual(a, b) {
   }
   return difference === 0;
 }
+
+// src/stream.ts
+async function* streamEvents(options) {
+  const base = (options.baseUrl ?? "https://pidgeon.ai/api/v1").replace(/\/$/, "");
+  let lastEventId;
+  let backoffMs = 1e3;
+  while (!options.signal?.aborted) {
+    const url = new URL(`${base}/events/stream`);
+    if (options.identityId) url.searchParams.set("identity_id", options.identityId);
+    if (options.type) url.searchParams.set("type", options.type);
+    if (options.after && !lastEventId) url.searchParams.set("after", options.after);
+    let response;
+    try {
+      response = await fetch(url, {
+        headers: {
+          authorization: `Bearer ${options.apiKey}`,
+          accept: "text/event-stream",
+          ...lastEventId ? { "last-event-id": lastEventId } : {}
+        },
+        signal: options.signal
+      });
+    } catch {
+      if (options.signal?.aborted) return;
+      await sleep(backoffMs, options.signal);
+      backoffMs = Math.min(backoffMs * 2, 3e4);
+      continue;
+    }
+    if (response.status === 401 || response.status === 403 || response.status === 404) {
+      throw new Error(
+        `Pidgeon refused the stream: ${response.status} ${await response.text().catch(() => "")}`.trim()
+      );
+    }
+    if (!response.ok || !response.body) {
+      await sleep(backoffMs, options.signal);
+      backoffMs = Math.min(backoffMs * 2, 3e4);
+      continue;
+    }
+    backoffMs = 1e3;
+    for await (const frame of frames(response.body, options.signal)) {
+      if (frame.id) lastEventId = frame.id;
+      if (!frame.data) continue;
+      if (frame.event === "error") continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(frame.data);
+      } catch {
+        continue;
+      }
+      yield parsed;
+    }
+  }
+}
+async function* frames(body, signal) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (!signal?.aborted) {
+      const { done, value } = await reader.read();
+      if (done) return;
+      buffer += decoder.decode(value, { stream: true });
+      let boundary = buffer.indexOf("\n\n");
+      while (boundary !== -1) {
+        const block = buffer.slice(0, boundary);
+        buffer = buffer.slice(boundary + 2);
+        boundary = buffer.indexOf("\n\n");
+        const frame = {};
+        const data = [];
+        for (const line of block.split("\n")) {
+          if (line.startsWith(":")) continue;
+          const colon = line.indexOf(":");
+          if (colon === -1) continue;
+          const field = line.slice(0, colon);
+          const value2 = line.slice(colon + 1).replace(/^ /, "");
+          if (field === "id") frame.id = value2;
+          else if (field === "event") frame.event = value2;
+          else if (field === "data") data.push(value2);
+        }
+        if (data.length > 0) frame.data = data.join("\n");
+        if (frame.id || frame.data) yield frame;
+      }
+    }
+  } finally {
+    await reader.cancel().catch(() => void 0);
+  }
+}
+function sleep(ms, signal) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true }
+    );
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SIGNATURE_HEADER,
@@ -1734,10 +1866,15 @@ function constantTimeEqual(a, b) {
   messagesUndo,
   messagesUpdate,
   metricsQuery,
+  podsCreate,
+  podsGet,
+  podsList,
+  podsUpdate,
   routingCreate,
   routingDelete,
   routingList,
   routingUpdate,
+  streamEvents,
   threadsGet,
   threadsLabelsCreate,
   threadsLabelsDelete,