@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 +27 -0
- package/README.md +26 -1
- package/dist/index.d.ts +350 -2
- package/dist/index.js +198 -0
- package/package.json +1 -1
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.
|
|
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
|
-
|
|
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.
|
|
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",
|