@pidgeon-ai/sdk 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -1,14 +1,67 @@
 # Changelog
 
 Versioned independently of the application. The API is `/v1`; this package
-is `0.x`. They are different contracts with different audiences, and tying
+is `1.x`. They are different contracts with different audiences, and tying
 the two would publish a release for every unrelated product deploy.
 
-Semver applies to **this package's own surface** — the exported types, the
-method signatures, the error shape — not to the API behind it.
+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.2.0 — the document says what its fields mean
+
+**Additive, and a correction.**
+
+**Added.** Every request field that means one thing everywhere now carries a
+description, so the types say what `from`, `to`, `attachment_ids` and twenty
+others are for — 0 of 136 had one before.
+
+**Corrected.** `messagesSend` is typed `Sent` at `202`, which is what the API
+has always answered. It was declared `Message` at `201`, a response that never
+arrives — so a caller reading `data.subject` off a send got `undefined`, and
+`send` and `reply` appeared to disagree about their shape when they never did.
+Minor rather than major because nothing could have depended on a status code
+the server does not send.
+
+## 1.1.0 — the domain an address is on
+
+Additive. Nothing here changes a call that already works.
+
+**Added**
+
+- `Identity.domain_id`. Every address now says which domain it is on, not
+  only its name. This exists because the id was otherwise unlearnable: an
+  account whose only domain is the shared one gets `[]` from `GET /domains`,
+  correctly — that endpoint lists what a workspace _owns_ — and `domain_id`
+  is what `identitiesCreate` requires. A customer building against production
+  read the uuid out of the database to get past it.
+- `identitiesCreate` takes `domain` (a name) or `address` (a whole one) in
+  place of `domain_id`. Pass exactly one. `address` also supplies the local
+  part, which is the form `skills/pidgeon/SKILL.md` has documented since it
+  was written.
+- `threadsList` takes `identity_id`, `status`, `owner_type` and
+  `assignee_id`. The API has honoured all four since it was written and the
+  contract declared none of them, so no generated client could offer them.
+  `assignee_id` takes a person's id or the literal `unassigned`.
+
+## 1.0.0 — one name per operation, generated
+
+**Published without an entry here**, which is how a changelog stops being
+read. Recorded after the fact, on 13 October, when a customer found the
+package README describing a class the package does not export.
+
+**Breaking.** The hand-written client is gone. There is no `Pidgeon` class
+and no `PidgeonError`: the package is generated from `openapi.json`, one
+function per operation named for its tag — `messagesSend`, `messagesGet`,
+`threadsUpdate` — sharing one client you configure at startup with
+`client.setConfig`. A call resolves to `{ data, error }` rather than
+throwing, or pass `throwOnError: true`.
+
+Both clients are generated from the same document, so an operation has the
+same name in TypeScript and in Python. `decisions.md` §343 is the argument,
+including why the stutter in `messagesSend` is accepted.
+
 ## 0.2.0 — the mailbox, and the credentials to reach it
 
 A minor rather than a patch, because one signature changed. In `0.x` semver

package/README.md

@@ -1,7 +1,8 @@
 # @pidgeon-ai/sdk
 
