@pidgeon-ai/sdk 2.0.0 → 2.1.1

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,27 @@
1
1
  # Changelog
2
2
 
3
+ ## 2.1.1
4
+
5
+ - `calendar.create` and `calendar.update` take `attendees` and `sendInvites`,
6
+ and `calendar.remove` takes `{ sendInvites }`: the attendees get an
7
+ invitation, an update or a cancellation from the inbox. `CalendarEvent` has
8
+ `organizer`, `attendees` and, after a write that sent, `invites`.
9
+
10
+ ## 2.1.0
11
+
12
+ All of Email, and webhooks. Additive: 2.0 code runs unchanged.
13
+
14
+ - `messages`: `list`, `get` (`body: 'clean'` for the Firewall's cleaned text),
15
+ `markSeen`, `await` (wait for mail), `search`; sending takes `attachmentIds`.
16
+ - `threads` (list, read, file, star, hand to a person, delete, labels),
17
+ `labels`, `contacts`, `attachments` (`upload`, which goes straight to
18
+ storage over 4 MB; `get`, a five-minute link), `calendar`, `domains` (mail
19
+ on your own domain), `appPasswords` (for mail apps), `storage()`,
20
+ `testInbound()` (with a test key), and `webhooks`.
21
+ - `inboxes.create` takes `domain`; `inboxes.holdSuspicious`.
22
+ - Types follow the API: an inbox's `kind` is `agent` or `events`, and it has
23
+ `hold_suspicious` (no `owner_id`).
24
+
3
25
  ## 2.0.0
4
26
 
5
27
  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,157 @@ 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
+ checked_at: string | null;
204
+ records: {
205
+ purpose: string;
206
+ type: string;
207
+ name: string;
208
+ value: string;
209
+ priority?: number;
210
+ required: boolean;
211
+ }[];
212
+ };
213
+ export type AppPassword = {
214
+ id: string;
215
+ inbox_id: string;
216
+ name: string;
217
+ prefix: string;
218
+ last_used_at: string | null;
219
+ revoked_at: string | null;
220
+ created_at: string;
221
+ /** Answered once, when it is made. */
222
+ password?: string;
223
+ };
224
+ export type CalendarEvent = {
225
+ id: string;
226
+ title: string | null;
227
+ start: string;
228
+ end: string;
229
+ all_day: boolean;
230
+ description?: string | null;
231
+ location?: string | null;
232
+ organizer?: string | null;
233
+ attendees?: {
234
+ email: string;
235
+ status: 'needs_action' | 'accepted' | 'declined' | 'tentative';
236
+ }[];
237
+ /** After a write with `sendInvites`: who was sent the invitation, or why nobody was. */
238
+ invites?: {
239
+ sent_to: string[];
240
+ error: string | null;
241
+ };
242
+ [field: string]: unknown;
243
+ };
244
+ export type Webhook = {
245
+ id: string;
246
+ url: string;
247
+ events: string[];
248
+ created_at: string;
249
+ disabled_at: string | null;
250
+ };
251
+ export type BodyChoice = 'original' | 'clean';
113
252
  /** What to send, or what a draft says. `replyTo` is one of the inbox's messages. */
114
253
  export type MessageInput = {
115
254
  to: string[];
@@ -119,6 +258,8 @@ export type MessageInput = {
119
258
  text?: string;
120
259
  html?: string;
121
260
  replyTo?: string;
261
+ /** Finished uploads of this inbox (`email.attachments.upload`). */
262
+ attachmentIds?: string[];
122
263
  };
123
264
  /** What sending answers: `sent`, `held` for a person's approval, or `scheduled`. */
124
265
  export type SendResult = {
@@ -269,14 +410,196 @@ export declare class Pidgeon {
269
410
  displayName?: string;
270
411
  agentId?: string;
271
412
  podId?: string;
413
+ /** One of your own domains with mail on; `pidgeon.email` when left out. */
414
+ domain?: string;
272
415
  }) => Promise<Inbox>;
416
+ /** Hold suspicious mail for a person. A key can turn holding on, never off. */
417
+ holdSuspicious: (id: string) => Promise<Inbox>;
273
418
  /** Remove an inbox. Its address is retired, never given to anyone again. */
274
419
  remove: (id: string) => Promise<void>;
275
420
  };
