@pidgeon-ai/sdk 2.0.0 → 2.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,32 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.2.0
4
+
5
+ - `webhooks.create` takes `inboxIds`: the endpoint hears only those inboxes'
6
+ events. `Webhook` has `inbox_ids`, null for one of the whole account.
7
+
8
+ ## 2.1.1
9
+
10
+ - `calendar.create` and `calendar.update` take `attendees` and `sendInvites`,
11
+ and `calendar.remove` takes `{ sendInvites }`: the attendees get an
12
+ invitation, an update or a cancellation from the inbox. `CalendarEvent` has
13
+ `organizer`, `attendees` and, after a write that sent, `invites`.
14
+
15
+ ## 2.1.0
16
+
17
+ All of Email, and webhooks. Additive: 2.0 code runs unchanged.
18
+
19
+ - `messages`: `list`, `get` (`body: 'clean'` for the Firewall's cleaned text),
20
+ `markSeen`, `await` (wait for mail), `search`; sending takes `attachmentIds`.
21
+ - `threads` (list, read, file, star, hand to a person, delete, labels),
22
+ `labels`, `contacts`, `attachments` (`upload`, which goes straight to
23
+ storage over 4 MB; `get`, a five-minute link), `calendar`, `domains` (mail
24
+ on your own domain), `appPasswords` (for mail apps), `storage()`,
25
+ `testInbound()` (with a test key), and `webhooks`.
26
+ - `inboxes.create` takes `domain`; `inboxes.holdSuspicious`.
27
+ - Types follow the API: an inbox's `kind` is `agent` or `events`, and it has
28
+ `hold_suspicious` (no `owner_id`).
29
+
3
30
  ## 2.0.0
4
31
 
5
32
  For the new Pidgeon: Passport, Bouncer, Email and Auth. A new major version,
package/README.md CHANGED
@@ -70,9 +70,34 @@ const draft = await pidgeon.drafts.create(inbox.id, {
70
70
  text: '…',
71
71
  });
72
72
  await pidgeon.drafts.requestApproval(draft.id);
73
+
74
+ // Wait for mail, read it as the Firewall cleaned it, answer in its conversation:
75
+ let since: string | undefined;
76
+ for (;;) {
77
+ const { data, next_since } = await pidgeon.messages.await(inbox.id, { since, body: 'clean' });
78
+ for (const message of data) {
79
+ if (message.firewall?.verdict === 'suspicious') {
80
+ await pidgeon.threads.update(message.thread_id, {
81
+ ownerType: 'human',
82
+ status: 'human_review',
83
+ });
84
+ continue;
85
+ }
86
+ await pidgeon.messages.send(inbox.id, {
87
+ to: [message.from.address],
88
+ subject: `Re: ${message.subject}`,
89
+ text: 'On it.',
90
+ replyTo: message.id,
91
+ });
92
+ }
93
+ since = next_since;
94
+ }
73
95
  ```
74
96
 
75
- Also `pidgeon.rules`, `pidgeon.suppressions`, `pidgeon.events`, `pidgeon.pods`,
97
+ Also `pidgeon.threads`, `pidgeon.labels`, `pidgeon.contacts`,
98
+ `pidgeon.attachments` (`upload`, `get`), `pidgeon.calendar`,
99
+ `pidgeon.domains`, `pidgeon.appPasswords`, `pidgeon.webhooks`,
100
+ `pidgeon.rules`, `pidgeon.suppressions`, `pidgeon.events`, `pidgeon.pods`,
76
101
  and `pidgeon.request(method, path, …)` for any `/v1` call. A refusal throws
77
102
  `PidgeonError` with the API's `status` and `code`.
78
103
 
package/dist/index.d.ts CHANGED
@@ -98,18 +98,161 @@ export type AgentDetail = Agent & {
98
98
  next: string | null;
99
99
  };
100
100
  };
101
- export type InboxKind = 'person' | 'shared' | 'agent' | 'events';
101
+ /** `agent`: an agent's inbox (the default). `events`: receives only, as events. */
102
+ export type InboxKind = 'agent' | 'events';
102
103
  export type Inbox = {
103
104
  id: string;
104
105
  address: string;
105
106
  kind: InboxKind;
106
107
  display_name: string | null;
107
108
  pod_id: string;
108
- owner_id: string | null;
109
109
  agent_id: string | null;
110
110
  status: string;
111
+ /** Mail the Firewall calls suspicious waits for a person. */
112
+ hold_suspicious: boolean;
111
113
  created_at: string;
112
114
  };
115
+ /** The Firewall's reading of a received message. */
116
+ export type Firewall = {
117
+ verdict: 'clean' | 'suspicious';
118
+ signals: {
119
+ kind: string;
120
+ where: string;
121
+ detail?: string;
122
+ }[];
123
+ clean_text?: string;
124
+ version: number;
125
+ };
126
+ export type Attachment = {
127
+ id: string;
128
+ filename: string;
129
+ content_type: string;
130
+ size: number;
131
+ inline: boolean;
132
+ content_id: string | null;
133
+ };
134
+ /** A message as the API serves it. A held one has `is_held` and nothing it says. */
135
+ export type Message = {
136
+ id: string;
137
+ thread_id: string;
138
+ inbox_id: string;
139
+ direction: 'in' | 'out';
140
+ status: string;
141
+ is_held: boolean;
142
+ from: {
143
+ address: string;
144
+ name: string | null;
145
+ };
146
+ to: string[];
147
+ cc: string[];
148
+ bcc?: string[];
149
+ subject: string | null;
150
+ text: string | null;
151
+ html: string | null;
152
+ spam: boolean | null;
153
+ seen: boolean;
154
+ test: boolean;
155
+ attachments: Attachment[];
156
+ firewall: Firewall | null;
157
+ created_at: string;
158
+ sent_at: string | null;
159
+ };
160
+ export type Thread = {
161
+ id: string;
162
+ inbox_id: string;
163
+ subject: string | null;
164
+ folder: 'inbox' | 'archive' | 'spam' | 'trash';
165
+ starred: boolean;
166
+ status: 'open' | 'waiting' | 'resolved' | 'human_review';
167
+ owner_type: 'agent' | 'human' | 'automation';
168
+ assignee_id: string | null;
169
+ labels: {
170
+ id: string;
171
+ name: string;
172
+ colour: string;
173
+ }[];
174
+ message_count: number;
175
+ unread_count: number;
176
+ last_message_at: string;
177
+ created_at: string;
178
+ };
179
+ export type Label = {
180
+ id: string;
181
+ inbox_id: string;
182
+ name: string;
183
+ colour: string;
184
+ created_at: string;
185
+ };
186
+ export type Contact = {
187
+ id: string;
188
+ inbox_id: string;
189
+ email: string;
190
+ name: string | null;
191
+ notes: string | null;
192
+ first_seen_at: string | null;
193
+ last_seen_at: string | null;
194
+ edited_at: string | null;
195
+ created_at: string;
196
+ };
197
+ export type MailDomain = {
198
+ id: string;
199
+ domain: string;
200
+ mail: boolean;
201
+ status: 'pending' | 'verified' | 'failed' | null;
202
+ receiving: boolean;
203
+ /** Whether Pidgeon signs agents' `Agent-of` here: the `pgn2._domainkey` record answered at the last check. */
204
+ agent_signing: boolean;
205
+ checked_at: string | null;
206
+ records: {
207
+ purpose: string;
208
+ type: string;
209
+ name: string;
210
+ value: string;
211
+ priority?: number;
212
+ required: boolean;
213
+ }[];
214
+ };
215
+ export type AppPassword = {
216
+ id: string;
217
+ inbox_id: string;
218
+ name: string;
219
+ prefix: string;
220
+ last_used_at: string | null;
221
+ revoked_at: string | null;
222
+ created_at: string;
223
+ /** Answered once, when it is made. */
224
+ password?: string;
225
+ };
226
+ export type CalendarEvent = {
227
+ id: string;
228
+ title: string | null;
229
+ start: string;
230
+ end: string;
231
+ all_day: boolean;
232
+ description?: string | null;
233
+ location?: string | null;
234
+ organizer?: string | null;
235
+ attendees?: {
236
+ email: string;
237
+ status: 'needs_action' | 'accepted' | 'declined' | 'tentative';
238
+ }[];
239
+ /** After a write with `sendInvites`: who was sent the invitation, or why nobody was. */
240
+ invites?: {
241
+ sent_to: string[];
242
+ error: string | null;
243
+ };
244
+ [field: string]: unknown;
245
+ };
246
+ export type Webhook = {
247
+ id: string;
248
+ url: string;
249
+ events: string[];
250
+ /** The inboxes it hears; null when it hears the whole account. */
251
+ inbox_ids: string[] | null;
252
+ created_at: string;
253
+ disabled_at: string | null;
254
+ };
255
+ export type BodyChoice = 'original' | 'clean';
113
256
  /** What to send, or what a draft says. `replyTo` is one of the inbox's messages. */
114
257
  export type MessageInput = {
115
258
  to: string[];
@@ -119,6 +262,8 @@ export type MessageInput = {
119
262
  text?: string;
120
263
  html?: string;
121
264
  replyTo?: string;
265
+ /** Finished uploads of this inbox (`email.attachments.upload`). */
266
+ attachmentIds?: string[];
122
267
  };
123
268
  /** What sending answers: `sent`, `held` for a person's approval, or `scheduled`. */
124
269
  export type SendResult = {
@@ -269,14 +414,196 @@ export declare class Pidgeon {
269
414
  displayName?: string;
270
415
  agentId?: string;
271
416
  podId?: string;
417
+ /** One of your own domains with mail on; `pidgeon.email` when left out. */
418
+ domain?: string;
272
419
  }) => Promise<Inbox>;
420
+ /** Hold suspicious mail for a person. A key can turn holding on, never off. */
421
+ holdSuspicious: (id: string) => Promise<Inbox>;
273
422
  /** Remove an inbox. Its address is retired, never given to anyone again. */
274
423
  remove: (id: string) => Promise<void>;
275
424
  };
276
425
  readonly messages: {
277
426
  /** Send from an inbox: `status` is `sent`, or `held` while a person approves it. */
278
427
  send: (inboxId: string, input: MessageInput) => Promise<SendResult>;
428
+ /** The inbox's mail, newest first. `body: 'clean'` serves the Firewall's cleaned text. */
429
+ list: (inboxId: string, options?: ListOptions & {
430
+ body?: BodyChoice;
431
+ }) => Promise<Page<Message>>;
432
+ get: (id: string, options?: {
433
+ body?: BodyChoice;
434
+ }) => Promise<Message>;
435
+ /** Mark a received message read, or unread. */
436
+ markSeen: (id: string, seen?: boolean) => Promise<Message>;
437
+ /**
438
+ * Wait for mail: answers as soon as received mail newer than `since` (a
439
+ * time or a message id; default now) is there, or after `timeout`
440
+ * seconds (at most 50). Pass `next_since` back to wait for the next.
441
+ */
442
+ await: (inboxId: string, options?: {
443
+ since?: string;
444
+ timeout?: number;
445
+ body?: BodyChoice;
446
+ }) => Promise<{
447
+ data: Message[];
448
+ held: number;
449
+ next_since: string;
450
+ }>;
451
+ /** Mail by words in its subject, sender or text, newest first. */
452
+ search: (q: string, options?: ListOptions & {
453
+ inboxId?: string;
454
+ }) => Promise<Page<Message>>;
455
+ };
456
+ /** Conversations across your inboxes, and what is filed where. */
457
+ readonly threads: {
458
+ list: (options?: ListOptions & {
459
+ inboxId?: string;
460
+ folder?: Thread["folder"];
461
+ labelId?: string;
462
+ status?: Thread["status"];
463
+ starred?: boolean;
464
+ }) => Promise<Page<Thread>>;
465
+ /** The conversation, and its messages oldest first. */
466
+ get: (id: string, options?: ListOptions & {
467
+ body?: BodyChoice;
468
+ }) => Promise<Thread & {
469
+ messages: Page<Message>;
470
+ }>;
471
+ /** File, star or hand over: `{ ownerType: 'human', status: 'human_review' }` puts it before a person. */
472
+ update: (id: string, input: {
473
+ folder?: Thread["folder"];
474
+ starred?: boolean;
475
+ status?: Thread["status"];
476
+ ownerType?: Thread["owner_type"];
477
+ assigneeId?: string | null;
478
+ }) => Promise<Thread>;
479
+ /** Delete the conversation, its messages and files, for good. */
480
+ remove: (id: string) => Promise<void>;
481
+ addLabel: (id: string, labelId: string) => Promise<Thread>;
482
+ removeLabel: (id: string, labelId: string) => Promise<Thread>;
483
+ };
484
+ /** An inbox's labels. */
485
+ readonly labels: {
486
+ list: (inboxId: string) => Promise<{
487
+ data: Label[];
488
+ }>;
489
+ create: (inboxId: string, input: {
490
+ name: string;
491
+ colour?: string;
492
+ }) => Promise<Label>;
493
+ update: (id: string, input: {
494
+ name?: string;
495
+ colour?: string;
496
+ }) => Promise<Label>;
497
+ remove: (id: string) => Promise<void>;
498
+ };
499
+ /** Files: those that arrived, and uploads to send. */
500
+ readonly attachments: {
501
+ /** Its details and a link to its bytes that lasts five minutes. */
502
+ get: (id: string) => Promise<Attachment & {
503
+ url: string;
504
+ expires_in: number;
505
+ }>;
506
+ /** Upload a file to send (name its id in `attachmentIds`). Up to 25 MB; over 4 MB goes straight to storage. */
507
+ upload: (inboxId: string, file: {
508
+ filename: string;
509
+ contentType: string;
510
+ content: Uint8Array | ArrayBuffer | Blob;
511
+ }) => Promise<Attachment>;
512
+ };
513
+ /** Who an inbox corresponds with. */
514
+ readonly contacts: {
515
+ list: (options?: ListOptions & {
516
+ inboxId?: string;
517
+ search?: string;
518
+ }) => Promise<Page<Contact>>;
519
+ get: (id: string) => Promise<Contact>;
520
+ update: (id: string, input: {
521
+ name?: string | null;
522
+ notes?: string | null;
523
+ }) => Promise<Contact>;
524
+ remove: (id: string) => Promise<void>;
525
+ };
526
+ /** Each inbox's calendar. */
527
+ readonly calendar: {
528
+ list: (inboxId: string, options?: ListOptions & {
529
+ after?: string;
530
+ before?: string;
531
+ }) => Promise<Page<CalendarEvent>>;
532
+ get: (id: string) => Promise<CalendarEvent>;
533
+ create: (inboxId: string, input: {
534
+ title: string;
535
+ start: string;
536
+ end: string;
537
+ allDay?: boolean;
538
+ description?: string;
539
+ location?: string;
540
+ /** Who is on it; writing the list sends nothing. */
541
+ attendees?: string[];
542
+ /** Invite them now (a key with `send` access): an email from the inbox with the `.ics`. */
543
+ sendInvites?: boolean;
544
+ }) => Promise<CalendarEvent>;
545
+ update: (id: string, input: {
546
+ title?: string;
547
+ start?: string;
548
+ end?: string;
549
+ allDay?: boolean;
550
+ description?: string;
551
+ location?: string;
552
+ attendees?: string[];
553
+ /** Send the attendees the updated invitation (a key with `send` access). */
554
+ sendInvites?: boolean;
555
+ }) => Promise<CalendarEvent>;
556
+ /** With `sendInvites`, the attendees are sent a cancellation first (a key with `send` access). */
557
+ remove: (id: string, options?: {
558
+ sendInvites?: boolean;
559
+ }) => Promise<void | {
560
+ deleted: true;
561
+ invites: {
562
+ sent_to: string[];
563
+ error: string | null;
564
+ };
565
+ }>;
566
+ };
567
+ /** Inboxes on your own domains. A key of the whole account only. */
568
+ readonly domains: {
569
+ list: () => Promise<{
570
+ data: MailDomain[];
571
+ }>;
572
+ get: (id: string) => Promise<MailDomain>;
573
+ /** Turn mail on for a domain you proved; answers the DNS records to set. */
574
+ enableMail: (id: string) => Promise<MailDomain>;
575
+ disableMail: (id: string) => Promise<void>;
576
+ /** Ask DNS and the mail service where the domain stands now. */
577
+ check: (id: string) => Promise<MailDomain>;
578
+ };
579
+ /** Passwords for mail apps (IMAP, SMTP, CalDAV), one inbox each. */
580
+ readonly appPasswords: {
581
+ list: (inboxId: string) => Promise<{
582
+ data: AppPassword[];
583
+ }>;
584
+ /** Answers `password` this once. */
585
+ create: (inboxId: string, name: string) => Promise<AppPassword>;
586
+ revoke: (id: string) => Promise<void>;
279
587
  };
588
+ /** How much of the account's 10 GB its mail and files use. */
589
+ storage(): Promise<{
590
+ used_bytes: number;
591
+ limit_bytes: number;
592
+ }>;
593
+ /** With a test key: deliver a message to one of your inboxes as if from outside, marked test. */
594
+ testInbound(input: {
595
+ inboxId: string;
596
+ from: string;
597
+ fromName?: string;
598
+ subject: string;
599
+ text?: string;
600
+ html?: string;
601
+ inReplyTo?: string;
602
+ }): Promise<{
603
+ inbox_id: string;
604
+ message_id: string | null;
605
+ outcome: string | null;
606
+ }>;
280
607
  readonly drafts: {
281
608
  create: (inboxId: string, input: MessageInput) => Promise<Draft>;
282
609
  get: (id: string) => Promise<Draft>;
@@ -353,6 +680,27 @@ export declare class Pidgeon {
353
680
  }>;
354
681
  create: (name: string) => Promise<Pod>;
355
682
  };
683
+ /** Your webhook endpoints. A key of the whole account only. */
684
+ readonly webhooks: {
685
+ list: () => Promise<{
686
+ data: Webhook[];
687
+ }>;
688
+ /**
689
+ * Answers `secret` once: check each delivery's signature with it (`verifyWebhook`).
690
+ * With `inboxIds` it hears only those inboxes' events; without, the whole account's.
691
+ */
692
+ create: (input: {
693
+ url: string;
694
+ events: string[];
695
+ inboxIds?: string[];
696
+ }) => Promise<{
697
+ id: string;
698
+ secret: string;
699
+ }>;
700
+ remove: (id: string) => Promise<void>;
701
+ };
702
+ /** A multipart POST (uploads): the same authentication and errors as `request`. */
703
+ private multipart;
356
704
  }
357
705
  /** `fetch`, signed as your agent: every request carries its Web Bot Auth signature. */
358
706
  export declare function signedFetch(input: string | URL | Request, init: RequestInit | undefined, agent: {
package/dist/index.js CHANGED
@@ -49,6 +49,7 @@ const messageBody = (input) => ({
49
49
  text: input.text,
50
50
  html: input.html,
51
51
  reply_to: input.replyTo,
52
+ attachment_ids: input.attachmentIds,
52
53
  });
53
54
  const segment = (id) => encodeURIComponent(id);
54
55
  /**
@@ -162,8 +163,13 @@ export class Pidgeon {
162
163
  display_name: input.displayName,
163
164
  agent_id: input.agentId,
164
165
  pod_id: input.podId,
166
+ domain: input.domain,
165
167
  },
166
168
  }),
169
+ /** Hold suspicious mail for a person. A key can turn holding on, never off. */
170
+ holdSuspicious: (id) => this.request('PATCH', `/v1/email/inboxes/${segment(id)}`, {
171
+ body: { hold_suspicious: true },
172
+ }),
167
173
  /** Remove an inbox. Its address is retired, never given to anyone again. */
168
174
  remove: (id) => this.request('DELETE', `/v1/email/inboxes/${segment(id)}`),
169
175
  };
@@ -172,7 +178,174 @@ export class Pidgeon {
172
178
  send: (inboxId, input) => this.request('POST', `/v1/email/inboxes/${segment(inboxId)}/messages`, {
173
179
  body: messageBody(input),
174
180
  }),
181
+ /** The inbox's mail, newest first. `body: 'clean'` serves the Firewall's cleaned text. */
182
+ list: (inboxId, options = {}) => this.request('GET', `/v1/email/inboxes/${segment(inboxId)}/messages`, { query: options }),
183
+ get: (id, options = {}) => this.request('GET', `/v1/email/messages/${segment(id)}`, { query: options }),
184
+ /** Mark a received message read, or unread. */
185
+ markSeen: (id, seen = true) => this.request('PATCH', `/v1/email/messages/${segment(id)}`, { body: { seen } }),
186
+ /**
187
+ * Wait for mail: answers as soon as received mail newer than `since` (a
188
+ * time or a message id; default now) is there, or after `timeout`
189
+ * seconds (at most 50). Pass `next_since` back to wait for the next.
190
+ */
191
+ await: (inboxId, options = {}) => this.request('GET', `/v1/email/inboxes/${segment(inboxId)}/messages/await`, {
192
+ query: options,
193
+ }),
194
+ /** Mail by words in its subject, sender or text, newest first. */
195
+ search: (q, options = {}) => this.request('GET', '/v1/email/search', {
196
+ query: { q, inbox_id: options.inboxId, limit: options.limit, cursor: options.cursor },
197
+ }),
198
+ };
199
+ /** Conversations across your inboxes, and what is filed where. */
200
+ threads = {
201
+ list: (options = {}) => this.request('GET', '/v1/email/threads', {
202
+ query: {
203
+ inbox_id: options.inboxId,
204
+ folder: options.folder,
205
+ label_id: options.labelId,
206
+ status: options.status,
207
+ starred: options.starred ? 'true' : undefined,
208
+ limit: options.limit,
209
+ cursor: options.cursor,
210
+ },
211
+ }),
212
+ /** The conversation, and its messages oldest first. */
213
+ get: (id, options = {}) => this.request('GET', `/v1/email/threads/${segment(id)}`, { query: options }),
214
+ /** File, star or hand over: `{ ownerType: 'human', status: 'human_review' }` puts it before a person. */
215
+ update: (id, input) => this.request('PATCH', `/v1/email/threads/${segment(id)}`, {
216
+ body: {
217
+ folder: input.folder,
218
+ starred: input.starred,
219
+ status: input.status,
220
+ owner_type: input.ownerType,
221
+ assignee_id: input.assigneeId,
222
+ },
223
+ }),
224
+ /** Delete the conversation, its messages and files, for good. */
225
+ remove: (id) => this.request('DELETE', `/v1/email/threads/${segment(id)}`),
226
+ addLabel: (id, labelId) => this.request('POST', `/v1/email/threads/${segment(id)}/labels`, {
227
+ body: { label_id: labelId },
228
+ }),
229
+ removeLabel: (id, labelId) => this.request('DELETE', `/v1/email/threads/${segment(id)}/labels/${segment(labelId)}`),
230
+ };
231
+ /** An inbox's labels. */
232
+ labels = {
233
+ list: (inboxId) => this.request('GET', `/v1/email/inboxes/${segment(inboxId)}/labels`),
234
+ create: (inboxId, input) => this.request('POST', `/v1/email/inboxes/${segment(inboxId)}/labels`, { body: input }),
235
+ update: (id, input) => this.request('PATCH', `/v1/email/labels/${segment(id)}`, { body: input }),
236
+ remove: (id) => this.request('DELETE', `/v1/email/labels/${segment(id)}`),
175
237
  };
238
+ /** Files: those that arrived, and uploads to send. */
239
+ attachments = {
240
+ /** Its details and a link to its bytes that lasts five minutes. */
241
+ get: (id) => this.request('GET', `/v1/email/attachments/${segment(id)}`),
242
+ /** Upload a file to send (name its id in `attachmentIds`). Up to 25 MB; over 4 MB goes straight to storage. */
243
+ upload: async (inboxId, file) => {
244
+ const blob = file.content instanceof Blob
245
+ ? file.content
246
+ : new Blob([file.content], { type: file.contentType });
247
+ if (blob.size <= 4 * 1024 * 1024) {
248
+ const form = new FormData();
249
+ form.set('file', new File([blob], file.filename, { type: file.contentType }));
250
+ return this.multipart(`/v1/email/inboxes/${segment(inboxId)}/attachments`, form);
251
+ }
252
+ const made = await this.request('POST', `/v1/email/inboxes/${segment(inboxId)}/attachments/uploads`, { body: { filename: file.filename, content_type: file.contentType, size: blob.size } });
253
+ const put = await this.fetchImpl(made.upload.url, {
254
+ method: 'PUT',
255
+ headers: { 'content-type': file.contentType },
256
+ body: blob,
257
+ });
258
+ if (!put.ok)
259
+ throw new PidgeonError(put.status, 'upload_failed', 'Storage refused the file.');
260
+ return this.request('POST', `/v1/email/attachments/${segment(made.id)}/complete`, {
261
+ body: {},
262
+ });
263
+ },
264
+ };
265
+ /** Who an inbox corresponds with. */
266
+ contacts = {
267
+ list: (options = {}) => this.request('GET', '/v1/email/contacts', {
268
+ query: {
269
+ inbox_id: options.inboxId,
270
+ search: options.search,
271
+ limit: options.limit,
272
+ cursor: options.cursor,
273
+ },
274
+ }),
275
+ get: (id) => this.request('GET', `/v1/email/contacts/${segment(id)}`),
276
+ update: (id, input) => this.request('PATCH', `/v1/email/contacts/${segment(id)}`, { body: input }),
277
+ remove: (id) => this.request('DELETE', `/v1/email/contacts/${segment(id)}`),
278
+ };
279
+ /** Each inbox's calendar. */
280
+ calendar = {
281
+ list: (inboxId, options = {}) => this.request('GET', `/v1/email/inboxes/${segment(inboxId)}/events`, { query: options }),
282
+ get: (id) => this.request('GET', `/v1/email/events/${segment(id)}`),
283
+ create: (inboxId, input) => this.request('POST', `/v1/email/inboxes/${segment(inboxId)}/events`, {
284
+ body: {
285
+ title: input.title,
286
+ start: input.start,
287
+ end: input.end,
288
+ all_day: input.allDay,
289
+ description: input.description,
290
+ location: input.location,
291
+ attendees: input.attendees,
292
+ send_invites: input.sendInvites,
293
+ },
294
+ }),
295
+ update: (id, input) => this.request('PATCH', `/v1/email/events/${segment(id)}`, {
296
+ body: {
297
+ title: input.title,
298
+ start: input.start,
299
+ end: input.end,
300
+ all_day: input.allDay,
301
+ description: input.description,
302
+ location: input.location,
303
+ attendees: input.attendees,
304
+ send_invites: input.sendInvites,
305
+ },
306
+ }),
307
+ /** With `sendInvites`, the attendees are sent a cancellation first (a key with `send` access). */
308
+ remove: (id, options = {}) => this.request('DELETE', `/v1/email/events/${segment(id)}`, {
309
+ query: options.sendInvites ? { send_invites: 'true' } : undefined,
310
+ }),
311
+ };
312
+ /** Inboxes on your own domains. A key of the whole account only. */
313
+ domains = {
314
+ list: () => this.request('GET', '/v1/email/domains'),
315
+ get: (id) => this.request('GET', `/v1/email/domains/${segment(id)}`),
316
+ /** Turn mail on for a domain you proved; answers the DNS records to set. */
317
+ enableMail: (id) => this.request('POST', `/v1/email/domains/${segment(id)}/mail`, { body: {} }),
318
+ disableMail: (id) => this.request('DELETE', `/v1/email/domains/${segment(id)}/mail`),
319
+ /** Ask DNS and the mail service where the domain stands now. */
320
+ check: (id) => this.request('POST', `/v1/email/domains/${segment(id)}/check`, { body: {} }),
321
+ };
322
+ /** Passwords for mail apps (IMAP, SMTP, CalDAV), one inbox each. */
323
+ appPasswords = {
324
+ list: (inboxId) => this.request('GET', `/v1/email/inboxes/${segment(inboxId)}/app-passwords`),
325
+ /** Answers `password` this once. */
326
+ create: (inboxId, name) => this.request('POST', `/v1/email/inboxes/${segment(inboxId)}/app-passwords`, {
327
+ body: { name },
328
+ }),
329
+ revoke: (id) => this.request('DELETE', `/v1/email/app-passwords/${segment(id)}`),
330
+ };
331
+ /** How much of the account's 10 GB its mail and files use. */
332
+ storage() {
333
+ return this.request('GET', '/v1/email/storage');
334
+ }
335
+ /** With a test key: deliver a message to one of your inboxes as if from outside, marked test. */
336
+ testInbound(input) {
337
+ return this.request('POST', '/v1/email/test/inbound', {
338
+ body: {
339
+ inbox_id: input.inboxId,
340
+ from: input.from,
341
+ from_name: input.fromName,
342
+ subject: input.subject,
343
+ text: input.text,
344
+ html: input.html,
345
+ in_reply_to: input.inReplyTo,
346
+ },
347
+ });
348
+ }
176
349
  drafts = {
177
350
  create: (inboxId, input) => this.request('POST', `/v1/email/inboxes/${segment(inboxId)}/drafts`, {
178
351
  body: messageBody(input),
@@ -243,6 +416,31 @@ export class Pidgeon {
243
416
  list: () => this.request('GET', '/v1/pods'),
244
417
  create: (name) => this.request('POST', '/v1/pods', { body: { name } }),
245
418
  };
419
+ /** Your webhook endpoints. A key of the whole account only. */
420
+ webhooks = {
421
+ list: () => this.request('GET', '/v1/webhooks'),
422
+ /**
423
+ * Answers `secret` once: check each delivery's signature with it (`verifyWebhook`).
424
+ * With `inboxIds` it hears only those inboxes' events; without, the whole account's.
425
+ */
426
+ create: (input) => this.request('POST', '/v1/webhooks', {
427
+ body: { url: input.url, events: input.events, inbox_ids: input.inboxIds },
428
+ }),
429
+ remove: (id) => this.request('DELETE', `/v1/webhooks/${segment(id)}`),
430
+ };
431
+ /** A multipart POST (uploads): the same authentication and errors as `request`. */
432
+ async multipart(path, form) {
433
+ const response = await this.fetchImpl(new URL(`${this.baseUrl}${path}`), {
434
+ method: 'POST',
435
+ headers: { authorization: `Bearer ${await this.token()}` },
436
+ body: form,
437
+ });
438
+ const data = (await response.json().catch(() => null));
439
+ if (!response.ok) {
440
+ throw new PidgeonError(response.status, data?.error?.code ?? 'error', data?.error?.message ?? `Pidgeon answered ${response.status}.`);
441
+ }
442
+ return data;
443
+ }
246
444
  }
247
445
  /** `fetch`, signed as your agent: every request carries its Web Bot Auth signature. */
248
446
  export async function signedFetch(input, init, agent) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pidgeon-ai/sdk",
3
- "version": "2.0.0",
3
+ "version": "2.2.0",
4
4
  "description": "Pidgeon's TypeScript SDK: Passport, Bouncer, Email and Auth. Sign your agents' requests, verify agents at your site, send mail from agent inboxes, and Sign in with Pidgeon.",
5
5
  "license": "Apache-2.0",
6
6
  "type": "module",