@pidgeon-ai/sdk 1.14.0 → 1.16.0

package/CHANGELOG.md

@@ -7,7 +7,33 @@ the two would publish a release for every unrelated product deploy.
 Semver applies to **this package's own surface** — the exported names, the
 call shapes, the result shape — not to the API behind it.
 
-## Unreleased
+## 1.16.0 — an attachment as text
+
+`attachmentsText` (`GET /attachments/{id}/text`) returns a text attachment —
+CSV, log, JSON, calendar — as text, up to 5 MB and 200,000 characters, with
+a Pidgeon Firewall verdict judged with the message's sender. `body: 'clean'`
+returns the cleaned text. HTML, PDF, Office files and images are refused.
+
+## 1.15.0 — a read says what it held back
+
+`GET /messages/await` returns `held_back`: matching messages that arrived
+and were filed as spam, by count and id, so a wait that times out on a code
+from a sender whose authentication failed no longer reads as "nothing came".
+`include_spam=true` returns such a message instead. The inbox page of
+`GET /mailboxes/{folder}` carries `held_back.spam`, the unread messages in
+Spam, because an inbox that looks empty may not be.
+
+## 1.14.2 — the PyPI page is the Python README
+
+No change to the API or the exported surface. Released with the Python
+client, whose PyPI page is now its own README rather than a shorter copy.
+
+## 1.14.1 — the README leads with the job
+
+No change to the API or the exported surface. The README opens with
+creating an address, sending, waiting for the answer and replying with
+`messagesReply`, and the package's description and keywords say what it is
+for: email inboxes for AI agents.
 
 ## 1.14.0 — clean bodies in a conversation
 

package/README.md

@@ -1,17 +1,74 @@
 # @pidgeon-ai/sdk
 
