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