@verevoir/aigency-work 0.2.1 → 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.
@@ -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;
@@ -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
- const text = plainTextOf(ticket.rich_text);
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
- async function pageToCard(page, resolved) {
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
- return { outcome: 'found', card: mapped.card };
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 = card.properties?.[resolved.titleProperty] ?? '';
1179
+ const titleText = typeof titlePropertyRaw === 'string' ? titlePropertyRaw : '';
669
1180
  const properties = {
670
1181
  ...mappable,
671
1182
  [resolved.titleProperty]: { title: titleText === '' ? [] : [{ text: { content: titleText } }] },
@@ -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;