276
421
  readonly messages: {
277
422
  /** Send from an inbox: `status` is `sent`, or `held` while a person approves it. */
278
423
  send: (inboxId: string, input: MessageInput) => Promise<SendResult>;
424
+ /** The inbox's mail, newest first. `body: 'clean'` serves the Firewall's cleaned text. */
425
+ list: (inboxId: string, options?: ListOptions & {
426
+ body?: BodyChoice;
427
+ }) => Promise<Page<Message>>;
428
+ get: (id: string, options?: {
429
+ body?: BodyChoice;
430
+ }) => Promise<Message>;
431
+ /** Mark a received message read, or unread. */
432
+ markSeen: (id: string, seen?: boolean) => Promise<Message>;
433
+ /**
434
+ * Wait for mail: answers as soon as received mail newer than `since` (a
435
+ * time or a message id; default now) is there, or after `timeout`
436
+ * seconds (at most 50). Pass `next_since` back to wait for the next.
437
+ */
438
+ await: (inboxId: string, options?: {
439
+ since?: string;
440
+ timeout?: number;
441
+ body?: BodyChoice;
442
+ }) => Promise<{
443
+ data: Message[];
444
+ held: number;
445
+ next_since: string;
446
+ }>;
447
+ /** Mail by words in its subject, sender or text, newest first. */
448
+ search: (q: string, options?: ListOptions & {
449
+ inboxId?: string;
450
+ }) => Promise<Page<Message>>;
279
451
  };
452
+ /** Conversations across your inboxes, and what is filed where. */
453
+ readonly threads: {
454
+ list: (options?: ListOptions & {
455
+ inboxId?: string;
456
+ folder?: Thread["folder"];
457
+ labelId?: string;
458
+ status?: Thread["status"];
459
+ starred?: boolean;
460
+ }) => Promise<Page<Thread>>;
461
+ /** The conversation, and its messages oldest first. */
462
+ get: (id: string, options?: ListOptions & {
463
+ body?: BodyChoice;
464
+ }) => Promise<Thread & {
465
+ messages: Page<Message>;
466
+ }>;
467
+ /** File, star or hand over: `{ ownerType: 'human', status: 'human_review' }` puts it before a person. */
468
+ update: (id: string, input: {
469
+ folder?: Thread["folder"];
470
+ starred?: boolean;
471
+ status?: Thread["status"];
472
+ ownerType?: Thread["owner_type"];
473
+ assigneeId?: string | null;
474
+ }) => Promise<Thread>;
475
+ /** Delete the conversation, its messages and files, for good. */
476
+ remove: (id: string) => Promise<void>;
477
+ addLabel: (id: string, labelId: string) => Promise<Thread>;
478
+ removeLabel: (id: string, labelId: string) => Promise<Thread>;
479
+ };
480
+ /** An inbox's labels. */
481
+ readonly labels: {
482
+ list: (inboxId: string) => Promise<{
483
+ data: Label[];
484
+ }>;
485
+ create: (inboxId: string, input: {
486
+ name: string;
487
+ colour?: string;
488
+ }) => Promise<Label>;
489
+ update: (id: string, input: {
490
+ name?: string;
491
+ colour?: string;
492
+ }) => Promise<Label>;
493
+ remove: (id: string) => Promise<void>;
494
+ };
495
+ /** Files: those that arrived, and uploads to send. */
496
+ readonly attachments: {
497
+ /** Its details and a link to its bytes that lasts five minutes. */
498
+ get: (id: string) => Promise<Attachment & {
499
+ url: string;
500
+ expires_in: number;
501
+ }>;
502
+ /** Upload a file to send (name its id in `attachmentIds`). Up to 25 MB; over 4 MB goes straight to storage. */
503
+ upload: (inboxId: string, file: {
504
+ filename: string;
505
+ contentType: string;
506
+ content: Uint8Array | ArrayBuffer | Blob;
507
+ }) => Promise<Attachment>;
508
+ };
509
+ /** Who an inbox corresponds with. */
510
+ readonly contacts: {
511
+ list: (options?: ListOptions & {
512
+ inboxId?: string;
513
+ search?: string;
514
+ }) => Promise<Page<Contact>>;
515
+ get: (id: string) => Promise<Contact>;
516
+ update: (id: string, input: {
517
+ name?: string | null;
518
+ notes?: string | null;
519
+ }) => Promise<Contact>;
520
+ remove: (id: string) => Promise<void>;
521
+ };
522
+ /** Each inbox's calendar. */
523
+ readonly calendar: {
524
+ list: (inboxId: string, options?: ListOptions & {
525
+ after?: string;
526
+ before?: string;
527
+ }) => Promise<Page<CalendarEvent>>;
528
+ get: (id: string) => Promise<CalendarEvent>;
529
+ create: (inboxId: string, input: {
530
+ title: string;
531
+ start: string;
532
+ end: string;
533
+ allDay?: boolean;
534
+ description?: string;
535
+ location?: string;
536
+ /** Who is on it; writing the list sends nothing. */
537
+ attendees?: string[];
538
+ /** Invite them now (a key with `send` access): an email from the inbox with the `.ics`. */
539
+ sendInvites?: boolean;
540
+ }) => Promise<CalendarEvent>;
541
+ update: (id: string, input: {
542
+ title?: string;
543
+ start?: string;
544
+ end?: string;
545
+ allDay?: boolean;
546
+ description?: string;
547
+ location?: string;
548
+ attendees?: string[];
549
+ /** Send the attendees the updated invitation (a key with `send` access). */
550
+ sendInvites?: boolean;
551
+ }) => Promise<CalendarEvent>;
552
+ /** With `sendInvites`, the attendees are sent a cancellation first (a key with `send` access). */
553
+ remove: (id: string, options?: {
554
+ sendInvites?: boolean;
555
+ }) => Promise<void | {
556
+ deleted: true;
557
+ invites: {
558
+ sent_to: string[];
559
+ error: string | null;
560
+ };
561
+ }>;
562
+ };
563
+ /** Inboxes on your own domains. A key of the whole account only. */
564
+ readonly domains: {
565
+ list: () => Promise<{
566
+ data: MailDomain[];
567
+ }>;
568
+ get: (id: string) => Promise<MailDomain>;
569
+ /** Turn mail on for a domain you proved; answers the DNS records to set. */
570
+ enableMail: (id: string) => Promise<MailDomain>;
571
+ disableMail: (id: string) => Promise<void>;
572
+ /** Ask DNS and the mail service where the domain stands now. */
573
+ check: (id: string) => Promise<MailDomain>;
574
+ };
575
+ /** Passwords for mail apps (IMAP, SMTP, CalDAV), one inbox each. */
576
+ readonly appPasswords: {
577
+ list: (inboxId: string) => Promise<{
578
+ data: AppPassword[];
579
+ }>;
580
+ /** Answers `password` this once. */
581
+ create: (inboxId: string, name: string) => Promise<AppPassword>;
582
+ revoke: (id: string) => Promise<void>;
583
+ };
584
+ /** How much of the account's 10 GB its mail and files use. */
585
+ storage(): Promise<{
586
+ used_bytes: number;
587
+ limit_bytes: number;
588
+ }>;
589
+ /** With a test key: deliver a message to one of your inboxes as if from outside, marked test. */
590
+ testInbound(input: {
591
+ inboxId: string;
592
+ from: string;
593
+ fromName?: string;
594
+ subject: string;
595
+ text?: string;
596
+ html?: string;
597
+ inReplyTo?: string;
598
+ }): Promise<{
599
+ inbox_id: string;
600
+ message_id: string | null;
601
+ outcome: string | null;
602
+ }>;
280
603
  readonly drafts: {
281
604
  create: (inboxId: string, input: MessageInput) => Promise<Draft>;
282
605
  get: (id: string) => Promise<Draft>;
@@ -353,6 +676,23 @@ export declare class Pidgeon {
353
676
  }>;
354
677
  create: (name: string) => Promise<Pod>;
355
678
  };
