@verevoir/aigency-work 0.2.1 → 0.4.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 +137 -0
- package/README.md +59 -0
- package/dist/asf-board.js +118 -40
- package/dist/backlog-board.d.ts +21 -0
- package/dist/backlog-board.js +383 -0
- package/dist/board.d.ts +21 -2
- package/dist/board.js +30 -1
- package/dist/card.d.ts +61 -17
- package/dist/card.js +38 -8
- package/dist/in-memory-board.d.ts +13 -1
- package/dist/in-memory-board.js +23 -3
- package/dist/index.d.ts +9 -3
- package/dist/index.js +4 -1
- package/dist/notion-board.d.ts +82 -0
- package/dist/notion-board.js +667 -26
- package/dist/payload-board.js +6 -1
- package/dist/status.d.ts +24 -0
- package/dist/status.js +36 -0
- package/dist/store-board.js +6 -1
- package/dist/trello-board.d.ts +41 -0
- package/dist/trello-board.js +337 -0
- package/package.json +1 -1
package/dist/notion-board.js
CHANGED
|
@@ -11,6 +11,74 @@
|
|
|
11
11
|
// that supplies one gets `unsupported`, naming it, rather than a guard
|
|
12
12
|
// that looks real and isn't (the same discipline `payload-board.ts`
|
|
13
13
|
// applies for the same reason).
|
|
14
|
+
//
|
|
15
|
+
// Nothing is silently partial. A card's body AND each of its property values
|
|
16
|
+
// is exactly one of: complete; explicitly marked incomplete (skipped or
|
|
17
|
+
// truncated body blocks, and `unknownFields.propertiesIncomplete` for a
|
|
18
|
+
// property Notion truncated that cannot be paged, such as a rollup); or the
|
|
19
|
+
// property is a configured title/requires/parent one that is missing or of
|
|
20
|
+
// the wrong type (a problem, never an absent field); or the
|
|
21
|
+
// read fails (a fetch failure is `unreachable`; a malformed page response is
|
|
22
|
+
// `unparseable` -- see `completeProperty` and, for the body, `fetchChildren`),
|
|
23
|
+
// with a reason. Notion truncates inline relation/people/title/rich_text
|
|
24
|
+
// values at 25 items and flags it with `has_more`; only a property that
|
|
25
|
+
// reports `has_more: true` triggers extra calls (lazy), paged in full via
|
|
26
|
+
// GET /v1/pages/{page_id}/properties/{property_id}.
|
|
27
|
+
//
|
|
28
|
+
// Only EXPLICITLY named title/requires/parent properties are strict: a
|
|
29
|
+
// `titleProperty`, `requiresProperty` or `parentProperty` the caller set that
|
|
30
|
+
// is missing or of the wrong type makes the card `unparseable`. The defaults
|
|
31
|
+
// ("Name", "Depends on") are not checked, so a database without them still
|
|
32
|
+
// reads, with the field absent.
|
|
33
|
+
import { normalizeStatus } from './status.js';
|
|
34
|
+
/**
|
|
35
|
+
* A ready-made `StatusMap` for the conventional Notion status names. It is
|
|
36
|
+
* OPT-IN: a board derives `Card.status` only when this (or another map) is
|
|
37
|
+
* passed as `NotionBoardConfig.statusMap`.
|
|
38
|
+
*/
|
|
39
|
+
export const NOTION_DEFAULT_STATUS_MAP = {
|
|
40
|
+
toStatus: {
|
|
41
|
+
Backlog: 'backlog',
|
|
42
|
+
Ready: 'ready',
|
|
43
|
+
'In progress': 'in-progress',
|
|
44
|
+
'In review': 'in-review',
|
|
45
|
+
Blocked: 'blocked',
|
|
46
|
+
Done: 'done',
|
|
47
|
+
},
|
|
48
|
+
fromStatus: {
|
|
49
|
+
backlog: 'Backlog',
|
|
50
|
+
ready: 'Ready',
|
|
51
|
+
'in-progress': 'In progress',
|
|
52
|
+
'in-review': 'In review',
|
|
53
|
+
blocked: 'Blocked',
|
|
54
|
+
done: 'Done',
|
|
55
|
+
},
|
|
56
|
+
};
|
|
57
|
+
/**
|
|
58
|
+
* Nested blocks are followed this many levels below the page when rendering a
|
|
59
|
+
* body. A block at this depth that still has children is rendered but its
|
|
60
|
+
* children are NOT fetched; the truncation is reported, never silent: a
|
|
61
|
+
* `<!-- children omitted: depth limit -->` line in the body text, and
|
|
62
|
+
* `unknownFields.body.truncatedAtDepth` / `truncatedBlocks` on the card.
|
|
63
|
+
*/
|
|
64
|
+
const MAX_BODY_DEPTH = 3;
|
|
65
|
+
/**
|
|
66
|
+
* Appended to every not-found answer the READ paths give (`get`, `list`,
|
|
67
|
+
* `readPage`) on a 404 / object_not_found. The write paths (`writeState`,
|
|
68
|
+
* `annotate`, `createCard`) report their own named `refused` reason and do
|
|
69
|
+
* not carry it.
|
|
70
|
+
* Notion answers the same for "does not exist" and "exists but your
|
|
71
|
+
* integration cannot see it", and the second is by far the commoner.
|
|
72
|
+
*/
|
|
73
|
+
const CONNECTION_HINT = 'Most likely the integration behind the token is not connected to that page or database ' +
|
|
74
|
+
'(in Notion: open it, then ••• → Connections, and add the integration).';
|
|
75
|
+
/**
|
|
76
|
+
* Added only where a DATABASE id was asked for (`list`): a data-source
|
|
77
|
+
* (collection) id is not a database id under 2022-06-28. A page id has no
|
|
78
|
+
* such confusion, so page paths (`get`, `readPage`) leave this out.
|
|
79
|
+
*/
|
|
80
|
+
const DATABASE_ID_HINT = 'Also check the id: a data-source (collection) id is not a database id under Notion API ' +
|
|
81
|
+
'2022-06-28, so a collection id is reported as not found.';
|
|
14
82
|
/** The API version this board was built and tested against. */
|
|
15
83
|
export const NOTION_VERSION = '2022-06-28';
|
|
16
84
|
const DEFAULT_MAX_ATTEMPTS = 4;
|
|
@@ -39,10 +107,21 @@ const defaultSleep = (ms) => new Promise((resolve) => {
|
|
|
39
107
|
});
|
|
40
108
|
function resolveConfig(config) {
|
|
41
109
|
return {
|
|
110
|
+
...resolveTransport(config),
|
|
42
111
|
databaseId: config.databaseId,
|
|
43
|
-
getToken: config.getToken,
|
|
44
112
|
statusProperty: config.statusProperty ?? 'Status',
|
|
45
113
|
titleProperty: config.titleProperty ?? 'Name',
|
|
114
|
+
titleConfigured: config.titleProperty !== undefined,
|
|
115
|
+
requiresProperty: config.requiresProperty ?? 'Depends on',
|
|
116
|
+
requiresConfigured: config.requiresProperty !== undefined,
|
|
117
|
+
parentProperty: config.parentProperty,
|
|
118
|
+
statusMap: config.statusMap,
|
|
119
|
+
};
|
|
120
|
+
}
|
|
121
|
+
/** Transport defaults shared by the board and the page reader. */
|
|
122
|
+
function resolveTransport(config) {
|
|
123
|
+
return {
|
|
124
|
+
getToken: config.getToken,
|
|
46
125
|
fetch: config.fetch ?? defaultFetch,
|
|
47
126
|
sleep: config.sleep ?? defaultSleep,
|
|
48
127
|
// Clamped to at least 1: a configured 0 (or negative) used to fall
|
|
@@ -200,15 +279,22 @@ async function request(resolved, method, path, body) {
|
|
|
200
279
|
* rate-limiting applies to a plain GET as much as to a write, so this IS
|
|
201
280
|
* reachable from here — and `unreachable`) falls back to `unreachable`.
|
|
202
281
|
*/
|
|
203
|
-
function toGetFailure(outcome) {
|
|
282
|
+
function toGetFailure(id, outcome) {
|
|
204
283
|
if (outcome.kind === 'notFound') {
|
|
205
|
-
return {
|
|
284
|
+
return {
|
|
285
|
+
outcome: 'absent',
|
|
286
|
+
reason: `Notion returned not found for page ${id}. ${CONNECTION_HINT}`,
|
|
287
|
+
};
|
|
206
288
|
}
|
|
207
289
|
return { outcome: 'unreachable', reason: outcome.reason };
|
|
208
290
|
}
|
|
209
291
|
function toListFailure(outcome) {
|
|
210
292
|
if (outcome.kind === 'notFound') {
|
|
211
|
-
return {
|
|
293
|
+
return {
|
|
294
|
+
outcome: 'unreachable',
|
|
295
|
+
reason: `Notion reported no such database. ${CONNECTION_HINT} ${DATABASE_ID_HINT}`,
|
|
296
|
+
notFound: true,
|
|
297
|
+
};
|
|
212
298
|
}
|
|
213
299
|
return { outcome: 'unreachable', reason: outcome.reason };
|
|
214
300
|
}
|
|
@@ -308,7 +394,16 @@ async function resolveRelation(propertyName, refs, resolved) {
|
|
|
308
394
|
reason: `"${propertyName}" references page ${ref.id}, whose "Ticket" property has type "${ticket.type}", not rich_text`,
|
|
309
395
|
};
|
|
310
396
|
}
|
|
311
|
-
|
|
397
|
+
// The Ticket is itself an inline property read: page it if truncated.
|
|
398
|
+
const fullTicket = await completeProperty(ref.id, 'Ticket', ticket, resolved);
|
|
399
|
+
if (!fullTicket.ok) {
|
|
400
|
+
return {
|
|
401
|
+
ok: false,
|
|
402
|
+
kind: fullTicket.kind === 'unreachable' ? 'unreachable' : 'problem',
|
|
403
|
+
reason: `"${propertyName}" references page ${ref.id}: ${fullTicket.reason}`,
|
|
404
|
+
};
|
|
405
|
+
}
|
|
406
|
+
const text = plainTextOf(fullTicket.prop.rich_text);
|
|
312
407
|
if (text === '') {
|
|
313
408
|
return {
|
|
314
409
|
ok: false,
|
|
@@ -379,6 +474,13 @@ async function flattenProperty(name, prop, resolved, properties, unknownFields)
|
|
|
379
474
|
}
|
|
380
475
|
return { ok: true };
|
|
381
476
|
}
|
|
477
|
+
case 'unique_id': {
|
|
478
|
+
const uid = prop.unique_id;
|
|
479
|
+
if (uid && uid.number !== null && uid.number !== undefined) {
|
|
480
|
+
properties[name] = uid.prefix ? `${uid.prefix}-${uid.number}` : String(uid.number);
|
|
481
|
+
}
|
|
482
|
+
return { ok: true };
|
|
483
|
+
}
|
|
382
484
|
case 'relation': {
|
|
383
485
|
const refs = prop.relation ?? [];
|
|
384
486
|
if (refs.length === 0) {
|
|
@@ -414,7 +516,10 @@ function extractState(page, resolved) {
|
|
|
414
516
|
if (prop === undefined) {
|
|
415
517
|
return {
|
|
416
518
|
ok: false,
|
|
417
|
-
reason: `property "${resolved.statusProperty}" does not exist on this page, so its state cannot be read
|
|
519
|
+
reason: `property "${resolved.statusProperty}" does not exist on this page, so its state cannot be read. ` +
|
|
520
|
+
`The page has no "${resolved.statusProperty}" property: either it is not a row of the configured database, or the status property was renamed or removed. ` +
|
|
521
|
+
'To read an ordinary Notion page (a design page, a row of another database such as ADRs), ' +
|
|
522
|
+
'use createNotionPageReader(...).readPage(pageId) instead of get().',
|
|
418
523
|
};
|
|
419
524
|
}
|
|
420
525
|
if (prop.type === 'select') {
|
|
@@ -428,7 +533,146 @@ function extractState(page, resolved) {
|
|
|
428
533
|
reason: `property "${resolved.statusProperty}" has type "${prop.type}", not select or status, so its state cannot be read`,
|
|
429
534
|
};
|
|
430
535
|
}
|
|
431
|
-
|
|
536
|
+
/** Inline value types Notion truncates at 25 items and lets us page in full. */
|
|
537
|
+
const PAGEABLE_PROPERTY_TYPES = new Set([
|
|
538
|
+
'relation',
|
|
539
|
+
'title',
|
|
540
|
+
'rich_text',
|
|
541
|
+
'people',
|
|
542
|
+
]);
|
|
543
|
+
/**
|
|
544
|
+
* The path of one page property item, with the property id encoded exactly
|
|
545
|
+
* once. Notion hands property ids out already URL-encoded (e.g. `%3DfL%3F`),
|
|
546
|
+
* so encoding them again would send `%253DfL%253F` and 404. The id is decoded
|
|
547
|
+
* first (a malformed escape is taken literally, never thrown) and then
|
|
548
|
+
* encoded, so an encoded id and its raw form give the same path.
|
|
549
|
+
*/
|
|
550
|
+
export function notionPropertyPath(pageId, propertyId) {
|
|
551
|
+
let decoded;
|
|
552
|
+
try {
|
|
553
|
+
decoded = decodeURIComponent(propertyId);
|
|
554
|
+
}
|
|
555
|
+
catch {
|
|
556
|
+
decoded = propertyId;
|
|
557
|
+
}
|
|
558
|
+
return `/pages/${encodeURIComponent(pageId)}/properties/${encodeURIComponent(decoded)}`;
|
|
559
|
+
}
|
|
560
|
+
/**
|
|
561
|
+
* Returns the property with its full value. LAZY: a property without
|
|
562
|
+
* `has_more: true` is returned as-is with no call. A truncated pageable one
|
|
563
|
+
* is fetched in full from /pages/{page}/properties/{property id}, following
|
|
564
|
+
* `next_cursor` with a repeated-cursor guard; any failure is `ok: false`,
|
|
565
|
+
* never a shorter value, and its `kind` says why: `unreachable` for a fetch
|
|
566
|
+
* failure, `unparseable` for a malformed or unpageable response. A truncated
|
|
567
|
+
* property that cannot be paged at all (a rollup, or any other type) is NOT a
|
|
568
|
+
* failure: it comes back `ok: true, incomplete: true` (Notion's value is kept
|
|
569
|
+
* and named in `unknownFields.propertiesIncomplete`), rather than guessing.
|
|
570
|
+
*/
|
|
571
|
+
async function completeProperty(pageId, name, prop, resolved) {
|
|
572
|
+
if (prop.has_more !== true) {
|
|
573
|
+
return { ok: true, prop, incomplete: false };
|
|
574
|
+
}
|
|
575
|
+
if (!PAGEABLE_PROPERTY_TYPES.has(prop.type)) {
|
|
576
|
+
return { ok: true, prop, incomplete: true };
|
|
577
|
+
}
|
|
578
|
+
if (typeof prop.id !== 'string' || prop.id === '') {
|
|
579
|
+
return {
|
|
580
|
+
ok: false,
|
|
581
|
+
kind: 'unparseable',
|
|
582
|
+
reason: `property "${name}" is truncated by Notion but has no id to page it with`,
|
|
583
|
+
};
|
|
584
|
+
}
|
|
585
|
+
const values = [];
|
|
586
|
+
const seenCursors = new Set();
|
|
587
|
+
let cursor;
|
|
588
|
+
for (;;) {
|
|
589
|
+
const cursorQuery = cursor === undefined ? '' : `&start_cursor=${encodeURIComponent(cursor)}`;
|
|
590
|
+
const outcome = await request(resolved, 'GET', `${notionPropertyPath(pageId, prop.id)}?page_size=100${cursorQuery}`);
|
|
591
|
+
if (outcome.kind === 'notFound') {
|
|
592
|
+
return {
|
|
593
|
+
ok: false,
|
|
594
|
+
kind: 'unreachable',
|
|
595
|
+
reason: `property "${name}" of page ${pageId} was not found`,
|
|
596
|
+
};
|
|
597
|
+
}
|
|
598
|
+
if (outcome.kind !== 'ok') {
|
|
599
|
+
return {
|
|
600
|
+
ok: false,
|
|
601
|
+
kind: 'unreachable',
|
|
602
|
+
reason: `property "${name}" of page ${pageId} could not be read: ${outcome.reason}`,
|
|
603
|
+
};
|
|
604
|
+
}
|
|
605
|
+
const response = outcome.body;
|
|
606
|
+
if (!isRecord(response) ||
|
|
607
|
+
!Array.isArray(response.results) ||
|
|
608
|
+
typeof response.has_more !== 'boolean') {
|
|
609
|
+
return {
|
|
610
|
+
ok: false,
|
|
611
|
+
kind: 'unparseable',
|
|
612
|
+
reason: `property "${name}": Notion's response was not shaped like a property item list`,
|
|
613
|
+
};
|
|
614
|
+
}
|
|
615
|
+
for (const item of response.results) {
|
|
616
|
+
if (!isRecord(item) || item[prop.type] === undefined) {
|
|
617
|
+
return {
|
|
618
|
+
ok: false,
|
|
619
|
+
kind: 'unparseable',
|
|
620
|
+
reason: `property "${name}": Notion returned an item that was not shaped like a ${prop.type} item`,
|
|
621
|
+
};
|
|
622
|
+
}
|
|
623
|
+
values.push(item[prop.type]);
|
|
624
|
+
}
|
|
625
|
+
if (!response.has_more) {
|
|
626
|
+
const full = { ...prop, [prop.type]: values, has_more: false };
|
|
627
|
+
return { ok: true, prop: full, incomplete: false };
|
|
628
|
+
}
|
|
629
|
+
if (typeof response.next_cursor !== 'string' || response.next_cursor === '') {
|
|
630
|
+
return {
|
|
631
|
+
ok: false,
|
|
632
|
+
kind: 'unparseable',
|
|
633
|
+
reason: `property "${name}": pagination cursor missing`,
|
|
634
|
+
};
|
|
635
|
+
}
|
|
636
|
+
if (seenCursors.has(response.next_cursor)) {
|
|
637
|
+
return {
|
|
638
|
+
ok: false,
|
|
639
|
+
kind: 'unparseable',
|
|
640
|
+
reason: `property "${name}": pagination cursor repeated`,
|
|
641
|
+
};
|
|
642
|
+
}
|
|
643
|
+
seenCursors.add(response.next_cursor);
|
|
644
|
+
cursor = response.next_cursor;
|
|
645
|
+
}
|
|
646
|
+
}
|
|
647
|
+
/** Completes every truncated property on a page (see `completeProperty`). */
|
|
648
|
+
async function completeProperties(page, resolved) {
|
|
649
|
+
const properties = {};
|
|
650
|
+
const incomplete = [];
|
|
651
|
+
for (const [name, prop] of Object.entries(page.properties)) {
|
|
652
|
+
const done = await completeProperty(page.id, name, prop, resolved);
|
|
653
|
+
if (!done.ok) {
|
|
654
|
+
return { ok: false, kind: done.kind, field: name, reason: done.reason };
|
|
655
|
+
}
|
|
656
|
+
if (done.incomplete) {
|
|
657
|
+
incomplete.push(name);
|
|
658
|
+
}
|
|
659
|
+
properties[name] = done.prop;
|
|
660
|
+
}
|
|
661
|
+
return { ok: true, page: { ...page, properties }, incomplete };
|
|
662
|
+
}
|
|
663
|
+
async function pageToCard(rawPage, resolved) {
|
|
664
|
+
const completed = await completeProperties(rawPage, resolved);
|
|
665
|
+
if (!completed.ok) {
|
|
666
|
+
if (completed.kind === 'unreachable') {
|
|
667
|
+
return { ok: false, kind: 'unreachable', reason: completed.reason };
|
|
668
|
+
}
|
|
669
|
+
return {
|
|
670
|
+
ok: false,
|
|
671
|
+
kind: 'unparseable',
|
|
672
|
+
problems: [{ field: completed.field, message: completed.reason }],
|
|
673
|
+
};
|
|
674
|
+
}
|
|
675
|
+
const page = completed.page;
|
|
432
676
|
const problems = [];
|
|
433
677
|
let state = '';
|
|
434
678
|
const stateOutcome = extractState(page, resolved);
|
|
@@ -455,9 +699,48 @@ async function pageToCard(page, resolved) {
|
|
|
455
699
|
problems.push({ field: outcome.field, message: outcome.reason });
|
|
456
700
|
}
|
|
457
701
|
}
|
|
702
|
+
// A configured title/requires/parent property that is missing or of the
|
|
703
|
+
// wrong type is a problem, never a silently absent field: Notion returns
|
|
704
|
+
// every schema property on every page, so absence is misconfiguration.
|
|
705
|
+
// Unconfigured (defaulted) properties keep their lenient behaviour.
|
|
706
|
+
const configured = [
|
|
707
|
+
[resolved.titleConfigured ? resolved.titleProperty : undefined, 'title'],
|
|
708
|
+
[resolved.requiresConfigured ? resolved.requiresProperty : undefined, 'relation'],
|
|
709
|
+
[resolved.parentProperty, 'relation'],
|
|
710
|
+
];
|
|
711
|
+
for (const [name, expected] of configured) {
|
|
712
|
+
if (name === undefined) {
|
|
713
|
+
continue;
|
|
714
|
+
}
|
|
715
|
+
const actual = page.properties[name];
|
|
716
|
+
if (actual === undefined) {
|
|
717
|
+
problems.push({
|
|
718
|
+
field: name,
|
|
719
|
+
message: `configured property "${name}" is missing from the page (expected type ${expected})`,
|
|
720
|
+
});
|
|
721
|
+
}
|
|
722
|
+
else if (actual.type !== expected) {
|
|
723
|
+
problems.push({
|
|
724
|
+
field: name,
|
|
725
|
+
message: `configured property "${name}" has type "${actual.type}", expected "${expected}"`,
|
|
726
|
+
});
|
|
727
|
+
}
|
|
728
|
+
}
|
|
458
729
|
if (problems.length > 0) {
|
|
459
730
|
return { ok: false, kind: 'unparseable', problems };
|
|
460
731
|
}
|
|
732
|
+
if (completed.incomplete.length > 0) {
|
|
733
|
+
unknownFields.propertiesIncomplete = completed.incomplete;
|
|
734
|
+
}
|
|
735
|
+
const titleProp = page.properties[resolved.titleProperty];
|
|
736
|
+
const title = titleProp?.type === 'title' ? plainTextOf(titleProp.title) : '';
|
|
737
|
+
const requiresProp = page.properties[resolved.requiresProperty];
|
|
738
|
+
const requires = requiresProp?.type === 'relation'
|
|
739
|
+
? (requiresProp.relation ?? []).map((ref) => ref.id)
|
|
740
|
+
: undefined;
|
|
741
|
+
const parentProp = resolved.parentProperty !== undefined ? page.properties[resolved.parentProperty] : undefined;
|
|
742
|
+
const parent = parentProp?.type === 'relation' ? parentProp.relation?.[0]?.id : undefined;
|
|
743
|
+
const derived = resolved.statusMap !== undefined ? normalizeStatus(state, resolved.statusMap) : undefined;
|
|
461
744
|
return {
|
|
462
745
|
ok: true,
|
|
463
746
|
card: {
|
|
@@ -467,13 +750,221 @@ async function pageToCard(page, resolved) {
|
|
|
467
750
|
source: `notion:${resolved.databaseId}`,
|
|
468
751
|
unknownFields,
|
|
469
752
|
properties,
|
|
753
|
+
...(title !== '' ? { title } : {}),
|
|
754
|
+
...(requires !== undefined ? { requires } : {}),
|
|
755
|
+
...(parent !== undefined ? { parent } : {}),
|
|
756
|
+
...(derived?.kind === 'mapped' ? { status: derived.status } : {}),
|
|
470
757
|
},
|
|
471
758
|
};
|
|
472
759
|
}
|
|
760
|
+
/**
|
|
761
|
+
* Every child block of `id`, following `has_more`/`next_cursor` until
|
|
762
|
+
* exhausted. Blocks are returned raw: `renderChildren` validates each one and
|
|
763
|
+
* counts what it cannot render. Any problem with the list itself (a failed
|
|
764
|
+
* page of results, a missing or repeated cursor, a malformed response) is
|
|
765
|
+
* `ok: false`, never a shorter list reported as complete.
|
|
766
|
+
*/
|
|
767
|
+
async function fetchChildren(id, resolved) {
|
|
768
|
+
const blocks = [];
|
|
769
|
+
const seenCursors = new Set();
|
|
770
|
+
let cursor;
|
|
771
|
+
for (;;) {
|
|
772
|
+
const cursorQuery = cursor === undefined ? '' : `&start_cursor=${encodeURIComponent(cursor)}`;
|
|
773
|
+
const outcome = await request(resolved, 'GET', `/blocks/${encodeURIComponent(id)}/children?page_size=100${cursorQuery}`);
|
|
774
|
+
if (outcome.kind === 'notFound') {
|
|
775
|
+
return { ok: false, kind: 'unreachable', reason: `content of block ${id} was not found` };
|
|
776
|
+
}
|
|
777
|
+
if (outcome.kind !== 'ok') {
|
|
778
|
+
return {
|
|
779
|
+
ok: false,
|
|
780
|
+
kind: 'unreachable',
|
|
781
|
+
reason: `content of block ${id} could not be read: ${outcome.reason}`,
|
|
782
|
+
};
|
|
783
|
+
}
|
|
784
|
+
const response = outcome.body;
|
|
785
|
+
if (!isRecord(response) ||
|
|
786
|
+
!Array.isArray(response.results) ||
|
|
787
|
+
typeof response.has_more !== 'boolean') {
|
|
788
|
+
return {
|
|
789
|
+
ok: false,
|
|
790
|
+
kind: 'unparseable',
|
|
791
|
+
reason: `content of block ${id}: Notion's response was not shaped like a block list`,
|
|
792
|
+
};
|
|
793
|
+
}
|
|
794
|
+
blocks.push(...response.results);
|
|
795
|
+
if (!response.has_more) {
|
|
796
|
+
return { ok: true, blocks };
|
|
797
|
+
}
|
|
798
|
+
if (typeof response.next_cursor !== 'string' || response.next_cursor === '') {
|
|
799
|
+
return {
|
|
800
|
+
ok: false,
|
|
801
|
+
kind: 'unparseable',
|
|
802
|
+
reason: `content of block ${id}: pagination cursor missing`,
|
|
803
|
+
};
|
|
804
|
+
}
|
|
805
|
+
if (seenCursors.has(response.next_cursor)) {
|
|
806
|
+
return {
|
|
807
|
+
ok: false,
|
|
808
|
+
kind: 'unparseable',
|
|
809
|
+
reason: `content of block ${id}: pagination cursor repeated`,
|
|
810
|
+
};
|
|
811
|
+
}
|
|
812
|
+
seenCursors.add(response.next_cursor);
|
|
813
|
+
cursor = response.next_cursor;
|
|
814
|
+
}
|
|
815
|
+
}
|
|
816
|
+
function renderRichText(fragments) {
|
|
817
|
+
return (fragments ?? [])
|
|
818
|
+
.map((fragment) => {
|
|
819
|
+
let text = fragment.plain_text ?? '';
|
|
820
|
+
if (text === '') {
|
|
821
|
+
return '';
|
|
822
|
+
}
|
|
823
|
+
if (fragment.annotations?.code) {
|
|
824
|
+
text = `\`${text}\``;
|
|
825
|
+
}
|
|
826
|
+
if (fragment.annotations?.bold) {
|
|
827
|
+
text = `**${text}**`;
|
|
828
|
+
}
|
|
829
|
+
if (fragment.annotations?.italic) {
|
|
830
|
+
text = `_${text}_`;
|
|
831
|
+
}
|
|
832
|
+
if (fragment.href) {
|
|
833
|
+
text = `[${text}](${fragment.href})`;
|
|
834
|
+
}
|
|
835
|
+
return text;
|
|
836
|
+
})
|
|
837
|
+
.join('');
|
|
838
|
+
}
|
|
839
|
+
/** Block types whose payload must carry a `rich_text` array to be rendered. */
|
|
840
|
+
const RICH_TEXT_TYPES = new Set([
|
|
841
|
+
'paragraph',
|
|
842
|
+
'heading_1',
|
|
843
|
+
'heading_2',
|
|
844
|
+
'heading_3',
|
|
845
|
+
'bulleted_list_item',
|
|
846
|
+
'numbered_list_item',
|
|
847
|
+
'to_do',
|
|
848
|
+
'quote',
|
|
849
|
+
'code',
|
|
850
|
+
]);
|
|
851
|
+
/**
|
|
852
|
+
* Renders the children of one block (or page) to markdown. A body is exactly
|
|
853
|
+
* one of three things, never silently partial:
|
|
854
|
+
* 1. complete;
|
|
855
|
+
* 2. marked incomplete: blocks that cannot be rendered (unsupported type,
|
|
856
|
+
* no type, missing payload or rich text) are counted in
|
|
857
|
+
* `state.skipped`, and depth truncation is counted in `state.truncated`
|
|
858
|
+
* with a marker line (both surface in `unknownFields.body`);
|
|
859
|
+
* 3. the whole `get` fails with a reason: `unreachable` for a failed block-list
|
|
860
|
+
* fetch, `unparseable` for a malformed or looping one (on any page of
|
|
861
|
+
* results, at any depth).
|
|
862
|
+
* Blocks at
|
|
863
|
+
* MAX_BODY_DEPTH that have children are not descended into: they are counted
|
|
864
|
+
* in `state.truncated` and followed by a visible marker line.
|
|
865
|
+
*/
|
|
866
|
+
async function renderChildren(id, depth, resolved, state) {
|
|
867
|
+
const fetched = await fetchChildren(id, resolved);
|
|
868
|
+
if (!fetched.ok) {
|
|
869
|
+
return fetched;
|
|
870
|
+
}
|
|
871
|
+
const parts = [];
|
|
872
|
+
let numbered = 0;
|
|
873
|
+
for (const raw of fetched.blocks) {
|
|
874
|
+
if (!isRecord(raw) || typeof raw.type !== 'string') {
|
|
875
|
+
state.skipped += 1;
|
|
876
|
+
continue;
|
|
877
|
+
}
|
|
878
|
+
const block = raw;
|
|
879
|
+
const rawPayload = block[block.type];
|
|
880
|
+
if (!isRecord(rawPayload) ||
|
|
881
|
+
(block.has_children === true && typeof block.id !== 'string') ||
|
|
882
|
+
(RICH_TEXT_TYPES.has(block.type) && !Array.isArray(rawPayload.rich_text))) {
|
|
883
|
+
state.skipped += 1;
|
|
884
|
+
continue;
|
|
885
|
+
}
|
|
886
|
+
numbered = block.type === 'numbered_list_item' ? numbered + 1 : 0;
|
|
887
|
+
const payload = rawPayload;
|
|
888
|
+
const richFragments = payload.rich_text;
|
|
889
|
+
const rich = renderRichText(richFragments);
|
|
890
|
+
let text;
|
|
891
|
+
switch (block.type) {
|
|
892
|
+
case 'paragraph':
|
|
893
|
+
text = rich;
|
|
894
|
+
break;
|
|
895
|
+
case 'heading_1':
|
|
896
|
+
text = `# ${rich}`;
|
|
897
|
+
break;
|
|
898
|
+
case 'heading_2':
|
|
899
|
+
text = `## ${rich}`;
|
|
900
|
+
break;
|
|
901
|
+
case 'heading_3':
|
|
902
|
+
text = `### ${rich}`;
|
|
903
|
+
break;
|
|
904
|
+
case 'bulleted_list_item':
|
|
905
|
+
text = `- ${rich}`;
|
|
906
|
+
break;
|
|
907
|
+
case 'numbered_list_item':
|
|
908
|
+
text = `${numbered}. ${rich}`;
|
|
909
|
+
break;
|
|
910
|
+
case 'to_do':
|
|
911
|
+
text = `- [${payload.checked === true ? 'x' : ' '}] ${rich}`;
|
|
912
|
+
break;
|
|
913
|
+
case 'quote':
|
|
914
|
+
text = rich
|
|
915
|
+
.split('\n')
|
|
916
|
+
.map((line) => `> ${line}`)
|
|
917
|
+
.join('\n');
|
|
918
|
+
break;
|
|
919
|
+
case 'code': {
|
|
920
|
+
const language = typeof payload.language === 'string' && payload.language !== 'plain text'
|
|
921
|
+
? payload.language
|
|
922
|
+
: '';
|
|
923
|
+
text = `\`\`\`${language}\n${plainTextOf(richFragments)}\n\`\`\``;
|
|
924
|
+
break;
|
|
925
|
+
}
|
|
926
|
+
case 'divider':
|
|
927
|
+
text = '---';
|
|
928
|
+
break;
|
|
929
|
+
default:
|
|
930
|
+
state.skipped += 1;
|
|
931
|
+
continue;
|
|
932
|
+
}
|
|
933
|
+
if (block.has_children === true && depth < MAX_BODY_DEPTH) {
|
|
934
|
+
const child = await renderChildren(block.id, depth + 1, resolved, state);
|
|
935
|
+
if (!child.ok) {
|
|
936
|
+
return child;
|
|
937
|
+
}
|
|
938
|
+
if (child.text !== '') {
|
|
939
|
+
const indented = child.text
|
|
940
|
+
.split('\n')
|
|
941
|
+
.map((line) => (line === '' ? line : ` ${line}`))
|
|
942
|
+
.join('\n');
|
|
943
|
+
text = `${text}\n${indented}`;
|
|
944
|
+
}
|
|
945
|
+
}
|
|
946
|
+
if (block.has_children === true && depth >= MAX_BODY_DEPTH) {
|
|
947
|
+
state.truncated += 1;
|
|
948
|
+
text = `${text}\n <!-- children omitted: depth limit -->`;
|
|
949
|
+
}
|
|
950
|
+
if (text === '') {
|
|
951
|
+
continue;
|
|
952
|
+
}
|
|
953
|
+
parts.push({ type: block.type, text });
|
|
954
|
+
}
|
|
955
|
+
let out = '';
|
|
956
|
+
parts.forEach((part, index) => {
|
|
957
|
+
if (index > 0) {
|
|
958
|
+
out += parts[index - 1]?.type === part.type && part.type !== 'paragraph' ? '\n' : '\n\n';
|
|
959
|
+
}
|
|
960
|
+
out += part.text;
|
|
961
|
+
});
|
|
962
|
+
return { ok: true, text: out };
|
|
963
|
+
}
|
|
473
964
|
async function performGet(id, resolved) {
|
|
474
965
|
const outcome = await request(resolved, 'GET', `/pages/${encodeURIComponent(id)}`);
|
|
475
966
|
if (outcome.kind !== 'ok') {
|
|
476
|
-
return toGetFailure(outcome);
|
|
967
|
+
return toGetFailure(id, outcome);
|
|
477
968
|
}
|
|
478
969
|
const page = asNotionPage(outcome.body);
|
|
479
970
|
if (page === undefined) {
|
|
@@ -490,7 +981,41 @@ async function performGet(id, resolved) {
|
|
|
490
981
|
}
|
|
491
982
|
return { outcome: 'unparseable', id, problems: mapped.problems };
|
|
492
983
|
}
|
|
493
|
-
|
|
984
|
+
// The body costs extra calls, so only `get` pays for it (never `list`).
|
|
985
|
+
// A failure here is `unreachable` (fetch) or `unparseable` (malformed list): a card must not silently come back
|
|
986
|
+
// without the body it would otherwise have.
|
|
987
|
+
const state = { skipped: 0, truncated: 0 };
|
|
988
|
+
const body = await renderChildren(page.id, 0, resolved, state);
|
|
989
|
+
if (!body.ok) {
|
|
990
|
+
if (body.kind === 'unreachable') {
|
|
991
|
+
return { outcome: 'unreachable', reason: body.reason };
|
|
992
|
+
}
|
|
993
|
+
return {
|
|
994
|
+
outcome: 'unparseable',
|
|
995
|
+
id,
|
|
996
|
+
problems: [{ field: 'body', message: body.reason }],
|
|
997
|
+
};
|
|
998
|
+
}
|
|
999
|
+
return {
|
|
1000
|
+
outcome: 'found',
|
|
1001
|
+
card: {
|
|
1002
|
+
...mapped.card,
|
|
1003
|
+
...(body.text !== '' ? { body: body.text } : {}),
|
|
1004
|
+
...(state.skipped > 0 || state.truncated > 0
|
|
1005
|
+
? {
|
|
1006
|
+
unknownFields: {
|
|
1007
|
+
...mapped.card.unknownFields,
|
|
1008
|
+
body: {
|
|
1009
|
+
...(state.skipped > 0 ? { skippedBlocks: state.skipped } : {}),
|
|
1010
|
+
...(state.truncated > 0
|
|
1011
|
+
? { truncatedAtDepth: MAX_BODY_DEPTH, truncatedBlocks: state.truncated }
|
|
1012
|
+
: {}),
|
|
1013
|
+
},
|
|
1014
|
+
},
|
|
1015
|
+
}
|
|
1016
|
+
: {}),
|
|
1017
|
+
},
|
|
1018
|
+
};
|
|
494
1019
|
}
|
|
495
1020
|
async function performList(filter, resolved) {
|
|
496
1021
|
const cards = [];
|
|
@@ -573,24 +1098,66 @@ async function performWriteState(id, state, resolved, options) {
|
|
|
573
1098
|
});
|
|
574
1099
|
return toWriteResult(patchOutcome, `no card with id ${id}`);
|
|
575
1100
|
}
|
|
1101
|
+
/** A string that is wholly a decimal: optional sign, digits, optional fraction, optional exponent. */
|
|
1102
|
+
const STRICT_DECIMAL = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:[eE][+-]?\d+)?$/;
|
|
1103
|
+
/**
|
|
1104
|
+
* Strict decimal parse for number properties: a finite number, or a string
|
|
1105
|
+
* that is wholly a finite decimal (see `STRICT_DECIMAL`). NaN, Infinity, "",
|
|
1106
|
+
* " ", "12abc", "0x10" are all undefined -- the caller refuses; a bad value is
|
|
1107
|
+
* never written as 0.
|
|
1108
|
+
*/
|
|
1109
|
+
function parseStrictNumber(value) {
|
|
1110
|
+
if (typeof value === 'number') {
|
|
1111
|
+
return Number.isFinite(value) ? value : undefined;
|
|
1112
|
+
}
|
|
1113
|
+
if (typeof value !== 'string' || !STRICT_DECIMAL.test(value)) {
|
|
1114
|
+
return undefined;
|
|
1115
|
+
}
|
|
1116
|
+
const parsed = Number(value);
|
|
1117
|
+
return Number.isFinite(parsed) ? parsed : undefined;
|
|
1118
|
+
}
|
|
576
1119
|
/**
|
|
577
1120
|
* The per-type write mapping `annotate` and `createCard` both apply to a
|
|
578
|
-
* flat
|
|
579
|
-
* safely without more information than a flat
|
|
1121
|
+
* flat value: only `rich_text`, `url` and `number` can be written back
|
|
1122
|
+
* safely without more information than a flat value carries (a `select`
|
|
580
1123
|
* needs to know whether the option already exists, `multi_select` needs
|
|
581
|
-
* a list, `
|
|
582
|
-
*
|
|
1124
|
+
* a list, `date` needs a parse that can fail in ways a plain write cannot
|
|
1125
|
+
* surface). A `number` is written only from a strictly parsed finite value
|
|
1126
|
+
* (see `parseStrictNumber`). Anything else is `ok: false` — the caller
|
|
583
1127
|
* decides what that means (refuse the annotate, or refuse the whole
|
|
584
1128
|
* create) rather than this function silently doing nothing.
|
|
585
1129
|
*/
|
|
586
|
-
function propertyWritePayload(type, value) {
|
|
587
|
-
if (type === '
|
|
588
|
-
|
|
1130
|
+
function propertyWritePayload(name, type, value) {
|
|
1131
|
+
if (type === 'number') {
|
|
1132
|
+
const parsed = parseStrictNumber(value);
|
|
1133
|
+
if (parsed === undefined) {
|
|
1134
|
+
const shown = typeof value === 'string' ? JSON.stringify(value) : String(value);
|
|
1135
|
+
return {
|
|
1136
|
+
ok: false,
|
|
1137
|
+
reason: `property "${name}" is a number property and ${shown} is not a finite decimal number (NaN, Infinity, empty and trailing text are refused, never written as 0)`,
|
|
1138
|
+
};
|
|
1139
|
+
}
|
|
1140
|
+
return { ok: true, payload: { number: parsed } };
|
|
589
1141
|
}
|
|
590
|
-
if (type === 'url') {
|
|
1142
|
+
if (type === 'rich_text' || type === 'url') {
|
|
1143
|
+
if (typeof value !== 'string') {
|
|
1144
|
+
return {
|
|
1145
|
+
ok: false,
|
|
1146
|
+
reason: `property "${name}" is a ${type} property and needs a string value, not ${typeof value}`,
|
|
1147
|
+
};
|
|
1148
|
+
}
|
|
1149
|
+
if (type === 'rich_text') {
|
|
1150
|
+
return {
|
|
1151
|
+
ok: true,
|
|
1152
|
+
payload: { rich_text: value === '' ? [] : [{ text: { content: value } }] },
|
|
1153
|
+
};
|
|
1154
|
+
}
|
|
591
1155
|
return { ok: true, payload: { url: value === '' ? null : value } };
|
|
592
1156
|
}
|
|
593
|
-
return {
|
|
1157
|
+
return {
|
|
1158
|
+
ok: false,
|
|
1159
|
+
reason: `property "${name}" has type "${type}", which cannot be written safely — only rich_text, url and number properties are supported`,
|
|
1160
|
+
};
|
|
594
1161
|
}
|
|
595
1162
|
/**
|
|
596
1163
|
* Creates a page in the configured database. Notion has nothing resembling
|
|
@@ -652,20 +1219,34 @@ async function performCreateCard(card, resolved) {
|
|
|
652
1219
|
problems.push(`${name} (no such property on the database)`);
|
|
653
1220
|
continue;
|
|
654
1221
|
}
|
|
655
|
-
|
|
1222
|
+
// `Card.properties` is typed to carry any JSON-safe value (see
|
|
1223
|
+
// card.ts's `PropertyValue`). `propertyWritePayload` takes `unknown`
|
|
1224
|
+
// and owns every per-type decision: a finite number (or strict
|
|
1225
|
+
// decimal string) for a `number` property, a string for `rich_text`
|
|
1226
|
+
// and `url`, and a named refusal for anything else.
|
|
1227
|
+
const written = propertyWritePayload(name, def.type, value);
|
|
656
1228
|
if (!written.ok) {
|
|
657
|
-
problems.push(
|
|
1229
|
+
problems.push(written.reason);
|
|
658
1230
|
continue;
|
|
659
1231
|
}
|
|
660
1232
|
mappable[name] = written.payload;
|
|
661
1233
|
}
|
|
1234
|
+
// Same discipline as the loop above, for the title property: it is
|
|
1235
|
+
// read a second time below (title is written from the same source
|
|
1236
|
+
// value, never re-entered into `mappable`), so its own non-string
|
|
1237
|
+
// check must happen here, before the early return, rather than at
|
|
1238
|
+
// the point it is actually used.
|
|
1239
|
+
const titlePropertyRaw = card.properties?.[resolved.titleProperty];
|
|
1240
|
+
if (titlePropertyRaw !== undefined && typeof titlePropertyRaw !== 'string') {
|
|
1241
|
+
problems.push(`${resolved.titleProperty} (value is not a string, and NotionBoard can only write a flat string title)`);
|
|
1242
|
+
}
|
|
662
1243
|
if (problems.length > 0) {
|
|
663
1244
|
return {
|
|
664
1245
|
outcome: 'refused',
|
|
665
1246
|
reason: `card cannot be created without silently dropping or misinterpreting data: ${problems.join(', ')}`,
|
|
666
1247
|
};
|
|
667
1248
|
}
|
|
668
|
-
const titleText =
|
|
1249
|
+
const titleText = typeof titlePropertyRaw === 'string' ? titlePropertyRaw : '';
|
|
669
1250
|
const properties = {
|
|
670
1251
|
...mappable,
|
|
671
1252
|
[resolved.titleProperty]: { title: titleText === '' ? [] : [{ text: { content: titleText } }] },
|
|
@@ -701,12 +1282,15 @@ async function performAnnotate(id, patch, resolved, options) {
|
|
|
701
1282
|
reason: `property "${key}" does not exist on card ${id}, so it cannot be annotated`,
|
|
702
1283
|
};
|
|
703
1284
|
}
|
|
704
|
-
const written = propertyWritePayload(existing.type, value);
|
|
1285
|
+
const written = propertyWritePayload(key, existing.type, value);
|
|
705
1286
|
if (!written.ok) {
|
|
706
|
-
return {
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
1287
|
+
return { outcome: 'refused', reason: written.reason };
|
|
1288
|
+
}
|
|
1289
|
+
if (existing.type === 'number') {
|
|
1290
|
+
if (existing.number !== parseStrictNumber(value)) {
|
|
1291
|
+
toWrite[key] = written.payload;
|
|
1292
|
+
}
|
|
1293
|
+
continue;
|
|
710
1294
|
}
|
|
711
1295
|
const currentValue = existing.type === 'rich_text' ? plainTextOf(existing.rich_text) : (existing.url ?? '');
|
|
712
1296
|
if (currentValue !== value) {
|
|
@@ -731,3 +1315,60 @@ export function createNotionBoard(config) {
|
|
|
731
1315
|
annotate: (id, patch, options) => performAnnotate(id, patch, resolved, options),
|
|
732
1316
|
};
|
|
733
1317
|
}
|
|
1318
|
+
async function performReadPage(pageId, resolved) {
|
|
1319
|
+
const outcome = await request(resolved, 'GET', `/pages/${encodeURIComponent(pageId)}`);
|
|
1320
|
+
if (outcome.kind === 'notFound') {
|
|
1321
|
+
return {
|
|
1322
|
+
ok: false,
|
|
1323
|
+
kind: 'not-found',
|
|
1324
|
+
reason: `Notion returned not found for page ${pageId}. ${CONNECTION_HINT}`,
|
|
1325
|
+
};
|
|
1326
|
+
}
|
|
1327
|
+
if (outcome.kind !== 'ok') {
|
|
1328
|
+
return { ok: false, kind: 'unreachable', reason: outcome.reason };
|
|
1329
|
+
}
|
|
1330
|
+
const page = asNotionPage(outcome.body);
|
|
1331
|
+
if (page === undefined) {
|
|
1332
|
+
return { ok: false, kind: 'unparseable', reason: unreadableBodyMessage('page') };
|
|
1333
|
+
}
|
|
1334
|
+
const titleProperty = Object.values(page.properties).find((prop) => prop.type === 'title');
|
|
1335
|
+
if (titleProperty === undefined) {
|
|
1336
|
+
return {
|
|
1337
|
+
ok: false,
|
|
1338
|
+
kind: 'unparseable',
|
|
1339
|
+
reason: `page ${pageId} has no title property, so its title cannot be read`,
|
|
1340
|
+
};
|
|
1341
|
+
}
|
|
1342
|
+
const lastEditedTime = isRecord(outcome.body) ? outcome.body.last_edited_time : undefined;
|
|
1343
|
+
if (typeof lastEditedTime !== 'string') {
|
|
1344
|
+
return {
|
|
1345
|
+
ok: false,
|
|
1346
|
+
kind: 'unparseable',
|
|
1347
|
+
reason: `page ${pageId} has no last_edited_time, so the response is not a Notion page`,
|
|
1348
|
+
};
|
|
1349
|
+
}
|
|
1350
|
+
const state = { skipped: 0, truncated: 0 };
|
|
1351
|
+
const body = await renderChildren(page.id, 0, resolved, state);
|
|
1352
|
+
if (!body.ok) {
|
|
1353
|
+
return { ok: false, kind: body.kind, reason: body.reason };
|
|
1354
|
+
}
|
|
1355
|
+
return {
|
|
1356
|
+
ok: true,
|
|
1357
|
+
title: plainTextOf(titleProperty.title),
|
|
1358
|
+
markdown: body.text,
|
|
1359
|
+
truncated: state.truncated > 0,
|
|
1360
|
+
skippedBlocks: state.skipped,
|
|
1361
|
+
lastEditedTime,
|
|
1362
|
+
};
|
|
1363
|
+
}
|
|
1364
|
+
/**
|
|
1365
|
+
* A reader for ordinary Notion pages, sharing the board's request, retry,
|
|
1366
|
+
* sleep and block-rendering code (and its API version). Use it for the pages
|
|
1367
|
+
* a backlog row points at -- a design page URL, the rows of an ADRs relation --
|
|
1368
|
+
* which `NotionBoard.get` cannot read because they are not rows of the
|
|
1369
|
+
* configured database.
|
|
1370
|
+
*/
|
|
1371
|
+
export function createNotionPageReader(config) {
|
|
1372
|
+
const resolved = resolveTransport(config);
|
|
1373
|
+
return { readPage: (pageId) => performReadPage(pageId, resolved) };
|
|
1374
|
+
}
|