@noisybrood/cli 0.0.0-stage → 0.1.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/LICENSE +202 -0
- package/README.md +74 -2
- package/dist/brood/api/src/fields.js +335 -0
- package/dist/brood/api/src/index.js +528 -0
- package/dist/brood/api/src/values.js +59 -0
- package/dist/brood/figures/index.js +10 -0
- package/dist/brood/tokens/dark.css +86 -0
- package/dist/brood/tokens/src/contrast.js +109 -0
- package/dist/brood/tokens/src/wren.js +58 -0
- package/dist/brood.js +11 -0
- package/dist/client.js +100 -0
- package/dist/commands.js +417 -0
- package/dist/io.js +50 -0
- package/dist/main.js +193 -0
- package/dist/out.js +53 -0
- package/dist/sign-in.js +129 -0
- package/dist/store.js +83 -0
- package/dist/version.js +16 -0
- package/dist/wren.js +153 -0
- package/package.json +37 -4
|
@@ -0,0 +1,528 @@
|
|
|
1
|
+
import { API_ACTS_PER_MINUTE, API_CALLS_PER_MINUTE, API_PAGE_MAX, API_UNUSED_DAYS, API_STRETCH_DAYS, PORTRAIT_DAYS, QUIET_REGULAR_MIN_MONTHS, QUIET_REGULAR_MONTHS, RETENTION_DAYS, } from "../../figures/index.js";
|
|
2
|
+
/**
|
|
3
|
+
* The API's one list of operations (DD21 §1): each name, the scope it needs,
|
|
4
|
+
* what it does and what each of its arguments means, and the types and
|
|
5
|
+
* narrowing of its arguments and answer. `apps/web` implements it, behind one
|
|
6
|
+
* gate; the CLI and the MCP server call it, so a client cannot call an
|
|
7
|
+
* operation this list does not have; and the docs' reference is rendered from
|
|
8
|
+
* it (#1344): what an operation is called with is said where it is
|
|
9
|
+
* defined, and its arguments are narrowed by the keys described. It grows
|
|
10
|
+
* by addition within v1 (DD21 §11): an operation is listed here in the
|
|
11
|
+
* change that implements it.
|
|
12
|
+
*
|
|
13
|
+
* Arguments arrive as JSON from outside, so each is narrowed by hand, as
|
|
14
|
+
* conventions/typescript.md asks of a value from an edge, rather than with a
|
|
15
|
+
* schema library, which would be a dependency in the path of every request.
|
|
16
|
+
* The keys an operation accepts are the keys its `arguments` describe, so an
|
|
17
|
+
* argument cannot be accepted without being documented.
|
|
18
|
+
*/
|
|
19
|
+
/** Where every operation is called, by POST with its arguments in the body (DD21 §2, §3). */
|
|
20
|
+
export const API_BASE = "https://app.noisybrood.com/api/v1";
|
|
21
|
+
/**
|
|
22
|
+
* Where a client signs in (DD21 §4): Clerk's OAuth server for the production
|
|
23
|
+
* instance, and each client's id there. A client id is not a secret: a public
|
|
24
|
+
* client is known by it alone, and ships it (#1354).
|
|
25
|
+
*/
|
|
26
|
+
export const SIGN_IN = {
|
|
27
|
+
issuer: "https://clerk.app.noisybrood.com",
|
|
28
|
+
clients: { cli: "P029s9c7VAQInceB" },
|
|
29
|
+
};
|
|
30
|
+
export * from "./values.js";
|
|
31
|
+
import { CLASSIFICATION_STATES, listed, } from "./values.js";
|
|
32
|
+
const OWNER = "The person whose index to read, by their user id, for a helper they have granted access. Leave it out to read your own.";
|
|
33
|
+
const LIMIT = `How many to return, from 1 to ${API_PAGE_MAX}.`;
|
|
34
|
+
const CURSOR = "Where to carry on from: the `next` of the page before. Leave it out for the first page.";
|
|
35
|
+
const SINCE = `The first day of the stretch, as YYYY-MM-DD in UTC. Leave it out for the ${API_STRETCH_DAYS} days ending \`until\`.`;
|
|
36
|
+
const UNTIL = "The last day of the stretch, as YYYY-MM-DD in UTC, counted whole. Leave it out for today.";
|
|
37
|
+
export const OPERATIONS = {
|
|
38
|
+
describe_index: {
|
|
39
|
+
scope: "read",
|
|
40
|
+
cli: null,
|
|
41
|
+
mcp: "describe_index",
|
|
42
|
+
description: "What Brood's index holds and never holds, and the state of each mailbox it reads. Call it first: it says whether answers can be trusted to be whole.",
|
|
43
|
+
arguments: { owner: OWNER },
|
|
44
|
+
},
|
|
45
|
+
list_accounts: {
|
|
46
|
+
scope: "read",
|
|
47
|
+
cli: "brood accounts",
|
|
48
|
+
mcp: null,
|
|
49
|
+
description: "The mailboxes connected to Brood, each with its address and whether Brood can still read it.",
|
|
50
|
+
arguments: { owner: OWNER },
|
|
51
|
+
},
|
|
52
|
+
summarise_week: {
|
|
53
|
+
scope: "read",
|
|
54
|
+
cli: "brood week",
|
|
55
|
+
mcp: "summarise_week",
|
|
56
|
+
description: "One finished week, Monday to Sunday in UTC: how it compared with the week before, who wrote most, who wrote for the first time, and the classifications Brood proposed and quieted.",
|
|
57
|
+
arguments: {
|
|
58
|
+
owner: OWNER,
|
|
59
|
+
week: `The week's Monday, as YYYY-MM-DD, finished and within the last ${PORTRAIT_DAYS} days. Leave it out for the most recent finished week.`,
|
|
60
|
+
},
|
|
61
|
+
},
|
|
62
|
+
get_sender: {
|
|
63
|
+
scope: "read",
|
|
64
|
+
cli: "brood senders <address|domain>",
|
|
65
|
+
mcp: "get_sender",
|
|
66
|
+
description: "One sender: how much it writes, by week and by month, its addresses and what files each, whether you have written to it, and the classifications that cover it.",
|
|
67
|
+
arguments: {
|
|
68
|
+
owner: OWNER,
|
|
69
|
+
sender: "The sender's id, as another answer gave it.",
|
|
70
|
+
scope: "`domain`, the default, for everything from the sender's domain, or `address` for the one address.",
|
|
71
|
+
},
|
|
72
|
+
},
|
|
73
|
+
list_classifications: {
|
|
74
|
+
scope: "read",
|
|
75
|
+
cli: "brood classifications [<path>]",
|
|
76
|
+
mcp: "list_classifications",
|
|
77
|
+
description: "Classifications, oldest proposed first: where Brood files mail, what each covers, and what was decided about it.",
|
|
78
|
+
arguments: {
|
|
79
|
+
owner: OWNER,
|
|
80
|
+
state: `Only those in this state, one of ${listed(CLASSIFICATION_STATES)}. Leave it out for all of them.`,
|
|
81
|
+
path: "Only this path and the paths inside it, such as `external` for `external/stripe`.",
|
|
82
|
+
limit: LIMIT,
|
|
83
|
+
cursor: CURSOR,
|
|
84
|
+
},
|
|
85
|
+
},
|
|
86
|
+
get_classification: {
|
|
87
|
+
scope: "read",
|
|
88
|
+
cli: "brood classification <id>",
|
|
89
|
+
mcp: "get_classification",
|
|
90
|
+
description: "One classification: what it covers, the classifications around it, the mailboxes it files in, what it filed by week, and the messages moved out of it.",
|
|
91
|
+
arguments: {
|
|
92
|
+
owner: OWNER,
|
|
93
|
+
id: "The classification's id, as another answer gave it.",
|
|
94
|
+
},
|
|
95
|
+
},
|
|
96
|
+
list_senders: {
|
|
97
|
+
scope: "read",
|
|
98
|
+
cli: "brood senders",
|
|
99
|
+
mcp: "list_senders",
|
|
100
|
+
description: `Who wrote over a stretch of time, by root domain (by address under a mail provider's domain or your own), most messages first, each with when it first and last wrote within it. Inside the last ${RETENTION_DAYS} days the counts are by the day; a stretch reaching further back is counted by the whole month, and the answer says which in \`resolution\`.`,
|
|
101
|
+
arguments: {
|
|
102
|
+
owner: OWNER,
|
|
103
|
+
since: SINCE,
|
|
104
|
+
until: UNTIL,
|
|
105
|
+
limit: LIMIT,
|
|
106
|
+
cursor: CURSOR,
|
|
107
|
+
},
|
|
108
|
+
},
|
|
109
|
+
list_events: {
|
|
110
|
+
scope: "read",
|
|
111
|
+
cli: "brood events",
|
|
112
|
+
mcp: "list_events",
|
|
113
|
+
description: `Messages that arrived or were sent, newest first: when, which way, and the facts about each, never what it said. The index keeps ${RETENTION_DAYS} days of them; \`retained_from\` says how far back this answer could reach.`,
|
|
114
|
+
arguments: {
|
|
115
|
+
owner: OWNER,
|
|
116
|
+
since: SINCE,
|
|
117
|
+
until: UNTIL,
|
|
118
|
+
sender: "Only messages from or to this sender, by the id another answer gave it.",
|
|
119
|
+
scope: "With `sender`: `domain`, the default, for everything from the sender's root domain, or `address` for the one address. Under a mail provider's domain or your own, `domain` is the one address too, since everyone on it is someone else.",
|
|
120
|
+
limit: LIMIT,
|
|
121
|
+
cursor: CURSOR,
|
|
122
|
+
},
|
|
123
|
+
},
|
|
124
|
+
list_quiet_senders: {
|
|
125
|
+
scope: "read",
|
|
126
|
+
cli: "brood quiet",
|
|
127
|
+
mcp: "list_quiet_senders",
|
|
128
|
+
description: `Senders that have gone silent, by root domain (by address under a mail provider's domain or your own), most recently silent first: each wrote in at least ${QUIET_REGULAR_MIN_MONTHS} of the ${QUIET_REGULAR_MONTHS} months up to its last message, and nothing since for the silence window the answer names in \`silence_days\`.`,
|
|
129
|
+
arguments: { owner: OWNER, limit: LIMIT, cursor: CURSOR },
|
|
130
|
+
},
|
|
131
|
+
list_rules: {
|
|
132
|
+
scope: "read",
|
|
133
|
+
cli: "brood rules",
|
|
134
|
+
mcp: "list_rules",
|
|
135
|
+
description: "The filters Brood installed in each mailbox, oldest first: what each files, the senders it leaves out, and whether it is still in place.",
|
|
136
|
+
arguments: {
|
|
137
|
+
owner: OWNER,
|
|
138
|
+
classification: "Only the rules of this classification, by its id.",
|
|
139
|
+
limit: LIMIT,
|
|
140
|
+
cursor: CURSOR,
|
|
141
|
+
},
|
|
142
|
+
},
|
|
143
|
+
get_rule: {
|
|
144
|
+
scope: "read",
|
|
145
|
+
cli: "brood rules <id>",
|
|
146
|
+
mcp: "get_rule",
|
|
147
|
+
description: "One filter Brood installed: what it files, the senders it leaves out, and whether it is still in place.",
|
|
148
|
+
arguments: {
|
|
149
|
+
owner: OWNER,
|
|
150
|
+
id: "The rule's id, as another answer gave it.",
|
|
151
|
+
},
|
|
152
|
+
},
|
|
153
|
+
hush: {
|
|
154
|
+
scope: "act",
|
|
155
|
+
cli: "brood hush",
|
|
156
|
+
mcp: null,
|
|
157
|
+
description: "Files a classification Brood proposed out of your inbox: Brood installs its filter in each mailbox its mail arrived in, and files what is already there. One you declined or undid is proposed again, then filed; one that took over a filter of your own is not Brood's to hush. Brood never files a sender your never-quiet list keeps in view. Hushing one already filed answers its rules.",
|
|
158
|
+
arguments: {
|
|
159
|
+
owner: OWNER,
|
|
160
|
+
classification: "The classification's id, as another answer gave it.",
|
|
161
|
+
},
|
|
162
|
+
},
|
|
163
|
+
unhush: {
|
|
164
|
+
scope: "act",
|
|
165
|
+
cli: "brood unhush",
|
|
166
|
+
mcp: null,
|
|
167
|
+
description: "Undoes a filing: Brood removes its filters, declines it, and brings its mail back to your inbox, the first of it at once and the rest within the hour. One that took over a filter of your own puts your filter back instead, and moves no mail. Unhushing one not filed changes nothing.",
|
|
168
|
+
arguments: {
|
|
169
|
+
owner: OWNER,
|
|
170
|
+
classification: "The classification's id, as another answer gave it.",
|
|
171
|
+
},
|
|
172
|
+
},
|
|
173
|
+
end_session: {
|
|
174
|
+
scope: "read",
|
|
175
|
+
cli: "brood logout",
|
|
176
|
+
mcp: null,
|
|
177
|
+
description: "Ends this client's session: its refresh token stops working, so no new access token can be had from it. An access token already issued lasts until it expires, within a day; to shut a program out at once, revoke it on the account page. The client stays allowed, so signing in again starts a new session. The answer reads no mailbox.",
|
|
178
|
+
arguments: {
|
|
179
|
+
refresh_token: "The client's own refresh token, passed to the sign-in service to end, and never kept.",
|
|
180
|
+
},
|
|
181
|
+
},
|
|
182
|
+
};
|
|
183
|
+
/**
|
|
184
|
+
* Which clients a reader can have yet. The reference names an operation's
|
|
185
|
+
* command or tool only once its client can be installed: the CLI is built
|
|
186
|
+
* and runs from the repository, and becomes true when it is published
|
|
187
|
+
* (#1367); the MCP server is not built (#297). So the reference never points
|
|
188
|
+
* a reader at a client they cannot have.
|
|
189
|
+
*/
|
|
190
|
+
export const CLIENTS_BUILT = { cli: false, mcp: false };
|
|
191
|
+
/** Every operation's name, in the list's order, for a reader that walks them all. */
|
|
192
|
+
// The keys of a literal object whose keys are known: `Object.keys` types them
|
|
193
|
+
// as string, and they are exactly OperationName (conventions/typescript.md).
|
|
194
|
+
export const OPERATION_NAMES = Object.keys(OPERATIONS);
|
|
195
|
+
export const isOperation = (name) => Object.hasOwn(OPERATIONS, name);
|
|
196
|
+
const ok = (value) => ({ ok: true, value });
|
|
197
|
+
const fail = (argument) => ({
|
|
198
|
+
ok: false,
|
|
199
|
+
argument,
|
|
200
|
+
});
|
|
201
|
+
/** An opaque id: what an `owner` may be, and nothing else. */
|
|
202
|
+
const OPAQUE = /^[A-Za-z0-9_-]{1,64}$/;
|
|
203
|
+
const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
204
|
+
/** A cursor is Brood's own encoding; nothing longer or stranger is one. */
|
|
205
|
+
const CURSOR_SHAPE = /^[A-Za-z0-9_-]{1,4096}$/;
|
|
206
|
+
/**
|
|
207
|
+
* A path as the app builds one: `external/` and a root's name, a domain, or
|
|
208
|
+
* a sender's whole address, whose local part may hold almost anything. So
|
|
209
|
+
* any printable text, no control character, up to the longest it can be.
|
|
210
|
+
*/
|
|
211
|
+
const PATH = /^[^\u0000-\u001f\u007f]{1,512}$/u;
|
|
212
|
+
const DAY = /^\d{4}-\d{2}-\d{2}$/;
|
|
213
|
+
/** A token as an OAuth server issues one: printable, with no space, and bounded. */
|
|
214
|
+
const TOKEN = /^[\x21-\x7e]{1,4096}$/;
|
|
215
|
+
const isRecord = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
|
|
216
|
+
/** The body's fields, or the first key it has that the operation does not describe. */
|
|
217
|
+
function fieldsOf(body, operation) {
|
|
218
|
+
if (body === undefined || body === null)
|
|
219
|
+
return ok({});
|
|
220
|
+
if (!isRecord(body))
|
|
221
|
+
return fail("body");
|
|
222
|
+
const known = Object.keys(OPERATIONS[operation].arguments);
|
|
223
|
+
for (const key of Object.keys(body))
|
|
224
|
+
if (!known.includes(key))
|
|
225
|
+
return fail(key);
|
|
226
|
+
return ok(body);
|
|
227
|
+
}
|
|
228
|
+
function ownerOf(f) {
|
|
229
|
+
const owner = f.owner;
|
|
230
|
+
if (owner === undefined)
|
|
231
|
+
return ok({});
|
|
232
|
+
return typeof owner === "string" && OPAQUE.test(owner)
|
|
233
|
+
? ok({ owner })
|
|
234
|
+
: fail("owner");
|
|
235
|
+
}
|
|
236
|
+
function pageOf(f) {
|
|
237
|
+
const { limit, cursor } = f;
|
|
238
|
+
if (limit !== undefined &&
|
|
239
|
+
!(typeof limit === "number" &&
|
|
240
|
+
Number.isInteger(limit) &&
|
|
241
|
+
limit >= 1 &&
|
|
242
|
+
limit <= API_PAGE_MAX))
|
|
243
|
+
return fail("limit");
|
|
244
|
+
if (cursor !== undefined &&
|
|
245
|
+
!(typeof cursor === "string" && CURSOR_SHAPE.test(cursor)))
|
|
246
|
+
return fail("cursor");
|
|
247
|
+
return ok({
|
|
248
|
+
...(limit === undefined ? {} : { limit }),
|
|
249
|
+
...(cursor === undefined ? {} : { cursor }),
|
|
250
|
+
});
|
|
251
|
+
}
|
|
252
|
+
/** A day as YYYY-MM-DD that exists. */
|
|
253
|
+
const isDay = (v) => {
|
|
254
|
+
if (typeof v !== "string" || !DAY.test(v))
|
|
255
|
+
return false;
|
|
256
|
+
const day = new Date(`${v}T00:00:00Z`);
|
|
257
|
+
return !Number.isNaN(day.getTime()) && day.toISOString().slice(0, 10) === v;
|
|
258
|
+
};
|
|
259
|
+
/** `since` and `until` as days that exist, `since` not after `until`. */
|
|
260
|
+
function stretchOf(f) {
|
|
261
|
+
const { since, until } = f;
|
|
262
|
+
if (since !== undefined && !isDay(since))
|
|
263
|
+
return fail("since");
|
|
264
|
+
if (until !== undefined && !isDay(until))
|
|
265
|
+
return fail("until");
|
|
266
|
+
if (isDay(since) && isDay(until) && since > until)
|
|
267
|
+
return fail("since");
|
|
268
|
+
return ok({
|
|
269
|
+
...(isDay(since) ? { since } : {}),
|
|
270
|
+
...(isDay(until) ? { until } : {}),
|
|
271
|
+
});
|
|
272
|
+
}
|
|
273
|
+
const isUuid = (v) => typeof v === "string" && UUID.test(v);
|
|
274
|
+
/** Only the owner: the operations that take nothing else. */
|
|
275
|
+
const ownerOnly = (operation) => (body) => {
|
|
276
|
+
const f = fieldsOf(body, operation);
|
|
277
|
+
return f.ok ? ownerOf(f.value) : f;
|
|
278
|
+
};
|
|
279
|
+
/** An owner and a classification's id: what acting on one takes. */
|
|
280
|
+
const classificationOnly = (operation) => (body) => {
|
|
281
|
+
const f = fieldsOf(body, operation);
|
|
282
|
+
if (!f.ok)
|
|
283
|
+
return f;
|
|
284
|
+
const owner = ownerOf(f.value);
|
|
285
|
+
if (!owner.ok)
|
|
286
|
+
return owner;
|
|
287
|
+
const classification = f.value.classification;
|
|
288
|
+
return isUuid(classification)
|
|
289
|
+
? ok({ ...owner.value, classification })
|
|
290
|
+
: fail("classification");
|
|
291
|
+
};
|
|
292
|
+
/** Each operation's arguments, narrowed. */
|
|
293
|
+
export const ARGUMENTS = {
|
|
294
|
+
describe_index: ownerOnly("describe_index"),
|
|
295
|
+
list_accounts: ownerOnly("list_accounts"),
|
|
296
|
+
summarise_week(body) {
|
|
297
|
+
const f = fieldsOf(body, "summarise_week");
|
|
298
|
+
if (!f.ok)
|
|
299
|
+
return f;
|
|
300
|
+
const owner = ownerOf(f.value);
|
|
301
|
+
if (!owner.ok)
|
|
302
|
+
return owner;
|
|
303
|
+
const week = f.value.week;
|
|
304
|
+
if (week === undefined)
|
|
305
|
+
return ok(owner.value);
|
|
306
|
+
return typeof week === "string" && DAY.test(week)
|
|
307
|
+
? ok({ ...owner.value, week })
|
|
308
|
+
: fail("week");
|
|
309
|
+
},
|
|
310
|
+
get_sender(body) {
|
|
311
|
+
const f = fieldsOf(body, "get_sender");
|
|
312
|
+
if (!f.ok)
|
|
313
|
+
return f;
|
|
314
|
+
const owner = ownerOf(f.value);
|
|
315
|
+
if (!owner.ok)
|
|
316
|
+
return owner;
|
|
317
|
+
const { sender, scope = "domain" } = f.value;
|
|
318
|
+
if (!isUuid(sender))
|
|
319
|
+
return fail("sender");
|
|
320
|
+
if (scope !== "domain" && scope !== "address")
|
|
321
|
+
return fail("scope");
|
|
322
|
+
return ok({ ...owner.value, sender, scope });
|
|
323
|
+
},
|
|
324
|
+
list_classifications(body) {
|
|
325
|
+
const f = fieldsOf(body, "list_classifications");
|
|
326
|
+
if (!f.ok)
|
|
327
|
+
return f;
|
|
328
|
+
const owner = ownerOf(f.value);
|
|
329
|
+
if (!owner.ok)
|
|
330
|
+
return owner;
|
|
331
|
+
const page = pageOf(f.value);
|
|
332
|
+
if (!page.ok)
|
|
333
|
+
return page;
|
|
334
|
+
const { state, path } = f.value;
|
|
335
|
+
const known = CLASSIFICATION_STATES.find((s) => s === state);
|
|
336
|
+
if (state !== undefined && known === undefined)
|
|
337
|
+
return fail("state");
|
|
338
|
+
if (path !== undefined && !(typeof path === "string" && PATH.test(path)))
|
|
339
|
+
return fail("path");
|
|
340
|
+
return ok({
|
|
341
|
+
...owner.value,
|
|
342
|
+
...page.value,
|
|
343
|
+
...(known === undefined ? {} : { state: known }),
|
|
344
|
+
...(typeof path === "string" ? { path } : {}),
|
|
345
|
+
});
|
|
346
|
+
},
|
|
347
|
+
get_classification(body) {
|
|
348
|
+
const f = fieldsOf(body, "get_classification");
|
|
349
|
+
if (!f.ok)
|
|
350
|
+
return f;
|
|
351
|
+
const owner = ownerOf(f.value);
|
|
352
|
+
if (!owner.ok)
|
|
353
|
+
return owner;
|
|
354
|
+
const id = f.value.id;
|
|
355
|
+
return isUuid(id) ? ok({ ...owner.value, id }) : fail("id");
|
|
356
|
+
},
|
|
357
|
+
list_senders(body) {
|
|
358
|
+
const f = fieldsOf(body, "list_senders");
|
|
359
|
+
if (!f.ok)
|
|
360
|
+
return f;
|
|
361
|
+
const owner = ownerOf(f.value);
|
|
362
|
+
if (!owner.ok)
|
|
363
|
+
return owner;
|
|
364
|
+
const page = pageOf(f.value);
|
|
365
|
+
if (!page.ok)
|
|
366
|
+
return page;
|
|
367
|
+
const stretch = stretchOf(f.value);
|
|
368
|
+
return stretch.ok
|
|
369
|
+
? ok({ ...owner.value, ...page.value, ...stretch.value })
|
|
370
|
+
: stretch;
|
|
371
|
+
},
|
|
372
|
+
list_events(body) {
|
|
373
|
+
const f = fieldsOf(body, "list_events");
|
|
374
|
+
if (!f.ok)
|
|
375
|
+
return f;
|
|
376
|
+
const owner = ownerOf(f.value);
|
|
377
|
+
if (!owner.ok)
|
|
378
|
+
return owner;
|
|
379
|
+
const page = pageOf(f.value);
|
|
380
|
+
if (!page.ok)
|
|
381
|
+
return page;
|
|
382
|
+
const stretch = stretchOf(f.value);
|
|
383
|
+
if (!stretch.ok)
|
|
384
|
+
return stretch;
|
|
385
|
+
const { sender, scope } = f.value;
|
|
386
|
+
if (sender !== undefined && !isUuid(sender))
|
|
387
|
+
return fail("sender");
|
|
388
|
+
if (scope !== undefined && scope !== "domain" && scope !== "address")
|
|
389
|
+
return fail("scope");
|
|
390
|
+
if (scope !== undefined && sender === undefined)
|
|
391
|
+
return fail("scope");
|
|
392
|
+
return ok({
|
|
393
|
+
...owner.value,
|
|
394
|
+
...page.value,
|
|
395
|
+
...stretch.value,
|
|
396
|
+
...(sender === undefined ? {} : { sender }),
|
|
397
|
+
...(scope === undefined ? {} : { scope }),
|
|
398
|
+
});
|
|
399
|
+
},
|
|
400
|
+
list_quiet_senders(body) {
|
|
401
|
+
const f = fieldsOf(body, "list_quiet_senders");
|
|
402
|
+
if (!f.ok)
|
|
403
|
+
return f;
|
|
404
|
+
const owner = ownerOf(f.value);
|
|
405
|
+
if (!owner.ok)
|
|
406
|
+
return owner;
|
|
407
|
+
const page = pageOf(f.value);
|
|
408
|
+
return page.ok ? ok({ ...owner.value, ...page.value }) : page;
|
|
409
|
+
},
|
|
410
|
+
list_rules(body) {
|
|
411
|
+
const f = fieldsOf(body, "list_rules");
|
|
412
|
+
if (!f.ok)
|
|
413
|
+
return f;
|
|
414
|
+
const owner = ownerOf(f.value);
|
|
415
|
+
if (!owner.ok)
|
|
416
|
+
return owner;
|
|
417
|
+
const page = pageOf(f.value);
|
|
418
|
+
if (!page.ok)
|
|
419
|
+
return page;
|
|
420
|
+
const classification = f.value.classification;
|
|
421
|
+
if (classification !== undefined && !isUuid(classification))
|
|
422
|
+
return fail("classification");
|
|
423
|
+
return ok({
|
|
424
|
+
...owner.value,
|
|
425
|
+
...page.value,
|
|
426
|
+
...(classification === undefined ? {} : { classification }),
|
|
427
|
+
});
|
|
428
|
+
},
|
|
429
|
+
get_rule(body) {
|
|
430
|
+
const f = fieldsOf(body, "get_rule");
|
|
431
|
+
if (!f.ok)
|
|
432
|
+
return f;
|
|
433
|
+
const owner = ownerOf(f.value);
|
|
434
|
+
if (!owner.ok)
|
|
435
|
+
return owner;
|
|
436
|
+
const id = f.value.id;
|
|
437
|
+
return isUuid(id) ? ok({ ...owner.value, id }) : fail("id");
|
|
438
|
+
},
|
|
439
|
+
hush: classificationOnly("hush"),
|
|
440
|
+
unhush: classificationOnly("unhush"),
|
|
441
|
+
end_session(body) {
|
|
442
|
+
const f = fieldsOf(body, "end_session");
|
|
443
|
+
if (!f.ok)
|
|
444
|
+
return f;
|
|
445
|
+
const token = f.value.refresh_token;
|
|
446
|
+
return typeof token === "string" && TOKEN.test(token)
|
|
447
|
+
? ok({ refresh_token: token })
|
|
448
|
+
: fail("refresh_token");
|
|
449
|
+
},
|
|
450
|
+
};
|
|
451
|
+
/** The codes a problem carries, which clients branch on (DD21 §8, RFC 9457). */
|
|
452
|
+
export const PROBLEM_CODES = [
|
|
453
|
+
"invalid_argument",
|
|
454
|
+
"unauthenticated",
|
|
455
|
+
"credential_revoked",
|
|
456
|
+
"insufficient_scope",
|
|
457
|
+
"plan_required",
|
|
458
|
+
"not_found",
|
|
459
|
+
"mailbox_unreachable",
|
|
460
|
+
"never_quiet",
|
|
461
|
+
"in_progress",
|
|
462
|
+
"rate_limited",
|
|
463
|
+
"internal",
|
|
464
|
+
];
|
|
465
|
+
/**
|
|
466
|
+
* Each problem's status, its title, and when it is answered (DD21 §8): what
|
|
467
|
+
* the app answers with and what the reference says, from one table.
|
|
468
|
+
*/
|
|
469
|
+
export const PROBLEMS = {
|
|
470
|
+
invalid_argument: {
|
|
471
|
+
status: 400,
|
|
472
|
+
title: "An argument is not valid",
|
|
473
|
+
when: "An argument, the body, or a cursor is not one the operation takes. `detail` names which, never its value.",
|
|
474
|
+
},
|
|
475
|
+
unauthenticated: {
|
|
476
|
+
status: 401,
|
|
477
|
+
title: "Not signed in",
|
|
478
|
+
when: "No token, one that fails verification, or one whose person has deleted their account. `WWW-Authenticate` says how to sign in.",
|
|
479
|
+
},
|
|
480
|
+
credential_revoked: {
|
|
481
|
+
status: 401,
|
|
482
|
+
title: "This credential was revoked",
|
|
483
|
+
when: `Unused for ${API_UNUSED_DAYS} days, or revoked. Signing in again does not undo it.`,
|
|
484
|
+
},
|
|
485
|
+
insufficient_scope: {
|
|
486
|
+
status: 403,
|
|
487
|
+
title: "This credential may not do that",
|
|
488
|
+
when: "The token lacks the operation's scope. `WWW-Authenticate` names the scope it needs.",
|
|
489
|
+
},
|
|
490
|
+
plan_required: {
|
|
491
|
+
status: 403,
|
|
492
|
+
title: "This needs Pro",
|
|
493
|
+
when: "Hushing on an account without Pro. Unhushing never needs it.",
|
|
494
|
+
acting: true,
|
|
495
|
+
},
|
|
496
|
+
not_found: {
|
|
497
|
+
status: 404,
|
|
498
|
+
title: "Not found",
|
|
499
|
+
when: "The operation, or the sender, classification or rule, is not this person's. Another person's is answered the same way, so the two cannot be told apart.",
|
|
500
|
+
},
|
|
501
|
+
mailbox_unreachable: {
|
|
502
|
+
status: 409,
|
|
503
|
+
title: "Brood cannot reach this mailbox",
|
|
504
|
+
when: "Hushing found no mailbox to install in: none connected that the classification's mail arrived in, or every one refused.",
|
|
505
|
+
acting: true,
|
|
506
|
+
},
|
|
507
|
+
never_quiet: {
|
|
508
|
+
status: 409,
|
|
509
|
+
title: "Your never-quiet list keeps this in view",
|
|
510
|
+
when: "Hushing a classification that your never-quiet list keeps in view. Brood never files mail the list keeps, whatever asks it to.",
|
|
511
|
+
},
|
|
512
|
+
in_progress: {
|
|
513
|
+
status: 409,
|
|
514
|
+
title: "Brood is still undoing this",
|
|
515
|
+
when: "Hushing a classification whose earlier filter Brood is still removing, or whose mail it is still bringing back. Try again within the hour.",
|
|
516
|
+
},
|
|
517
|
+
rate_limited: {
|
|
518
|
+
status: 429,
|
|
519
|
+
title: "Too many calls",
|
|
520
|
+
when: `More than ${API_CALLS_PER_MINUTE} calls in a minute from one credential, or ${API_ACTS_PER_MINUTE} that act on a mailbox; or, for \`unhush\`, the day's allowance of rule changes spent, which comes back at midnight UTC, as the app's undo shares it. \`Retry-After\` says when to call again.`,
|
|
521
|
+
},
|
|
522
|
+
internal: {
|
|
523
|
+
status: 500,
|
|
524
|
+
title: "Something went wrong",
|
|
525
|
+
when: "Anything else. Nothing from inside Brood reaches `detail`.",
|
|
526
|
+
},
|
|
527
|
+
};
|
|
528
|
+
export { ANSWER_FIELDS, ENVELOPE_FIELDS } from "./fields.js";
|
|
@@ -0,0 +1,59 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The values the API's answers and arguments take, as lists, so the types
|
|
3
|
+
* derive from them and the reference names them from them (#1344): one
|
|
4
|
+
* home for each, with no value typed twice.
|
|
5
|
+
*/
|
|
6
|
+
/** A classification's states, as the engine's list holds them, which a test keeps equal. */
|
|
7
|
+
export const CLASSIFICATION_STATES = [
|
|
8
|
+
"proposed",
|
|
9
|
+
"active",
|
|
10
|
+
"quieted",
|
|
11
|
+
"declined",
|
|
12
|
+
];
|
|
13
|
+
/** Why the engine proposed or moved a classification, as the engine's list holds them. */
|
|
14
|
+
export const CLASSIFICATION_REASONS = [
|
|
15
|
+
"volume",
|
|
16
|
+
"subdomain_split",
|
|
17
|
+
"customer",
|
|
18
|
+
"silence",
|
|
19
|
+
"correction_streak",
|
|
20
|
+
"reproposed",
|
|
21
|
+
"filter_missing",
|
|
22
|
+
"restored",
|
|
23
|
+
"kept_out",
|
|
24
|
+
"adopted",
|
|
25
|
+
];
|
|
26
|
+
/** How a week sounded beside the one before; `first` with none to compare. */
|
|
27
|
+
export const TONES = ["quieter", "louder", "much the same", "first"];
|
|
28
|
+
/** How a week sounded, as a reader is told it, with no number in it: the app's week page and `brood week` both say it. */
|
|
29
|
+
export const TONE_TITLES = {
|
|
30
|
+
quieter: "A quieter week.",
|
|
31
|
+
louder: "A louder week.",
|
|
32
|
+
"much the same": "A week much like the one before.",
|
|
33
|
+
first: "The first week Brood can tell you about.",
|
|
34
|
+
};
|
|
35
|
+
/** What a sender is, as the app tags it. */
|
|
36
|
+
export const SENDER_TAGS = [
|
|
37
|
+
"customer",
|
|
38
|
+
"filed",
|
|
39
|
+
"quieted",
|
|
40
|
+
"correspondence",
|
|
41
|
+
"mailing",
|
|
42
|
+
];
|
|
43
|
+
/** How much of a sender is meant: everything under its root domain, or the one address. */
|
|
44
|
+
export const SENDER_SCOPES = ["domain", "address"];
|
|
45
|
+
/** What a classification covers: a domain and everything under it, or one address. */
|
|
46
|
+
export const SUBJECT_KINDS = ["domain", "sender"];
|
|
47
|
+
/** How a classification is shown in a mailbox. */
|
|
48
|
+
export const SHOWN = ["active", "quieted", "left"];
|
|
49
|
+
/** Which way a message went. */
|
|
50
|
+
export const DIRECTIONS = ["inbound", "outbound"];
|
|
51
|
+
/** How the person was addressed on a message. */
|
|
52
|
+
export const ADDRESSED = ["to", "cc", "neither"];
|
|
53
|
+
/** A list of values as the reference writes them: each as code, `or` before the last. */
|
|
54
|
+
export const listed = (values) => values.length < 2
|
|
55
|
+
? values.map((v) => `\`${v}\``).join("")
|
|
56
|
+
: `${values
|
|
57
|
+
.slice(0, -1)
|
|
58
|
+
.map((v) => `\`${v}\``)
|
|
59
|
+
.join(", ")} or \`${values.at(-1)}\``;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
// The figures the CLI uses, as Brood's figures hold them.
|
|
2
|
+
export const API_ACTS_PER_MINUTE = 10;
|
|
3
|
+
export const API_CALLS_PER_MINUTE = 120;
|
|
4
|
+
export const API_PAGE_MAX = 200;
|
|
5
|
+
export const API_STRETCH_DAYS = 30;
|
|
6
|
+
export const API_UNUSED_DAYS = 90;
|
|
7
|
+
export const PORTRAIT_DAYS = 90;
|
|
8
|
+
export const QUIET_REGULAR_MIN_MONTHS = 2;
|
|
9
|
+
export const QUIET_REGULAR_MONTHS = 3;
|
|
10
|
+
export const RETENTION_DAYS = 120;
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Noisy Brood — the dark scheme (#575)
|
|
3
|
+
*
|
|
4
|
+
* The brand bible: "Dark mode inverts the system: deep Ink as ground, Linen
|
|
5
|
+
* as text. Barn remains the accent." So this redefines the
|
|
6
|
+
* colour tokens of theme.css, by the same names, when the person's system or
|
|
7
|
+
* browser asks for a dark scheme. There is no switch: following the system
|
|
8
|
+
* asks nothing of the person (interface-prohibitions, principle 2).
|
|
9
|
+
*
|
|
10
|
+
* The names keep their roles, not their colours: under this block `linen` is
|
|
11
|
+
* the ground and dark, `ink` the text and light. That is the inversion the
|
|
12
|
+
* bible describes, and it is why a dark button with light text becomes a light
|
|
13
|
+
* one with dark text without either being written twice. Tailwind's documented
|
|
14
|
+
* way is a `dark:` variant on every element; that would be a second copy of
|
|
15
|
+
* every colour decision in the app, which tokens-and-styling.md records as the
|
|
16
|
+
* departure and its reason.
|
|
17
|
+
*
|
|
18
|
+
* Which surfaces import it is listed in conventions/tokens-and-styling.md;
|
|
19
|
+
* the rest stay light until each is argued.
|
|
20
|
+
*
|
|
21
|
+
* Linen and Ink swap, so each is stated here rather than read from the other:
|
|
22
|
+
* a variable cannot name its own partner without a cycle. A test holds the two
|
|
23
|
+
* equal to theme.css (apps/web/src/app/colour.test.ts).
|
|
24
|
+
*
|
|
25
|
+
* The base roles were chosen in #648, and the brandkit's Dark page measures each.
|
|
26
|
+
* The data colours were chosen for this scheme and checked against Ink and the
|
|
27
|
+
* second ground for colour-blind readers, as theme.css's were against Linen
|
|
28
|
+
* (#655): Pond, Hedge and Chicory apart under every simulated vision, each at
|
|
29
|
+
* least 3:1 on Ink; Sky's steps one hue, brightest for the most.
|
|
30
|
+
*/
|
|
31
|
+
|
|
32
|
+
:root {
|
|
33
|
+
color-scheme: light dark;
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
@media (prefers-color-scheme: dark) {
|
|
37
|
+
:root {
|
|
38
|
+
/* Ground: Ink, and a step up from it at the distance Wheat sits below Linen. */
|
|
39
|
+
--color-linen: #1c2434;
|
|
40
|
+
--color-wheat: #2a3548;
|
|
41
|
+
|
|
42
|
+
/* Text: Linen. */
|
|
43
|
+
--color-ink: #f5efe4;
|
|
44
|
+
--color-ink-muted: rgb(245 239 228 / 0.6);
|
|
45
|
+
--color-ink-line: rgb(245 239 228 / 0.12);
|
|
46
|
+
|
|
47
|
+
/* Field, lifted until it reads as secondary text on Ink. */
|
|
48
|
+
--color-field: #a7b1be;
|
|
49
|
+
--color-field-muted: rgb(167 177 190 / 0.85);
|
|
50
|
+
--color-field-line: rgb(167 177 190 / 0.22);
|
|
51
|
+
--color-field-soft: rgb(167 177 190 / 0.15);
|
|
52
|
+
|
|
53
|
+
/* The plate: the second ground, so it reads as lifted, not inverted. */
|
|
54
|
+
--color-plate: #2a3548;
|
|
55
|
+
--color-plate-text: #f5efe4;
|
|
56
|
+
|
|
57
|
+
/* Barn, still reserved, lifted to read on Ink as text and as a mark. */
|
|
58
|
+
--color-barn: #d4786b;
|
|
59
|
+
|
|
60
|
+
/* Functional. Embers is pushed toward orange so it does not meet Barn. */
|
|
61
|
+
--color-moss: #9cad74;
|
|
62
|
+
--color-moss-soft: rgb(156 173 116 / 0.16);
|
|
63
|
+
--color-hay: #d4b47e;
|
|
64
|
+
--color-hay-soft: rgb(212 180 126 / 0.16);
|
|
65
|
+
--color-embers: #e38a5b;
|
|
66
|
+
--color-embers-soft: rgb(227 138 91 / 0.16);
|
|
67
|
+
|
|
68
|
+
/* Data. */
|
|
69
|
+
--color-pond: #3a71ac;
|
|
70
|
+
--color-hedge: #258e6a;
|
|
71
|
+
--color-chicory: #997fde;
|
|
72
|
+
--color-sky: #5b97cb;
|
|
73
|
+
--color-sky-soft: rgb(91 151 203 / 0.18);
|
|
74
|
+
--color-sky-1: #2c5f8e;
|
|
75
|
+
--color-sky-2: #3f7bb0;
|
|
76
|
+
--color-sky-3: #5b97cb;
|
|
77
|
+
--color-sky-4: #7fb3e0;
|
|
78
|
+
|
|
79
|
+
/* Homes: the colours in the mailbox, unchanged (theme.css says why). */
|
|
80
|
+
--color-home-blue: #285bac;
|
|
81
|
+
--color-home-green: #0b804b;
|
|
82
|
+
--color-home-lavender: #b694e8;
|
|
83
|
+
--color-home-gold: #d5ae49;
|
|
84
|
+
--color-home-tint: #c9daf8;
|
|
85
|
+
}
|
|
86
|
+
}
|