@verevoir/aigency-work 0.2.0 → 0.3.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 +126 -0
- package/dist/asf-board.js +112 -39
- package/dist/backlog-board.d.ts +21 -0
- package/dist/backlog-board.js +383 -0
- 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 +17 -2
- package/dist/index.d.ts +11 -3
- package/dist/index.js +5 -1
- package/dist/notion-board.d.ts +33 -0
- package/dist/notion-board.js +515 -4
- package/dist/status.d.ts +24 -0
- package/dist/status.js +36 -0
- package/dist/trello-board.d.ts +41 -0
- package/dist/trello-board.js +337 -0
- package/package.json +1 -1
package/dist/notion-board.d.ts
CHANGED
|
@@ -1,4 +1,11 @@
|
|
|
1
1
|
import type { CardSource, CardSink, ListResult } from './board.js';
|
|
2
|
+
import type { StatusMap } from './status.js';
|
|
3
|
+
/**
|
|
4
|
+
* A ready-made `StatusMap` for the conventional Notion status names. It is
|
|
5
|
+
* OPT-IN: a board derives `Card.status` only when this (or another map) is
|
|
6
|
+
* passed as `NotionBoardConfig.statusMap`.
|
|
7
|
+
*/
|
|
8
|
+
export declare const NOTION_DEFAULT_STATUS_MAP: StatusMap;
|
|
2
9
|
/** The API version this board was built and tested against. */
|
|
3
10
|
export declare const NOTION_VERSION = "2022-06-28";
|
|
4
11
|
/** The reason given for any write that supplies `expectedRevision`. */
|
|
@@ -27,6 +34,24 @@ export interface NotionBoardConfig {
|
|
|
27
34
|
readonly statusProperty?: string;
|
|
28
35
|
/** The property that carries the card's title. Defaults to "Name". */
|
|
29
36
|
readonly titleProperty?: string;
|
|
37
|
+
/**
|
|
38
|
+
* The relation property whose related page ids become `Card.requires`.
|
|
39
|
+
* Defaults to "Depends on". `requires` is absent when the page has no
|
|
40
|
+
* such relation property.
|
|
41
|
+
*/
|
|
42
|
+
readonly requiresProperty?: string;
|
|
43
|
+
/**
|
|
44
|
+
* The relation property whose first related page id becomes
|
|
45
|
+
* `Card.parent`. No default: `parent` is only filled when this is set.
|
|
46
|
+
*/
|
|
47
|
+
readonly parentProperty?: string;
|
|
48
|
+
/**
|
|
49
|
+
* Maps this database's native states to the normalized `Status`. When
|
|
50
|
+
* given, `Card.status` is derived from the native state on read (absent
|
|
51
|
+
* when the state is unmapped). With no map there is no `status`. See
|
|
52
|
+
* `NOTION_DEFAULT_STATUS_MAP`, which is not applied unless passed.
|
|
53
|
+
*/
|
|
54
|
+
readonly statusMap?: StatusMap;
|
|
30
55
|
/** Injected for tests; defaults to the platform's global `fetch`. */
|
|
31
56
|
readonly fetch?: NotionFetch;
|
|
32
57
|
/** Injected for tests; defaults to a real timer-backed delay. */
|
|
@@ -44,4 +69,12 @@ export interface NotionBoard extends CardSource, CardSink {
|
|
|
44
69
|
*/
|
|
45
70
|
list(filter?: Record<string, unknown>): Promise<ListResult>;
|
|
46
71
|
}
|
|
72
|
+
/**
|
|
73
|
+
* The path of one page property item, with the property id encoded exactly
|
|
74
|
+
* once. Notion hands property ids out already URL-encoded (e.g. `%3DfL%3F`),
|
|
75
|
+
* so encoding them again would send `%253DfL%253F` and 404. The id is decoded
|
|
76
|
+
* first (a malformed escape is taken literally, never thrown) and then
|
|
77
|
+
* encoded, so an encoded id and its raw form give the same path.
|
|
78
|
+
*/
|
|
79
|
+
export declare function notionPropertyPath(pageId: string, propertyId: string): string;
|
|
47
80
|
export declare function createNotionBoard(config: NotionBoardConfig): NotionBoard;
|
package/dist/notion-board.js
CHANGED
|
@@ -11,6 +11,57 @@
|
|
|
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;
|
|
14
65
|
/** The API version this board was built and tested against. */
|
|
15
66
|
export const NOTION_VERSION = '2022-06-28';
|
|
16
67
|
const DEFAULT_MAX_ATTEMPTS = 4;
|
|
@@ -43,6 +94,11 @@ function resolveConfig(config) {
|
|
|
43
94
|
getToken: config.getToken,
|
|
44
95
|
statusProperty: config.statusProperty ?? 'Status',
|
|
45
96
|
titleProperty: config.titleProperty ?? 'Name',
|
|
97
|
+
titleConfigured: config.titleProperty !== undefined,
|
|
98
|
+
requiresProperty: config.requiresProperty ?? 'Depends on',
|
|
99
|
+
requiresConfigured: config.requiresProperty !== undefined,
|
|
100
|
+
parentProperty: config.parentProperty,
|
|
101
|
+
statusMap: config.statusMap,
|
|
46
102
|
fetch: config.fetch ?? defaultFetch,
|
|
47
103
|
sleep: config.sleep ?? defaultSleep,
|
|
48
104
|
// Clamped to at least 1: a configured 0 (or negative) used to fall
|
|
@@ -308,7 +364,16 @@ async function resolveRelation(propertyName, refs, resolved) {
|
|
|
308
364
|
reason: `"${propertyName}" references page ${ref.id}, whose "Ticket" property has type "${ticket.type}", not rich_text`,
|
|
309
365
|
};
|
|
310
366
|
}
|
|
311
|
-
|
|
367
|
+
// The Ticket is itself an inline property read: page it if truncated.
|
|
368
|
+
const fullTicket = await completeProperty(ref.id, 'Ticket', ticket, resolved);
|
|
369
|
+
if (!fullTicket.ok) {
|
|
370
|
+
return {
|
|
371
|
+
ok: false,
|
|
372
|
+
kind: fullTicket.kind === 'unreachable' ? 'unreachable' : 'problem',
|
|
373
|
+
reason: `"${propertyName}" references page ${ref.id}: ${fullTicket.reason}`,
|
|
374
|
+
};
|
|
375
|
+
}
|
|
376
|
+
const text = plainTextOf(fullTicket.prop.rich_text);
|
|
312
377
|
if (text === '') {
|
|
313
378
|
return {
|
|
314
379
|
ok: false,
|
|
@@ -379,6 +444,13 @@ async function flattenProperty(name, prop, resolved, properties, unknownFields)
|
|
|
379
444
|
}
|
|
380
445
|
return { ok: true };
|
|
381
446
|
}
|
|
447
|
+
case 'unique_id': {
|
|
448
|
+
const uid = prop.unique_id;
|
|
449
|
+
if (uid && uid.number !== null && uid.number !== undefined) {
|
|
450
|
+
properties[name] = uid.prefix ? `${uid.prefix}-${uid.number}` : String(uid.number);
|
|
451
|
+
}
|
|
452
|
+
return { ok: true };
|
|
453
|
+
}
|
|
382
454
|
case 'relation': {
|
|
383
455
|
const refs = prop.relation ?? [];
|
|
384
456
|
if (refs.length === 0) {
|
|
@@ -428,7 +500,146 @@ function extractState(page, resolved) {
|
|
|
428
500
|
reason: `property "${resolved.statusProperty}" has type "${prop.type}", not select or status, so its state cannot be read`,
|
|
429
501
|
};
|
|
430
502
|
}
|
|
431
|
-
|
|
503
|
+
/** Inline value types Notion truncates at 25 items and lets us page in full. */
|
|
504
|
+
const PAGEABLE_PROPERTY_TYPES = new Set([
|
|
505
|
+
'relation',
|
|
506
|
+
'title',
|
|
507
|
+
'rich_text',
|
|
508
|
+
'people',
|
|
509
|
+
]);
|
|
510
|
+
/**
|
|
511
|
+
* The path of one page property item, with the property id encoded exactly
|
|
512
|
+
* once. Notion hands property ids out already URL-encoded (e.g. `%3DfL%3F`),
|
|
513
|
+
* so encoding them again would send `%253DfL%253F` and 404. The id is decoded
|
|
514
|
+
* first (a malformed escape is taken literally, never thrown) and then
|
|
515
|
+
* encoded, so an encoded id and its raw form give the same path.
|
|
516
|
+
*/
|
|
517
|
+
export function notionPropertyPath(pageId, propertyId) {
|
|
518
|
+
let decoded;
|
|
519
|
+
try {
|
|
520
|
+
decoded = decodeURIComponent(propertyId);
|
|
521
|
+
}
|
|
522
|
+
catch {
|
|
523
|
+
decoded = propertyId;
|
|
524
|
+
}
|
|
525
|
+
return `/pages/${encodeURIComponent(pageId)}/properties/${encodeURIComponent(decoded)}`;
|
|
526
|
+
}
|
|
527
|
+
/**
|
|
528
|
+
* Returns the property with its full value. LAZY: a property without
|
|
529
|
+
* `has_more: true` is returned as-is with no call. A truncated pageable one
|
|
530
|
+
* is fetched in full from /pages/{page}/properties/{property id}, following
|
|
531
|
+
* `next_cursor` with a repeated-cursor guard; any failure is `ok: false`,
|
|
532
|
+
* never a shorter value, and its `kind` says why: `unreachable` for a fetch
|
|
533
|
+
* failure, `unparseable` for a malformed or unpageable response. A truncated
|
|
534
|
+
* property that cannot be paged at all (a rollup, or any other type) is NOT a
|
|
535
|
+
* failure: it comes back `ok: true, incomplete: true` (Notion's value is kept
|
|
536
|
+
* and named in `unknownFields.propertiesIncomplete`), rather than guessing.
|
|
537
|
+
*/
|
|
538
|
+
async function completeProperty(pageId, name, prop, resolved) {
|
|
539
|
+
if (prop.has_more !== true) {
|
|
540
|
+
return { ok: true, prop, incomplete: false };
|
|
541
|
+
}
|
|
542
|
+
if (!PAGEABLE_PROPERTY_TYPES.has(prop.type)) {
|
|
543
|
+
return { ok: true, prop, incomplete: true };
|
|
544
|
+
}
|
|
545
|
+
if (typeof prop.id !== 'string' || prop.id === '') {
|
|
546
|
+
return {
|
|
547
|
+
ok: false,
|
|
548
|
+
kind: 'unparseable',
|
|
549
|
+
reason: `property "${name}" is truncated by Notion but has no id to page it with`,
|
|
550
|
+
};
|
|
551
|
+
}
|
|
552
|
+
const values = [];
|
|
553
|
+
const seenCursors = new Set();
|
|
554
|
+
let cursor;
|
|
555
|
+
for (;;) {
|
|
556
|
+
const cursorQuery = cursor === undefined ? '' : `&start_cursor=${encodeURIComponent(cursor)}`;
|
|
557
|
+
const outcome = await request(resolved, 'GET', `${notionPropertyPath(pageId, prop.id)}?page_size=100${cursorQuery}`);
|
|
558
|
+
if (outcome.kind === 'notFound') {
|
|
559
|
+
return {
|
|
560
|
+
ok: false,
|
|
561
|
+
kind: 'unreachable',
|
|
562
|
+
reason: `property "${name}" of page ${pageId} was not found`,
|
|
563
|
+
};
|
|
564
|
+
}
|
|
565
|
+
if (outcome.kind !== 'ok') {
|
|
566
|
+
return {
|
|
567
|
+
ok: false,
|
|
568
|
+
kind: 'unreachable',
|
|
569
|
+
reason: `property "${name}" of page ${pageId} could not be read: ${outcome.reason}`,
|
|
570
|
+
};
|
|
571
|
+
}
|
|
572
|
+
const response = outcome.body;
|
|
573
|
+
if (!isRecord(response) ||
|
|
574
|
+
!Array.isArray(response.results) ||
|
|
575
|
+
typeof response.has_more !== 'boolean') {
|
|
576
|
+
return {
|
|
577
|
+
ok: false,
|
|
578
|
+
kind: 'unparseable',
|
|
579
|
+
reason: `property "${name}": Notion's response was not shaped like a property item list`,
|
|
580
|
+
};
|
|
581
|
+
}
|
|
582
|
+
for (const item of response.results) {
|
|
583
|
+
if (!isRecord(item) || item[prop.type] === undefined) {
|
|
584
|
+
return {
|
|
585
|
+
ok: false,
|
|
586
|
+
kind: 'unparseable',
|
|
587
|
+
reason: `property "${name}": Notion returned an item that was not shaped like a ${prop.type} item`,
|
|
588
|
+
};
|
|
589
|
+
}
|
|
590
|
+
values.push(item[prop.type]);
|
|
591
|
+
}
|
|
592
|
+
if (!response.has_more) {
|
|
593
|
+
const full = { ...prop, [prop.type]: values, has_more: false };
|
|
594
|
+
return { ok: true, prop: full, incomplete: false };
|
|
595
|
+
}
|
|
596
|
+
if (typeof response.next_cursor !== 'string' || response.next_cursor === '') {
|
|
597
|
+
return {
|
|
598
|
+
ok: false,
|
|
599
|
+
kind: 'unparseable',
|
|
600
|
+
reason: `property "${name}": pagination cursor missing`,
|
|
601
|
+
};
|
|
602
|
+
}
|
|
603
|
+
if (seenCursors.has(response.next_cursor)) {
|
|
604
|
+
return {
|
|
605
|
+
ok: false,
|
|
606
|
+
kind: 'unparseable',
|
|
607
|
+
reason: `property "${name}": pagination cursor repeated`,
|
|
608
|
+
};
|
|
609
|
+
}
|
|
610
|
+
seenCursors.add(response.next_cursor);
|
|
611
|
+
cursor = response.next_cursor;
|
|
612
|
+
}
|
|
613
|
+
}
|
|
614
|
+
/** Completes every truncated property on a page (see `completeProperty`). */
|
|
615
|
+
async function completeProperties(page, resolved) {
|
|
616
|
+
const properties = {};
|
|
617
|
+
const incomplete = [];
|
|
618
|
+
for (const [name, prop] of Object.entries(page.properties)) {
|
|
619
|
+
const done = await completeProperty(page.id, name, prop, resolved);
|
|
620
|
+
if (!done.ok) {
|
|
621
|
+
return { ok: false, kind: done.kind, field: name, reason: done.reason };
|
|
622
|
+
}
|
|
623
|
+
if (done.incomplete) {
|
|
624
|
+
incomplete.push(name);
|
|
625
|
+
}
|
|
626
|
+
properties[name] = done.prop;
|
|
627
|
+
}
|
|
628
|
+
return { ok: true, page: { ...page, properties }, incomplete };
|
|
629
|
+
}
|
|
630
|
+
async function pageToCard(rawPage, resolved) {
|
|
631
|
+
const completed = await completeProperties(rawPage, resolved);
|
|
632
|
+
if (!completed.ok) {
|
|
633
|
+
if (completed.kind === 'unreachable') {
|
|
634
|
+
return { ok: false, kind: 'unreachable', reason: completed.reason };
|
|
635
|
+
}
|
|
636
|
+
return {
|
|
637
|
+
ok: false,
|
|
638
|
+
kind: 'unparseable',
|
|
639
|
+
problems: [{ field: completed.field, message: completed.reason }],
|
|
640
|
+
};
|
|
641
|
+
}
|
|
642
|
+
const page = completed.page;
|
|
432
643
|
const problems = [];
|
|
433
644
|
let state = '';
|
|
434
645
|
const stateOutcome = extractState(page, resolved);
|
|
@@ -455,9 +666,48 @@ async function pageToCard(page, resolved) {
|
|
|
455
666
|
problems.push({ field: outcome.field, message: outcome.reason });
|
|
456
667
|
}
|
|
457
668
|
}
|
|
669
|
+
// A configured title/requires/parent property that is missing or of the
|
|
670
|
+
// wrong type is a problem, never a silently absent field: Notion returns
|
|
671
|
+
// every schema property on every page, so absence is misconfiguration.
|
|
672
|
+
// Unconfigured (defaulted) properties keep their lenient behaviour.
|
|
673
|
+
const configured = [
|
|
674
|
+
[resolved.titleConfigured ? resolved.titleProperty : undefined, 'title'],
|
|
675
|
+
[resolved.requiresConfigured ? resolved.requiresProperty : undefined, 'relation'],
|
|
676
|
+
[resolved.parentProperty, 'relation'],
|
|
677
|
+
];
|
|
678
|
+
for (const [name, expected] of configured) {
|
|
679
|
+
if (name === undefined) {
|
|
680
|
+
continue;
|
|
681
|
+
}
|
|
682
|
+
const actual = page.properties[name];
|
|
683
|
+
if (actual === undefined) {
|
|
684
|
+
problems.push({
|
|
685
|
+
field: name,
|
|
686
|
+
message: `configured property "${name}" is missing from the page (expected type ${expected})`,
|
|
687
|
+
});
|
|
688
|
+
}
|
|
689
|
+
else if (actual.type !== expected) {
|
|
690
|
+
problems.push({
|
|
691
|
+
field: name,
|
|
692
|
+
message: `configured property "${name}" has type "${actual.type}", expected "${expected}"`,
|
|
693
|
+
});
|
|
694
|
+
}
|
|
695
|
+
}
|
|
458
696
|
if (problems.length > 0) {
|
|
459
697
|
return { ok: false, kind: 'unparseable', problems };
|
|
460
698
|
}
|
|
699
|
+
if (completed.incomplete.length > 0) {
|
|
700
|
+
unknownFields.propertiesIncomplete = completed.incomplete;
|
|
701
|
+
}
|
|
702
|
+
const titleProp = page.properties[resolved.titleProperty];
|
|
703
|
+
const title = titleProp?.type === 'title' ? plainTextOf(titleProp.title) : '';
|
|
704
|
+
const requiresProp = page.properties[resolved.requiresProperty];
|
|
705
|
+
const requires = requiresProp?.type === 'relation'
|
|
706
|
+
? (requiresProp.relation ?? []).map((ref) => ref.id)
|
|
707
|
+
: undefined;
|
|
708
|
+
const parentProp = resolved.parentProperty !== undefined ? page.properties[resolved.parentProperty] : undefined;
|
|
709
|
+
const parent = parentProp?.type === 'relation' ? parentProp.relation?.[0]?.id : undefined;
|
|
710
|
+
const derived = resolved.statusMap !== undefined ? normalizeStatus(state, resolved.statusMap) : undefined;
|
|
461
711
|
return {
|
|
462
712
|
ok: true,
|
|
463
713
|
card: {
|
|
@@ -467,9 +717,217 @@ async function pageToCard(page, resolved) {
|
|
|
467
717
|
source: `notion:${resolved.databaseId}`,
|
|
468
718
|
unknownFields,
|
|
469
719
|
properties,
|
|
720
|
+
...(title !== '' ? { title } : {}),
|
|
721
|
+
...(requires !== undefined ? { requires } : {}),
|
|
722
|
+
...(parent !== undefined ? { parent } : {}),
|
|
723
|
+
...(derived?.kind === 'mapped' ? { status: derived.status } : {}),
|
|
470
724
|
},
|
|
471
725
|
};
|
|
472
726
|
}
|
|
727
|
+
/**
|
|
728
|
+
* Every child block of `id`, following `has_more`/`next_cursor` until
|
|
729
|
+
* exhausted. Blocks are returned raw: `renderChildren` validates each one and
|
|
730
|
+
* counts what it cannot render. Any problem with the list itself (a failed
|
|
731
|
+
* page of results, a missing or repeated cursor, a malformed response) is
|
|
732
|
+
* `ok: false`, never a shorter list reported as complete.
|
|
733
|
+
*/
|
|
734
|
+
async function fetchChildren(id, resolved) {
|
|
735
|
+
const blocks = [];
|
|
736
|
+
const seenCursors = new Set();
|
|
737
|
+
let cursor;
|
|
738
|
+
for (;;) {
|
|
739
|
+
const cursorQuery = cursor === undefined ? '' : `&start_cursor=${encodeURIComponent(cursor)}`;
|
|
740
|
+
const outcome = await request(resolved, 'GET', `/blocks/${encodeURIComponent(id)}/children?page_size=100${cursorQuery}`);
|
|
741
|
+
if (outcome.kind === 'notFound') {
|
|
742
|
+
return { ok: false, kind: 'unreachable', reason: `content of block ${id} was not found` };
|
|
743
|
+
}
|
|
744
|
+
if (outcome.kind !== 'ok') {
|
|
745
|
+
return {
|
|
746
|
+
ok: false,
|
|
747
|
+
kind: 'unreachable',
|
|
748
|
+
reason: `content of block ${id} could not be read: ${outcome.reason}`,
|
|
749
|
+
};
|
|
750
|
+
}
|
|
751
|
+
const response = outcome.body;
|
|
752
|
+
if (!isRecord(response) ||
|
|
753
|
+
!Array.isArray(response.results) ||
|
|
754
|
+
typeof response.has_more !== 'boolean') {
|
|
755
|
+
return {
|
|
756
|
+
ok: false,
|
|
757
|
+
kind: 'unparseable',
|
|
758
|
+
reason: `content of block ${id}: Notion's response was not shaped like a block list`,
|
|
759
|
+
};
|
|
760
|
+
}
|
|
761
|
+
blocks.push(...response.results);
|
|
762
|
+
if (!response.has_more) {
|
|
763
|
+
return { ok: true, blocks };
|
|
764
|
+
}
|
|
765
|
+
if (typeof response.next_cursor !== 'string' || response.next_cursor === '') {
|
|
766
|
+
return {
|
|
767
|
+
ok: false,
|
|
768
|
+
kind: 'unparseable',
|
|
769
|
+
reason: `content of block ${id}: pagination cursor missing`,
|
|
770
|
+
};
|
|
771
|
+
}
|
|
772
|
+
if (seenCursors.has(response.next_cursor)) {
|
|
773
|
+
return {
|
|
774
|
+
ok: false,
|
|
775
|
+
kind: 'unparseable',
|
|
776
|
+
reason: `content of block ${id}: pagination cursor repeated`,
|
|
777
|
+
};
|
|
778
|
+
}
|
|
779
|
+
seenCursors.add(response.next_cursor);
|
|
780
|
+
cursor = response.next_cursor;
|
|
781
|
+
}
|
|
782
|
+
}
|
|
783
|
+
function renderRichText(fragments) {
|
|
784
|
+
return (fragments ?? [])
|
|
785
|
+
.map((fragment) => {
|
|
786
|
+
let text = fragment.plain_text ?? '';
|
|
787
|
+
if (text === '') {
|
|
788
|
+
return '';
|
|
789
|
+
}
|
|
790
|
+
if (fragment.annotations?.code) {
|
|
791
|
+
text = `\`${text}\``;
|
|
792
|
+
}
|
|
793
|
+
if (fragment.annotations?.bold) {
|
|
794
|
+
text = `**${text}**`;
|
|
795
|
+
}
|
|
796
|
+
if (fragment.annotations?.italic) {
|
|
797
|
+
text = `_${text}_`;
|
|
798
|
+
}
|
|
799
|
+
if (fragment.href) {
|
|
800
|
+
text = `[${text}](${fragment.href})`;
|
|
801
|
+
}
|
|
802
|
+
return text;
|
|
803
|
+
})
|
|
804
|
+
.join('');
|
|
805
|
+
}
|
|
806
|
+
/** Block types whose payload must carry a `rich_text` array to be rendered. */
|
|
807
|
+
const RICH_TEXT_TYPES = new Set([
|
|
808
|
+
'paragraph',
|
|
809
|
+
'heading_1',
|
|
810
|
+
'heading_2',
|
|
811
|
+
'heading_3',
|
|
812
|
+
'bulleted_list_item',
|
|
813
|
+
'numbered_list_item',
|
|
814
|
+
'to_do',
|
|
815
|
+
'quote',
|
|
816
|
+
'code',
|
|
817
|
+
]);
|
|
818
|
+
/**
|
|
819
|
+
* Renders the children of one block (or page) to markdown. A body is exactly
|
|
820
|
+
* one of three things, never silently partial:
|
|
821
|
+
* 1. complete;
|
|
822
|
+
* 2. marked incomplete: blocks that cannot be rendered (unsupported type,
|
|
823
|
+
* no type, missing payload or rich text) are counted in
|
|
824
|
+
* `state.skipped`, and depth truncation is counted in `state.truncated`
|
|
825
|
+
* with a marker line (both surface in `unknownFields.body`);
|
|
826
|
+
* 3. the whole `get` fails with a reason: `unreachable` for a failed block-list
|
|
827
|
+
* fetch, `unparseable` for a malformed or looping one (on any page of
|
|
828
|
+
* results, at any depth).
|
|
829
|
+
* Blocks at
|
|
830
|
+
* MAX_BODY_DEPTH that have children are not descended into: they are counted
|
|
831
|
+
* in `state.truncated` and followed by a visible marker line.
|
|
832
|
+
*/
|
|
833
|
+
async function renderChildren(id, depth, resolved, state) {
|
|
834
|
+
const fetched = await fetchChildren(id, resolved);
|
|
835
|
+
if (!fetched.ok) {
|
|
836
|
+
return fetched;
|
|
837
|
+
}
|
|
838
|
+
const parts = [];
|
|
839
|
+
let numbered = 0;
|
|
840
|
+
for (const raw of fetched.blocks) {
|
|
841
|
+
if (!isRecord(raw) || typeof raw.type !== 'string') {
|
|
842
|
+
state.skipped += 1;
|
|
843
|
+
continue;
|
|
844
|
+
}
|
|
845
|
+
const block = raw;
|
|
846
|
+
const rawPayload = block[block.type];
|
|
847
|
+
if (!isRecord(rawPayload) ||
|
|
848
|
+
(block.has_children === true && typeof block.id !== 'string') ||
|
|
849
|
+
(RICH_TEXT_TYPES.has(block.type) && !Array.isArray(rawPayload.rich_text))) {
|
|
850
|
+
state.skipped += 1;
|
|
851
|
+
continue;
|
|
852
|
+
}
|
|
853
|
+
numbered = block.type === 'numbered_list_item' ? numbered + 1 : 0;
|
|
854
|
+
const payload = rawPayload;
|
|
855
|
+
const richFragments = payload.rich_text;
|
|
856
|
+
const rich = renderRichText(richFragments);
|
|
857
|
+
let text;
|
|
858
|
+
switch (block.type) {
|
|
859
|
+
case 'paragraph':
|
|
860
|
+
text = rich;
|
|
861
|
+
break;
|
|
862
|
+
case 'heading_1':
|
|
863
|
+
text = `# ${rich}`;
|
|
864
|
+
break;
|
|
865
|
+
case 'heading_2':
|
|
866
|
+
text = `## ${rich}`;
|
|
867
|
+
break;
|
|
868
|
+
case 'heading_3':
|
|
869
|
+
text = `### ${rich}`;
|
|
870
|
+
break;
|
|
871
|
+
case 'bulleted_list_item':
|
|
872
|
+
text = `- ${rich}`;
|
|
873
|
+
break;
|
|
874
|
+
case 'numbered_list_item':
|
|
875
|
+
text = `${numbered}. ${rich}`;
|
|
876
|
+
break;
|
|
877
|
+
case 'to_do':
|
|
878
|
+
text = `- [${payload.checked === true ? 'x' : ' '}] ${rich}`;
|
|
879
|
+
break;
|
|
880
|
+
case 'quote':
|
|
881
|
+
text = rich
|
|
882
|
+
.split('\n')
|
|
883
|
+
.map((line) => `> ${line}`)
|
|
884
|
+
.join('\n');
|
|
885
|
+
break;
|
|
886
|
+
case 'code': {
|
|
887
|
+
const language = typeof payload.language === 'string' && payload.language !== 'plain text'
|
|
888
|
+
? payload.language
|
|
889
|
+
: '';
|
|
890
|
+
text = `\`\`\`${language}\n${plainTextOf(richFragments)}\n\`\`\``;
|
|
891
|
+
break;
|
|
892
|
+
}
|
|
893
|
+
case 'divider':
|
|
894
|
+
text = '---';
|
|
895
|
+
break;
|
|
896
|
+
default:
|
|
897
|
+
state.skipped += 1;
|
|
898
|
+
continue;
|
|
899
|
+
}
|
|
900
|
+
if (block.has_children === true && depth < MAX_BODY_DEPTH) {
|
|
901
|
+
const child = await renderChildren(block.id, depth + 1, resolved, state);
|
|
902
|
+
if (!child.ok) {
|
|
903
|
+
return child;
|
|
904
|
+
}
|
|
905
|
+
if (child.text !== '') {
|
|
906
|
+
const indented = child.text
|
|
907
|
+
.split('\n')
|
|
908
|
+
.map((line) => (line === '' ? line : ` ${line}`))
|
|
909
|
+
.join('\n');
|
|
910
|
+
text = `${text}\n${indented}`;
|
|
911
|
+
}
|
|
912
|
+
}
|
|
913
|
+
if (block.has_children === true && depth >= MAX_BODY_DEPTH) {
|
|
914
|
+
state.truncated += 1;
|
|
915
|
+
text = `${text}\n <!-- children omitted: depth limit -->`;
|
|
916
|
+
}
|
|
917
|
+
if (text === '') {
|
|
918
|
+
continue;
|
|
919
|
+
}
|
|
920
|
+
parts.push({ type: block.type, text });
|
|
921
|
+
}
|
|
922
|
+
let out = '';
|
|
923
|
+
parts.forEach((part, index) => {
|
|
924
|
+
if (index > 0) {
|
|
925
|
+
out += parts[index - 1]?.type === part.type && part.type !== 'paragraph' ? '\n' : '\n\n';
|
|
926
|
+
}
|
|
927
|
+
out += part.text;
|
|
928
|
+
});
|
|
929
|
+
return { ok: true, text: out };
|
|
930
|
+
}
|
|
473
931
|
async function performGet(id, resolved) {
|
|
474
932
|
const outcome = await request(resolved, 'GET', `/pages/${encodeURIComponent(id)}`);
|
|
475
933
|
if (outcome.kind !== 'ok') {
|
|
@@ -490,7 +948,41 @@ async function performGet(id, resolved) {
|
|
|
490
948
|
}
|
|
491
949
|
return { outcome: 'unparseable', id, problems: mapped.problems };
|
|
492
950
|
}
|
|
493
|
-
|
|
951
|
+
// The body costs extra calls, so only `get` pays for it (never `list`).
|
|
952
|
+
// A failure here is `unreachable` (fetch) or `unparseable` (malformed list): a card must not silently come back
|
|
953
|
+
// without the body it would otherwise have.
|
|
954
|
+
const state = { skipped: 0, truncated: 0 };
|
|
955
|
+
const body = await renderChildren(page.id, 0, resolved, state);
|
|
956
|
+
if (!body.ok) {
|
|
957
|
+
if (body.kind === 'unreachable') {
|
|
958
|
+
return { outcome: 'unreachable', reason: body.reason };
|
|
959
|
+
}
|
|
960
|
+
return {
|
|
961
|
+
outcome: 'unparseable',
|
|
962
|
+
id,
|
|
963
|
+
problems: [{ field: 'body', message: body.reason }],
|
|
964
|
+
};
|
|
965
|
+
}
|
|
966
|
+
return {
|
|
967
|
+
outcome: 'found',
|
|
968
|
+
card: {
|
|
969
|
+
...mapped.card,
|
|
970
|
+
...(body.text !== '' ? { body: body.text } : {}),
|
|
971
|
+
...(state.skipped > 0 || state.truncated > 0
|
|
972
|
+
? {
|
|
973
|
+
unknownFields: {
|
|
974
|
+
...mapped.card.unknownFields,
|
|
975
|
+
body: {
|
|
976
|
+
...(state.skipped > 0 ? { skippedBlocks: state.skipped } : {}),
|
|
977
|
+
...(state.truncated > 0
|
|
978
|
+
? { truncatedAtDepth: MAX_BODY_DEPTH, truncatedBlocks: state.truncated }
|
|
979
|
+
: {}),
|
|
980
|
+
},
|
|
981
|
+
},
|
|
982
|
+
}
|
|
983
|
+
: {}),
|
|
984
|
+
},
|
|
985
|
+
};
|
|
494
986
|
}
|
|
495
987
|
async function performList(filter, resolved) {
|
|
496
988
|
const cards = [];
|
|
@@ -652,6 +1144,16 @@ async function performCreateCard(card, resolved) {
|
|
|
652
1144
|
problems.push(`${name} (no such property on the database)`);
|
|
653
1145
|
continue;
|
|
654
1146
|
}
|
|
1147
|
+
// `Card.properties` is typed to carry any JSON-safe value (see
|
|
1148
|
+
// card.ts's `PropertyValue`), but Notion's own write mapping
|
|
1149
|
+
// (`propertyWritePayload`) can only ever write a flat string --
|
|
1150
|
+
// refused by name here, rather than silently stringified or passed
|
|
1151
|
+
// through to a function typed for a narrower input than this value
|
|
1152
|
+
// actually is.
|
|
1153
|
+
if (typeof value !== 'string') {
|
|
1154
|
+
problems.push(`${name} (value is not a string, and NotionBoard can only write flat string properties)`);
|
|
1155
|
+
continue;
|
|
1156
|
+
}
|
|
655
1157
|
const written = propertyWritePayload(def.type, value);
|
|
656
1158
|
if (!written.ok) {
|
|
657
1159
|
problems.push(`${name} (type "${def.type}" cannot be written safely)`);
|
|
@@ -659,13 +1161,22 @@ async function performCreateCard(card, resolved) {
|
|
|
659
1161
|
}
|
|
660
1162
|
mappable[name] = written.payload;
|
|
661
1163
|
}
|
|
1164
|
+
// Same discipline as the loop above, for the title property: it is
|
|
1165
|
+
// read a second time below (title is written from the same source
|
|
1166
|
+
// value, never re-entered into `mappable`), so its own non-string
|
|
1167
|
+
// check must happen here, before the early return, rather than at
|
|
1168
|
+
// the point it is actually used.
|
|
1169
|
+
const titlePropertyRaw = card.properties?.[resolved.titleProperty];
|
|
1170
|
+
if (titlePropertyRaw !== undefined && typeof titlePropertyRaw !== 'string') {
|
|
1171
|
+
problems.push(`${resolved.titleProperty} (value is not a string, and NotionBoard can only write a flat string title)`);
|
|
1172
|
+
}
|
|
662
1173
|
if (problems.length > 0) {
|
|
663
1174
|
return {
|
|
664
1175
|
outcome: 'refused',
|
|
665
1176
|
reason: `card cannot be created without silently dropping or misinterpreting data: ${problems.join(', ')}`,
|
|
666
1177
|
};
|
|
667
1178
|
}
|
|
668
|
-
const titleText =
|
|
1179
|
+
const titleText = typeof titlePropertyRaw === 'string' ? titlePropertyRaw : '';
|
|
669
1180
|
const properties = {
|
|
670
1181
|
...mappable,
|
|
671
1182
|
[resolved.titleProperty]: { title: titleText === '' ? [] : [{ text: { content: titleText } }] },
|
package/dist/status.d.ts
ADDED
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
export declare const STATUSES: readonly ["backlog", "ready", "in-progress", "in-review", "blocked", "done", "retracted"];
|
|
2
|
+
export type Status = (typeof STATUSES)[number];
|
|
3
|
+
export type StatusMap = {
|
|
4
|
+
readonly toStatus: Readonly<Record<string, Status>>;
|
|
5
|
+
readonly fromStatus: Readonly<Partial<Record<Status, string>>>;
|
|
6
|
+
};
|
|
7
|
+
export type NormalizeResult = {
|
|
8
|
+
readonly kind: 'mapped';
|
|
9
|
+
readonly status: Status;
|
|
10
|
+
} | {
|
|
11
|
+
readonly kind: 'unmapped';
|
|
12
|
+
readonly nativeState: string;
|
|
13
|
+
};
|
|
14
|
+
export type NativeStateResult = {
|
|
15
|
+
readonly kind: 'mapped';
|
|
16
|
+
readonly state: string;
|
|
17
|
+
} | {
|
|
18
|
+
readonly kind: 'unmapped';
|
|
19
|
+
readonly status: Status;
|
|
20
|
+
};
|
|
21
|
+
export declare function isStatus(value: unknown): value is Status;
|
|
22
|
+
/** Case-sensitive on the native name. Never throws, never guesses. */
|
|
23
|
+
export declare function normalizeStatus(nativeState: string, map: StatusMap): NormalizeResult;
|
|
24
|
+
export declare function nativeStateFor(status: Status, map: StatusMap): NativeStateResult;
|