-A thin TypeScript client for the [Pidgeon](https://pidgeon.ai) email API.
-Typed `fetch` wrappers, one error class, and a webhook verifier.
+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
@@ -11,15 +12,35 @@ CommonJS.
 pnpm add @pidgeon-ai/sdk
 ```
 
+## The shape
+
+**There is no `Pidgeon` class.** Every operation is a function named for its
+tag — `messagesSend`, `messagesGet`, `threadsUpdate` — and they share one
+client you configure at startup. The Python package is generated from the same
+document, so an operation has the same name in both.
+
+```ts
+import { client, messagesGet } from '@pidgeon-ai/sdk';
+
+client.setConfig({ auth: () => process.env.PIDGEON_API_KEY! });
+
+const { data, error } = await messagesGet({ path: { id: messageId } });
+```
+
+A call resolves to `{ data, error }` rather than throwing: `error` carries the
+API's own `code`, a `message` written for a person, and a `field` when one
+input was at fault. Pass `throwOnError: true` on a call to get the data
+directly and an exception instead.
+
 ## Receiving mail
 
 Mail arriving at an address your code owns becomes an event, and your
 endpoint is called with a signed payload.
 
 ```ts
-import { Pidgeon, verifyWebhook } from '@pidgeon-ai/sdk';
+import { client, messagesGet, messagesSend, verifyWebhook } from '@pidgeon-ai/sdk';
 
-const pidgeon = new Pidgeon({ apiKey: process.env.PIDGEON_API_KEY! });
+client.setConfig({ auth: () => process.env.PIDGEON_API_KEY! });
 
 export async function POST(request: Request) {
   // Verify first. An unverified payload is an unauthenticated POST that
@@ -33,15 +54,21 @@ export async function POST(request: Request) {
   if (event.type !== 'message.received') return new Response(null, { status: 204 });
 
   // The event carries ids, never a body. Exchange one for the content.
-  const mail = await pidgeon.messages.get(event.data.message_id as string);
-
-  await pidgeon.messages.send({
-    from: mail.to[0].email,
-    to: mail.from.email,
-    subject: `Re: ${mail.subject}`,
-    text: 'Got it — someone will be in touch.',
-    // Keeps the conversation together in the recipient's client too.
-    in_reply_to: mail.id,
+  const { data: mail } = await messagesGet({
+    path: { id: event.data.message_id as string },
+    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,
+    },
+    throwOnError: true,
   });
 
   return new Response(null, { status: 204 });
@@ -60,45 +87,60 @@ the signature, and compares in constant time.
 ## Handing a conversation to a person
 
 ```ts
-await pidgeon.threads.handOff(threadId);
+import { threadsUpdate } from '@pidgeon-ai/sdk';
+
+await threadsUpdate({
+  path: { id: threadId },
+  body: { owner_type: 'human' },
+  throwOnError: true,
+});
 ```
 
+Hand it back by setting `owner_type` to `agent`.
+
 It appears in the web inbox, and `thread.updated` tells whatever was
 driving the conversation that it no longer is.
 
 ## Errors
 
-Every failure is a `PidgeonError` carrying the API's own `code`, the HTTP
-`status`, the offending `field` on a validation failure, and the request id
-to quote in a support conversation.
+A failure comes back in `error`, carrying the API's own `code`, a `message`
+written for a person and safe to show one, and the offending `field` on a
+validation failure.
 
 ```ts
-import { PidgeonError } from '@pidgeon-ai/sdk';
+const { data, error } = await messagesSend({ body: { from, to, text } });
 
-try {
-  await pidgeon.messages.send({ from, to, text });
-} catch (error) {
-  if (error instanceof PidgeonError && error.code === 'rate_limited') {
+if (error) {
+  if (error.error.code === 'rate_limited') {
     // Back off. Deliberately not done for you — see below.
   }
-  throw error;
+  throw new Error(error.error.message);
 }
 ```
 
 `code` is one of `validation`, `unauthenticated`, `entitlement`,
 `forbidden`, `not_found`, `conflict`, `rate_limited`, `internal`.
 
+With `throwOnError: true` the same failure is thrown instead and `data` is no
+longer `undefined`, which is the shape most call sites want.
+
 ## Pagination
 
 List endpoints return a page, not an iterator.
 
 ```ts
-let cursor: string | null = null;
+import { eventsList } from '@pidgeon-ai/sdk';
+
+let cursor: string | undefined;
 
 do {
-  const page = await pidgeon.events.list({ limit: 50, cursor: cursor ?? undefined });
+  const { data: page } = await eventsList({
+    query: { limit: 50, cursor },
+    throwOnError: true,
+  });
+
   for (const event of page.data) handle(event);
-  cursor = page.next_cursor;
+  cursor = page.next_cursor ?? undefined;
 } while (cursor);
 ```
 
@@ -112,8 +154,10 @@ pagination also hides the rate limit pagination is subject to.
 ## Options
 
 ```ts
-new Pidgeon({
-  apiKey: process.env.PIDGEON_API_KEY!,
+import { client } from '@pidgeon-ai/sdk';
+
+client.setConfig({
+  auth: () => process.env.PIDGEON_API_KEY!,
   // Point at a local dev server, or a preview deployment.
   baseUrl: 'http://localhost:3000/api/v1',
   // Inject a transport. Useful in tests.
@@ -121,10 +165,13 @@ new Pidgeon({
 });
 ```
 
+`createClient(createConfig({ … }))` makes a second, independent client, for
+code that talks to two accounts; pass it as `client` on a call.
+
 ## Versioning
 
 Versioned independently of the API. The API is `/v1`; this package is
-`0.x`, and semver applies to its own surface — the exported types, the
+`1.x`, and semver applies to its own surface — the exported types, the
 method signatures, the error shape. See `CHANGELOG.md`.
 
 MIT.