@pidgeon-ai/sdk 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -9,6 +9,140 @@ call shapes, the result shape — not to the API behind it.
 
 ## Unreleased
 
+## 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.**
+
+1.2.0 went out on 14 October and then the contract moved for a day without
+this number moving with it. A field test on 15 October installed the published
+package, called a search the live API had been accepting since the morning,
+and got a `TypeError` for an argument the contract no longer requires. It
+built what it needed with a hand-written HTTP client instead. Everything below
+had already shipped; none of it was installable.
+
+**Fixed.** `verifyWebhook` reads the signature headers whatever case the
+framework spells them in. The lookup was `headers[name] ?? headers[name
+.toLowerCase()]` and `name` is already a lowercase constant — so it read the
+same key twice, and a plain object keyed `X-Pidgeon-Signature` was rejected as
+unsigned. Every existing test passed, because they all hand it a `Headers` or
+a lowercase object and both are already normalised. The broken branch is
+reached by an object somebody built themselves, which is what API Gateway
+hands a Lambda. `pidgeon` on PyPI was always right about this.
+
+**Added.**
+
+- `meGet`. What a key is, what it may do, and how many addresses it reaches —
+  the first call a credential can make about itself.
+- `eventsStream`'s endpoint is in the document. The client does not wrap SSE,
+  because a generated client has nowhere to put a long-lived connection; the
+  path, the cursor header and the event shape are typed so hand-rolling it is
+  twenty lines rather than a reverse-engineering exercise.
+- `thread.created` is emitted and subscribable. It was declared, accepted by
+  `POST /webhooks`, and had never once fired.
+- `from_self` on `message.received`. A workspace with several addresses sees
+  its own outbound mail arrive at the others, genuinely inbound, with nothing
+  to distinguish it from a stranger — so a handler written the obvious way
+  answers its own reply. Check it before you reply.
+- Quota pacing on a refusal: `Retry-After` and `X-RateLimit-*-Day`, so a
+  client refused a send can compute when it may try again instead of guessing
+  a day.
+
+**Declared, having always been returned.** Three fields the API sends and the
+document did not mention, so the generated types dropped them and a caller had
+to cast to reach them:
+
+- `sync_cursor` on a folder listing. `GET /mailboxes/changes` documents
+  `since` as "the `sync_cursor` from a listing" and no listing declared one,
+  so the change feed was unreachable from a typed client without defeating
+  its own types.
+- `folder` on a search hit, and `identity` beside `identity_id` — the address
+  rather than the uuid, which is what the rest of the API already carries on a
+  thread row, on an event and on `GET /messages/{id}`. A search is the one
+  endpoint that spans mailboxes, so it was the one that most needed to name
+  them and the only one that would not. A hit is now its own type,
+  `SearchHit`, rather than a `MessageListItem` with two fields missing.
+- `colour` is the eight-value enum it has always been enforced as, not
+  `string`. The palette existed only in the refusal, so the first call
+  anybody writes fails — somebody who has written CSS passes a hex. The
+  refusal was already good and is kept word for word.
+
+**Widened.** `messagesSearch` no longer requires `identity_id`. It searches
+every address the credential reaches, which is what it has always done on the
+server and what `skill.md` has always said; the document said "one mailbox at
+a time" in prose while declaring the parameter optional, and the generator
+followed the prose. `MessageListItem` carries `identity_id`, `to`,
+`counterparty` and `counterparty_name`, so a hit can be attributed to a
+mailbox without a second call.
+
+**Also.** `identitiesCreate` on the shared domain, a 404 that stopped
+pretending an address it had just listed did not exist, and `repository`
+fields that resolve — all four packages pointed at a private repository that
+404s for everybody who installs one.
+
 ## 1.2.0 — the document says what its fields mean
 
 **Additive, and a correction.**

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PCN Labs OÜ
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -62,6 +62,7 @@ __export(index_exports, {
   draftsUpdate: () => draftsUpdate,
   eventsGet: () => eventsGet,
   eventsList: () => eventsList,
+  eventsStream: () => eventsStream,
   identitiesAccessCreate: () => identitiesAccessCreate,
   identitiesAccessDelete: () => identitiesAccessDelete,
   identitiesAccessGet: () => identitiesAccessGet,
@@ -90,6 +91,7 @@ __export(index_exports, {
   mailboxesEmptyTrash: () => mailboxesEmptyTrash,
   mailboxesList: () => mailboxesList,
   mailboxesListFolder: () => mailboxesListFolder,
+  meGet: () => meGet,
   messagesAct: () => messagesAct,
   messagesForward: () => messagesForward,
   messagesGet: () => messagesGet,
@@ -107,6 +109,7 @@ __export(index_exports, {
   routingDelete: () => routingDelete,
   routingList: () => routingList,
   routingUpdate: () => routingUpdate,
+  streamEvents: () => streamEvents,
   threadsGet: () => threadsGet,
   threadsLabelsCreate: () => threadsLabelsCreate,
   threadsLabelsDelete: () => threadsLabelsDelete,
@@ -173,7 +176,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;
@@ -277,7 +280,7 @@ function createSseClient({
           break;
         }
         const backoff = Math.min(retryDelay * 2 ** (attempt - 1), sseMaxRetryDelay ?? 3e4);
-        await sleep(backoff);
+        await sleep2(backoff);
       }
     }
   };
@@ -1117,7 +1120,7 @@ var messagesSend = (options) => (options.client ?? client).post({
     ...options.headers
   }
 });
-var messagesSearch = (options) => (options.client ?? client).get({
+var messagesSearch = (options) => (options?.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
   url: "/messages/search",
   ...options
@@ -1353,6 +1356,11 @@ var appPasswordsRevoke = (options) => (options.client ?? client).delete({
   url: "/app-passwords/{id}",
   ...options
 });
+var meGet = (options) => (options?.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/me",
+  ...options
+});
 var workspaceGet = (options) => (options?.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
   url: "/workspace",
@@ -1368,6 +1376,11 @@ var eventsList = (options) => (options?.client ?? client).get({
   url: "/events",
   ...options
 });
+var eventsStream = (options) => (options?.client ?? client).sse.get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/events/stream",
+  ...options
+});
 var eventsGet = (options) => (options.client ?? client).get({
   security: [{ scheme: "bearer", type: "http" }],
   url: "/events/{id}",
@@ -1589,7 +1602,16 @@ var attachmentsDownloadUrl = (options) => (options.client ?? client).get({
 var SIGNATURE_HEADER = "x-pidgeon-signature";
 var TIMESTAMP_HEADER = "x-pidgeon-timestamp";
 async function verifyWebhook(input) {
-  const get = (name) => input.headers instanceof Headers ? input.headers.get(name) ?? void 0 : input.headers[name] ?? input.headers[name.toLowerCase()];
+  const get = (name) => {
+    if (input.headers instanceof Headers) return input.headers.get(name) ?? void 0;
+    const direct = input.headers[name];
+    if (direct !== void 0) return direct;
+    const wanted = name.toLowerCase();
+    for (const [key2, value] of Object.entries(input.headers)) {
+      if (key2.toLowerCase() === wanted) return value;
+    }
+    return void 0;
+  };
   const timestamp = get(TIMESTAMP_HEADER);
   const signature = get(SIGNATURE_HEADER);
   if (!timestamp || !signature) throw new Error("This request is not signed.");
@@ -1626,6 +1648,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,
@@ -1670,6 +1791,7 @@ function constantTimeEqual(a, b) {
   draftsUpdate,
   eventsGet,
   eventsList,
+  eventsStream,
   identitiesAccessCreate,
   identitiesAccessDelete,
   identitiesAccessGet,
@@ -1698,6 +1820,7 @@ function constantTimeEqual(a, b) {
   mailboxesEmptyTrash,
   mailboxesList,
   mailboxesListFolder,
+  meGet,
   messagesAct,
   messagesForward,
   messagesGet,
@@ -1715,6 +1838,7 @@ function constantTimeEqual(a, b) {
   routingDelete,
   routingList,
   routingUpdate,
+  streamEvents,
   threadsGet,
   threadsLabelsCreate,
   threadsLabelsDelete,