679
+ /** Your webhook endpoints. A key of the whole account only. */
680
+ readonly webhooks: {
681
+ list: () => Promise<{
682
+ data: Webhook[];
683
+ }>;
684
+ /** Answers `secret` once: check each delivery's signature with it (`verifyWebhook`). */
685
+ create: (input: {
686
+ url: string;
687
+ events: string[];
688
+ }) => Promise<{
689
+ id: string;
690
+ secret: string;
691
+ }>;
692
+ remove: (id: string) => Promise<void>;
693
+ };
694
+ /** A multipart POST (uploads): the same authentication and errors as `request`. */
695
+ private multipart;
356
696
  }
357
697
  /** `fetch`, signed as your agent: every request carries its Web Bot Auth signature. */
358
698
  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)}`),
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)}`),
175
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,26 @@ 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
+ /** Answers `secret` once: check each delivery's signature with it (`verifyWebhook`). */
423
+ create: (input) => this.request('POST', '/v1/webhooks', { body: input }),
424
+ remove: (id) => this.request('DELETE', `/v1/webhooks/${segment(id)}`),
425
+ };
426
+ /** A multipart POST (uploads): the same authentication and errors as `request`. */
427
+ async multipart(path, form) {
428
+ const response = await this.fetchImpl(new URL(`${this.baseUrl}${path}`), {
429
+ method: 'POST',
430
+ headers: { authorization: `Bearer ${await this.token()}` },
431
+ body: form,
432
+ });
433
+ const data = (await response.json().catch(() => null));
434
+ if (!response.ok) {
435
+ throw new PidgeonError(response.status, data?.error?.code ?? 'error', data?.error?.message ?? `Pidgeon answered ${response.status}.`);
436
+ }
437
+ return data;
438
+ }
246
439
  }
247
440
  /** `fetch`, signed as your agent: every request carries its Web Bot Auth signature. */
248
441
  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.1.1",
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",