-A TypeScript client for the [Pidgeon](https://pidgeon.ai) email API,
-generated from `openapi.json`: one typed function per operation, plus a
-webhook verifier.
-
-**Zero dependencies.** Needs `fetch` and `crypto.subtle`, so it runs on
-Node 18+, Bun, Deno, Cloudflare Workers and Vercel functions. ESM and
-CommonJS.
+Pidgeon is the email inbox API for AI agents. It gives agents their own inboxes
+so they can work with emails just like a human. This is its TypeScript client:
+one typed function per operation, plus a webhook verifier.
 
 ```bash
-pnpm add @pidgeon-ai/sdk
+npm install @pidgeon-ai/sdk
 ```
 
+Or `pnpm add @pidgeon-ai/sdk`. **Zero dependencies.** Needs `fetch` and
+`crypto.subtle`, so it runs on Node 18+, Bun, Deno, Cloudflare Workers and
+Vercel functions. ESM and CommonJS.
+
+## Create an address, send, receive, reply
+
+```ts
+import {
+  client,
+  identitiesCreate,
+  messagesAwait,
+  messagesReply,
+  messagesSend,
+} from '@pidgeon-ai/sdk';
+
+client.setConfig({ auth: () => process.env.PIDGEON_API_KEY! });
+
+// 1. An address of its own. Any free name on pidgeon.email works with no DNS.
+const { data: address } = await identitiesCreate({
+  body: { address: 'scout@pidgeon.email', type: 'agent' },
+  throwOnError: true,
+});
+
+// 2. Send from it.
+await messagesSend({
+  body: {
+    from: address.data.email,
+    to: 'ops@example.com',
+    subject: 'Staging access',
+    text: 'Could you send me the access code?',
+  },
+  throwOnError: true,
+});
+
+// 3. Receive: one held-open request until the answer arrives, up to 60 seconds.
+const { data: awaited } = await messagesAwait({
+  query: { identity_id: address.data.id, timeout: 60 },
+  throwOnError: true,
+});
+
+// 4. Reply into the same conversation. Recipients and subject come off the original.
+if (awaited.data.message) {
+  console.log(awaited.data.message.extracted.codes);
+  await messagesReply({
+    path: { id: awaited.data.message.id },
+    body: { text: 'Thanks, that worked.' },
+    throwOnError: true,
+  });
+}
+```
+
+`PIDGEON_API_KEY` is a `pgn_live_…` key. Make one at
+[pidgeon.ai/app/developers/keys](https://pidgeon.ai/app/developers/keys), or
+let your agent sign itself up: [pidgeon.ai/skill.md](https://pidgeon.ai/skill.md)
+is two calls, and the only thing it needs from a person is a six-digit code.
+
+In production, take a [signed webhook](#receiving-mail) rather than holding a
+request open. Documentation: [pidgeon.ai/docs](https://pidgeon.ai/docs) ·
+[API reference](https://pidgeon.ai/docs/reference) ·
+[OpenAPI](https://pidgeon.ai/openapi.json).
+
 ## The shape
 
 **There is no `Pidgeon` class.** Every operation is a function named for its
@@ -38,7 +95,7 @@ Mail arriving at an address your code owns becomes an event, and your
 endpoint is called with a signed payload.
 
 ```ts
-import { client, messagesGet, messagesSend, verifyWebhook } from '@pidgeon-ai/sdk';
+import { client, messagesGet, messagesReply, verifyWebhook } from '@pidgeon-ai/sdk';
 
 client.setConfig({ auth: () => process.env.PIDGEON_API_KEY! });
 
@@ -59,15 +116,10 @@ export async function POST(request: Request) {
     throwOnError: true,
   });
 
-  await messagesSend({
-    body: {
-      from: mail.data.to[0]!.email,
-      to: mail.data.from.email,
-      subject: `Re: ${mail.data.subject}`,
-      text: 'Got it — someone will be in touch.',
-      // Keeps the conversation together in the recipient's client too.
-      in_reply_to: mail.data.id,
-    },
+  // Into the same conversation, threaded in the recipient's client too.
+  await messagesReply({
+    path: { id: mail.data.id },
+    body: { text: 'Got it — someone will be in touch.' },
     throwOnError: true,
   });
 
@@ -174,4 +226,13 @@ Versioned independently of the API. The API is `/v1`; this package is
 `1.x`, and semver applies to its own surface — the exported types, the
 method signatures, the error shape. See `CHANGELOG.md`.
 
-MIT.
+## Contributing
+
+This package is generated from [`openapi.json`](https://pidgeon.ai/openapi.json),
+the contract the API validates against, and published from
+[pidgeon-ai/pidgeon-js](https://github.com/pidgeon-ai/pidgeon-js). A pull
+request against generated code cannot be merged as written — the fix belongs
+in the schema. [Open an issue](https://github.com/pidgeon-ai/pidgeon-js/issues)
+and say what is wrong, or email [support@pidgeon.ai](mailto:support@pidgeon.ai).
+
+MIT licensed.

package/dist/index.cjs

@@ -29,6 +29,7 @@ __export(index_exports, {
   appPasswordsList: () => appPasswordsList,
   appPasswordsRevoke: () => appPasswordsRevoke,
   attachmentsDownloadUrl: () => attachmentsDownloadUrl,
+  attachmentsText: () => attachmentsText,
   attachmentsUpload: () => attachmentsUpload,
   calendarCreateEvent: () => calendarCreateEvent,
   calendarDeleteEvent: () => calendarDeleteEvent,
@@ -1647,6 +1648,11 @@ var attachmentsDownloadUrl = (options) => (options.client ?? client).get({
   url: "/attachments/{id}",
   ...options
 });
+var attachmentsText = (options) => (options.client ?? client).get({
+  security: [{ scheme: "bearer", type: "http" }],
+  url: "/attachments/{id}/text",
+  ...options
+});
 
 // src/webhooks.ts
 var SIGNATURE_HEADER = "x-pidgeon-signature";
@@ -1808,6 +1814,7 @@ function sleep(ms, signal) {
   appPasswordsList,
   appPasswordsRevoke,
   attachmentsDownloadUrl,
+  attachmentsText,
   attachmentsUpload,
   calendarCreateEvent,
   calendarDeleteEvent,