@verevoir/aigency-work 0.3.0 → 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 CHANGED
@@ -5,6 +5,29 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [0.4.0] - 2026-11-18
9
+
10
+ ### Added
11
+
12
+ - Notion: `createNotionPageReader` (with `NotionPageReader`,
13
+ `NotionPageReaderConfig` and `NotionPageReadResult`) reads an ordinary
14
+ Notion page, not only a database row; `GetResult`'s `absent` gains an
15
+ optional `reason`, and `ListResult`'s `unreachable` an optional
16
+ `notFound`, so a not-found cause is named; `AnnotatePatch` accepts number
17
+ values, which Notion writes as numbers and flat-string boards store as
18
+ `String(n)`, refusing `NaN` and `Infinity` (#38).
19
+
20
+ ### Changed
21
+
22
+ - CI: the review job is granted `checks: read`, which the governance
23
+ review workflow needs (#35).
24
+ - CI: the governance review workflow is pinned by commit sha instead of
25
+ `@main` (#37).
26
+ - CI: the reviewer is repinned to governance 8f7df77, `@verevoir/review`
27
+ 0.3.5 (#39).
28
+ - BACKLOG.md only: cards for consolidating `@verevoir/workflows` into this
29
+ library and for Jira Cloud and Data Center; no code change (#40).
30
+
8
31
  ## [0.3.0] - 2026-11-05
9
32
 
10
33
  0.2.2 was never published to npm (the latest published version is 0.2.1), so
package/README.md CHANGED
@@ -13,6 +13,65 @@ Design lives in the meta repo, `verevoir/aigency-rebuild` — `design/architectu
13
13
  for why this boundary is here, `recon/constraints.md` for the defects it must
14
14
  not reproduce.
15
15
 
16
+ ## Reading ordinary Notion pages
17
+
18
+ `createNotionBoard(...).get(id)` only reads rows of the configured database: it needs the
19
+ status property. A backlog row's design page, or a row of another database (an ADRs
20
+ relation), has none, so use the page reader:
21
+
22
+ ```ts
23
+ import { createNotionPageReader } from '@verevoir/aigency-work';
24
+
25
+ const reader = createNotionPageReader({ getToken: async () => token });
26
+ const page = await reader.readPage(pageId);
27
+ if (page.ok) {
28
+ page.title; // the title property, whatever it is named
29
+ page.markdown; // content blocks as markdown (same renderer as get()); '' means no RENDERABLE content
30
+ page.truncated; // true if nested blocks below the depth limit were not fetched
31
+ page.skippedBlocks; // blocks that could not be rendered, counted not dropped
32
+ page.lastEditedTime;
33
+ } else {
34
+ page.kind; // 'not-found' | 'unreachable' | 'unparseable'
35
+ page.reason;
36
+ }
37
+ ```
38
+
39
+ It shares the board's request, retry and `sleep`/`fetch`/`maxAttempts`/`baseDelayMs` knobs and
40
+ API version (2022-06-28), so a 409/429 is retried with the same backoff. A failure is always
41
+ named, never an empty body. `markdown: ''` with `skippedBlocks: 0` is a page with no content;
42
+ `markdown: ''` with `skippedBlocks: N` is a page whose N blocks were all unrenderable.
43
+
44
+ A not-found answer on a read path (`not-found` here, `absent` with a `reason` from `get`,
45
+ `unreachable` from `list`, with `notFound: true` so it is distinguishable from an outage;
46
+ a non-404 `list` failure never sets `notFound`) usually means the
47
+ integration behind the token is not connected to that page or database (Notion: ••• →
48
+ Connections). The page paths (`get`, `readPage`) name the page id and give only that hint.
49
+ `list`, which is keyed by a database id, also warns that a data-source (collection) id is not a
50
+ database id under 2022-06-28 and is reported as not found. The write paths (`writeState`,
51
+ `annotate`, `createCard`) do not carry this hint: they report their own named `refused` reason.
52
+
53
+ ## Annotating Notion properties
54
+
55
+ `board.annotate(id, { properties })` patches properties other than the state. The Notion
56
+ board writes three property types and refuses the rest by name:
57
+
58
+ - `rich_text` and `url`: a string (`''` clears).
59
+ - `number`: a finite number, or a string that is wholly a finite decimal (`"12"`, `"-3.5"`,
60
+ `"0.0123"`, `"1e3"`). `NaN`, `Infinity`, `"12abc"`, `""`, blank and hex strings are
61
+ refused, naming the property and why. A bad value is never written as `0`. Clearing a
62
+ number with `null` is not supported.
63
+
64
+ The shared `AnnotatePatch` is `{ properties: Record<string, string | number> }`. Boards that
65
+ store flat string properties (in-memory, payload, store, ASF) store a number as `String(n)`
66
+ (a `NaN` or `Infinity` is refused by name on every board, never stored as `"NaN"`); Trello cannot annotate and refuses as before. Widening `properties` from string to
67
+ `string | number` means an out-of-tree `CardSink.annotate` implementation can now receive a
68
+ number and must handle it. The Notion board writes a real number to a `number` property.
69
+ A number given to any other Notion property type is refused, not stringified. A non-string given to a `rich_text` or
70
+ `url` property is refused as "needs a string value".
71
+
72
+ `createCard` uses the same write rules for `card.properties` (a number or a strict decimal
73
+ string for a `number` property); one bad value refuses the whole create and nothing is posted.
74
+
16
75
  ## Verify
17
76
 
18
77
  ```
package/dist/asf-board.js CHANGED
@@ -87,6 +87,7 @@
87
87
  // with no `If-Match` at all, which would silently overwrite the resource's
88
88
  // real properties with whatever this file guessed.
89
89
  import { z } from 'zod';
90
+ import { nonFiniteNumberReason, stringifyPatchProperties } from './board.js';
90
91
  // Before 0.2.2, a task whose `ticket` or `builtBy` was not a string, or
91
92
  // whose `requires` was neither a string nor an array of strings (for
92
93
  // example a number), failed validation: it was reported under
@@ -652,12 +653,16 @@ export function asfBoard(options) {
652
653
  currentRevision,
653
654
  };
654
655
  }
656
+ const nonFinite = nonFiniteNumberReason(patch.properties);
657
+ if (nonFinite !== undefined) {
658
+ return { outcome: 'refused', reason: nonFinite };
659
+ }
655
660
  // Merges into the RAW properties object -- every non-string property
656
661
  // ASF returned survives untouched unless `patch` itself replaces that
657
662
  // key. See the file header's "annotate's READ-MERGE-WRITE".
658
663
  const mergedProperties = {
659
664
  ...currentProperties,
660
- ...patch.properties,
665
+ ...stringifyPatchProperties(patch.properties),
661
666
  };
662
667
  const putResult = await authorizedFetch(resourceUrl, {
663
668
  method: 'PUT',
package/dist/board.d.ts CHANGED
@@ -96,6 +96,7 @@ export type GetResult = {
96
96
  readonly card: Card;
97
97
  } | {
98
98
  readonly outcome: 'absent';
99
+ readonly reason?: string;
99
100
  } | {
100
101
  readonly outcome: 'unreachable';
101
102
  readonly reason: string;
@@ -157,6 +158,7 @@ export type ListResult = {
157
158
  } | {
158
159
  readonly outcome: 'unreachable';
159
160
  readonly reason: string;
161
+ readonly notFound?: true;
160
162
  };
161
163
  /**
162
164
  * Options threading an optimistic-concurrency guard through a write.
@@ -182,14 +184,31 @@ export interface WriteOptions {
182
184
  readonly expectedRevision?: string;
183
185
  }
184
186
  /**
185
- * The patch `CardSink.annotate` applies: a flat string-to-string bag
187
+ * The patch `CardSink.annotate` applies: a flat bag of strings and numbers
186
188
  * merged into a card's own `properties`, never touching `state`. Used
187
189
  * for facts about a card's history that are not a column — a block or
188
190
  * retract reason, a recorded PR url.
189
191
  */
190
192
  export interface AnnotatePatch {
191
- readonly properties: Readonly<Record<string, string>>;
193
+ readonly properties: Readonly<Record<string, string | number>>;
192
194
  }
195
+ /**
196
+ * How a board that stores only flat string properties (in-memory, payload,
197
+ * store, ASF) takes a numeric patch value: `String(n)`, deterministically,
198
+ * so `1234.5` is stored as `"1234.5"`. A non-finite number is refused
199
+ * before this is called (see `nonFiniteNumberReason`), never stored as
200
+ * `"NaN"`. A board with typed number
201
+ * properties (Notion) writes the number itself instead; a board that
202
+ * cannot annotate at all (Trello) refuses before it ever looks.
203
+ */
204
+ export declare function stringifyPatchProperties(properties: Readonly<Record<string, string | number>>): Record<string, string>;
205
+ /**
206
+ * The reason a flat-string board refuses a patch, or `undefined` if it has
207
+ * none: a `NaN` or `Infinity` value would otherwise be stored as the string
208
+ * `"NaN"` or `"Infinity"`. Each such board answers `refused` with this text,
209
+ * matching what the Notion board does for the same patch.
210
+ */
211
+ export declare function nonFiniteNumberReason(properties: Readonly<Record<string, string | number>>): string | undefined;
193
212
  /**
194
213
  * The write half: changes a card's state, creates cards, and patches a
195
214
  * card's properties. Nothing else about a card is writable through it.
package/dist/board.js CHANGED
@@ -3,4 +3,33 @@
3
3
  // into a specific tracker's SDK — that is `sources`' job and a concrete
4
4
  // adapter's job, not this file's. This is the shape both halves share,
5
5
  // whatever backs them.
6
- export {};
6
+ /**
7
+ * How a board that stores only flat string properties (in-memory, payload,
8
+ * store, ASF) takes a numeric patch value: `String(n)`, deterministically,
9
+ * so `1234.5` is stored as `"1234.5"`. A non-finite number is refused
10
+ * before this is called (see `nonFiniteNumberReason`), never stored as
11
+ * `"NaN"`. A board with typed number
12
+ * properties (Notion) writes the number itself instead; a board that
13
+ * cannot annotate at all (Trello) refuses before it ever looks.
14
+ */
15
+ export function stringifyPatchProperties(properties) {
16
+ const out = {};
17
+ for (const [key, value] of Object.entries(properties)) {
18
+ out[key] = typeof value === 'number' ? String(value) : value;
19
+ }
20
+ return out;
21
+ }
22
+ /**
23
+ * The reason a flat-string board refuses a patch, or `undefined` if it has
24
+ * none: a `NaN` or `Infinity` value would otherwise be stored as the string
25
+ * `"NaN"` or `"Infinity"`. Each such board answers `refused` with this text,
26
+ * matching what the Notion board does for the same patch.
27
+ */
28
+ export function nonFiniteNumberReason(properties) {
29
+ for (const [key, value] of Object.entries(properties)) {
30
+ if (typeof value === 'number' && !Number.isFinite(value)) {
31
+ return `property "${key}" is ${String(value)}, not a finite number, so it is not written`;
32
+ }
33
+ }
34
+ return undefined;
35
+ }
@@ -3,6 +3,7 @@
3
3
  // something to move it on, and a tracker nobody has access to cannot be
4
4
  // that thing.
5
5
  import { normalizeStatus } from './status.js';
6
+ import { nonFiniteNumberReason, stringifyPatchProperties } from './board.js';
6
7
  export function createInMemoryBoard(initial = [], options = {}) {
7
8
  const statusMap = options.statusMap;
8
9
  const cards = new Map();
@@ -154,10 +155,14 @@ export function createInMemoryBoard(initial = [], options = {}) {
154
155
  if (mismatch !== undefined) {
155
156
  return mismatch;
156
157
  }
158
+ const nonFinite = nonFiniteNumberReason(patch.properties);
159
+ if (nonFinite !== undefined) {
160
+ return { outcome: 'refused', reason: nonFinite };
161
+ }
157
162
  bumpRevision(id);
158
163
  cards.set(id, {
159
164
  ...card,
160
- properties: { ...card.properties, ...patch.properties },
165
+ properties: { ...card.properties, ...stringifyPatchProperties(patch.properties) },
161
166
  });
162
167
  return { outcome: 'applied' };
163
168
  },
package/dist/index.d.ts CHANGED
@@ -7,8 +7,8 @@ export { createInMemoryBoard } from './in-memory-board.js';
7
7
  export type { InMemoryBoard, InMemoryBoardOptions } from './in-memory-board.js';
8
8
  export { createPayloadBoard } from './payload-board.js';
9
9
  export type { PayloadBoard } from './payload-board.js';
10
- export { createNotionBoard, NOTION_VERSION, NOTION_DEFAULT_STATUS_MAP } from './notion-board.js';
11
- export type { NotionBoard, NotionBoardConfig, NotionFetch, NotionFetchInit, NotionFetchResponse, } from './notion-board.js';
10
+ export { createNotionBoard, createNotionPageReader, NOTION_VERSION, NOTION_DEFAULT_STATUS_MAP, } from './notion-board.js';
11
+ export type { NotionPageReader, NotionPageReaderConfig, NotionPageReadResult, NotionBoard, NotionBoardConfig, NotionFetch, NotionFetchInit, NotionFetchResponse, } from './notion-board.js';
12
12
  export { createTrelloBoard } from './trello-board.js';
13
13
  export type { TrelloBoard, TrelloBoardConfig, TrelloFetch, TrelloFetchInit, TrelloFetchResponse, } from './trello-board.js';
14
14
  export { createBacklogBoard, BACKLOG_STATUS_MAP } from './backlog-board.js';
package/dist/index.js CHANGED
@@ -6,7 +6,7 @@ export { parseCard } from './card.js';
6
6
  export { normalizeStatus, nativeStateFor } from './status.js';
7
7
  export { createInMemoryBoard } from './in-memory-board.js';
8
8
  export { createPayloadBoard } from './payload-board.js';
9
- export { createNotionBoard, NOTION_VERSION, NOTION_DEFAULT_STATUS_MAP } from './notion-board.js';
9
+ export { createNotionBoard, createNotionPageReader, NOTION_VERSION, NOTION_DEFAULT_STATUS_MAP, } from './notion-board.js';
10
10
  export { createTrelloBoard } from './trello-board.js';
11
11
  export { createBacklogBoard, BACKLOG_STATUS_MAP } from './backlog-board.js';
12
12
  export { asfBoard } from './asf-board.js';
@@ -78,3 +78,52 @@ export interface NotionBoard extends CardSource, CardSink {
78
78
  */
79
79
  export declare function notionPropertyPath(pageId: string, propertyId: string): string;
80
80
  export declare function createNotionBoard(config: NotionBoardConfig): NotionBoard;
81
+ /**
82
+ * The outcome of `readPage`. Never a silent empty body: a page that cannot be
83
+ * read is a named failure. `markdown: ''` means the page has no RENDERABLE
84
+ * content: either it has no blocks, or every block was one the renderer skips.
85
+ * `skippedBlocks` says how many were skipped, so an all-skipped page
86
+ * (`markdown: ''`, `skippedBlocks: N`) is told apart from a genuinely empty one
87
+ * (`markdown: ''`, `skippedBlocks: 0`).
88
+ *
89
+ * - `not-found`: Notion answered 404 (the reason names the likely cause: the
90
+ * integration is not connected to the page);
91
+ * - `unreachable`: a fetch failed, credentials were rejected, or retries ran
92
+ * out (the page or a block list could not be read);
93
+ * - `unparseable`: Notion answered, but not with a page / block list this
94
+ * reader understands.
95
+ */
96
+ export type NotionPageReadResult = {
97
+ readonly ok: true;
98
+ /** The page's title property, whatever that property is named. */
99
+ readonly title: string;
100
+ readonly markdown: string;
101
+ /** True when nested blocks below the depth limit were not fetched (a marker line is in `markdown`). */
102
+ readonly truncated: boolean;
103
+ /** Blocks that could not be rendered at all; each is counted, never dropped silently. */
104
+ readonly skippedBlocks: number;
105
+ readonly lastEditedTime: string;
106
+ } | {
107
+ readonly ok: false;
108
+ readonly kind: 'not-found' | 'unreachable' | 'unparseable';
109
+ readonly reason: string;
110
+ };
111
+ /** What a page reader needs: no database id, no status/title mapping. */
112
+ export type NotionPageReaderConfig = Pick<NotionBoardConfig, 'getToken' | 'fetch' | 'sleep' | 'maxAttempts' | 'baseDelayMs'>;
113
+ export interface NotionPageReader {
114
+ /**
115
+ * Reads any Notion page the integration can see -- a plain page, or a row
116
+ * of ANY database (such as an ADRs database) -- and renders its content
117
+ * blocks to markdown with the same renderer `NotionBoard.get` uses. It
118
+ * ignores the board's status property entirely.
119
+ */
120
+ readPage(pageId: string): Promise<NotionPageReadResult>;
121
+ }
122
+ /**
123
+ * A reader for ordinary Notion pages, sharing the board's request, retry,
124
+ * sleep and block-rendering code (and its API version). Use it for the pages
125
+ * a backlog row points at -- a design page URL, the rows of an ADRs relation --
126
+ * which `NotionBoard.get` cannot read because they are not rows of the
127
+ * configured database.
128
+ */
129
+ export declare function createNotionPageReader(config: NotionPageReaderConfig): NotionPageReader;
@@ -62,6 +62,23 @@ export const NOTION_DEFAULT_STATUS_MAP = {
62
62
  * `unknownFields.body.truncatedAtDepth` / `truncatedBlocks` on the card.
63
63
  */
64
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.';
65
82
  /** The API version this board was built and tested against. */
66
83
  export const NOTION_VERSION = '2022-06-28';
67
84
  const DEFAULT_MAX_ATTEMPTS = 4;
@@ -90,8 +107,8 @@ const defaultSleep = (ms) => new Promise((resolve) => {
90
107
  });
91
108
  function resolveConfig(config) {
92
109
  return {
110
+ ...resolveTransport(config),
93
111
  databaseId: config.databaseId,
94
- getToken: config.getToken,
95
112
  statusProperty: config.statusProperty ?? 'Status',
96
113
  titleProperty: config.titleProperty ?? 'Name',
97
114
  titleConfigured: config.titleProperty !== undefined,
@@ -99,6 +116,12 @@ function resolveConfig(config) {
99
116
  requiresConfigured: config.requiresProperty !== undefined,
100
117
  parentProperty: config.parentProperty,
101
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,
102
125
  fetch: config.fetch ?? defaultFetch,
103
126
  sleep: config.sleep ?? defaultSleep,
104
127
  // Clamped to at least 1: a configured 0 (or negative) used to fall
@@ -256,15 +279,22 @@ async function request(resolved, method, path, body) {
256
279
  * rate-limiting applies to a plain GET as much as to a write, so this IS
257
280
  * reachable from here — and `unreachable`) falls back to `unreachable`.
258
281
  */
259
- function toGetFailure(outcome) {
282
+ function toGetFailure(id, outcome) {
260
283
  if (outcome.kind === 'notFound') {
261
- return { outcome: 'absent' };
284
+ return {
285
+ outcome: 'absent',
286
+ reason: `Notion returned not found for page ${id}. ${CONNECTION_HINT}`,
287
+ };
262
288
  }
263
289
  return { outcome: 'unreachable', reason: outcome.reason };
264
290
  }
265
291
  function toListFailure(outcome) {
266
292
  if (outcome.kind === 'notFound') {
267
- return { outcome: 'unreachable', reason: 'Notion reported no such database' };
293
+ return {
294
+ outcome: 'unreachable',
295
+ reason: `Notion reported no such database. ${CONNECTION_HINT} ${DATABASE_ID_HINT}`,
296
+ notFound: true,
297
+ };
268
298
  }
269
299
  return { outcome: 'unreachable', reason: outcome.reason };
270
300
  }
@@ -486,7 +516,10 @@ function extractState(page, resolved) {
486
516
  if (prop === undefined) {
487
517
  return {
488
518
  ok: false,
489
- 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().',
490
523
  };
491
524
  }
492
525
  if (prop.type === 'select') {
@@ -931,7 +964,7 @@ async function renderChildren(id, depth, resolved, state) {
931
964
  async function performGet(id, resolved) {
932
965
  const outcome = await request(resolved, 'GET', `/pages/${encodeURIComponent(id)}`);
933
966
  if (outcome.kind !== 'ok') {
934
- return toGetFailure(outcome);
967
+ return toGetFailure(id, outcome);
935
968
  }
936
969
  const page = asNotionPage(outcome.body);
937
970
  if (page === undefined) {
@@ -1065,24 +1098,66 @@ async function performWriteState(id, state, resolved, options) {
1065
1098
  });
1066
1099
  return toWriteResult(patchOutcome, `no card with id ${id}`);
1067
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
+ }
1068
1119
  /**
1069
1120
  * The per-type write mapping `annotate` and `createCard` both apply to a
1070
- * flat string value: only `rich_text` and `url` can be written back
1071
- * safely without more information than a flat string carries (a `select`
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`
1072
1123
  * needs to know whether the option already exists, `multi_select` needs
1073
- * a list, `number`/`date` need a parse that can fail in ways a plain
1074
- * string write cannot surface). Anything else is `ok: false` — the caller
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
1075
1127
  * decides what that means (refuse the annotate, or refuse the whole
1076
1128
  * create) rather than this function silently doing nothing.
1077
1129
  */
1078
- function propertyWritePayload(type, value) {
1079
- if (type === 'rich_text') {
1080
- return { ok: true, payload: { rich_text: value === '' ? [] : [{ text: { content: value } }] } };
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 } };
1081
1141
  }
1082
- 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
+ }
1083
1155
  return { ok: true, payload: { url: value === '' ? null : value } };
1084
1156
  }
1085
- return { ok: false };
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
+ };
1086
1161
  }
1087
1162
  /**
1088
1163
  * Creates a page in the configured database. Notion has nothing resembling
@@ -1145,18 +1220,13 @@ async function performCreateCard(card, resolved) {
1145
1220
  continue;
1146
1221
  }
1147
1222
  // `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
- }
1157
- const written = propertyWritePayload(def.type, value);
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);
1158
1228
  if (!written.ok) {
1159
- problems.push(`${name} (type "${def.type}" cannot be written safely)`);
1229
+ problems.push(written.reason);
1160
1230
  continue;
1161
1231
  }
1162
1232
  mappable[name] = written.payload;
@@ -1212,12 +1282,15 @@ async function performAnnotate(id, patch, resolved, options) {
1212
1282
  reason: `property "${key}" does not exist on card ${id}, so it cannot be annotated`,
1213
1283
  };
1214
1284
  }
1215
- const written = propertyWritePayload(existing.type, value);
1285
+ const written = propertyWritePayload(key, existing.type, value);
1216
1286
  if (!written.ok) {
1217
- return {
1218
- outcome: 'refused',
1219
- reason: `property "${key}" has type "${existing.type}", which annotate cannot write safely — only rich_text and url properties are supported`,
1220
- };
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;
1221
1294
  }
1222
1295
  const currentValue = existing.type === 'rich_text' ? plainTextOf(existing.rich_text) : (existing.url ?? '');
1223
1296
  if (currentValue !== value) {
@@ -1242,3 +1315,60 @@ export function createNotionBoard(config) {
1242
1315
  annotate: (id, patch, options) => performAnnotate(id, patch, resolved, options),
1243
1316
  };
1244
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
+ }
@@ -47,6 +47,7 @@
47
47
  // fake, never-moving revision through regardless of what a stored
48
48
  // payload happens to contain.
49
49
  import { parseCardPayload, renderCardPayload } from './payload.js';
50
+ import { nonFiniteNumberReason, stringifyPatchProperties } from './board.js';
50
51
  function formatProblems(problems) {
51
52
  return problems.map((problem) => `${problem.field}: ${problem.message}`).join('; ');
52
53
  }
@@ -202,9 +203,13 @@ export function createPayloadBoard(initial = []) {
202
203
  reason: `card ${id}'s properties are a tracker-shaped object, not a flat string bag; annotate would overwrite them`,
203
204
  };
204
205
  }
206
+ const nonFinite = nonFiniteNumberReason(patch.properties);
207
+ if (nonFinite !== undefined) {
208
+ return { outcome: 'refused', reason: nonFinite };
209
+ }
205
210
  const updated = {
206
211
  ...stripRevision(parsed.card),
207
- properties: { ...parsed.card.properties, ...patch.properties },
212
+ properties: { ...parsed.card.properties, ...stringifyPatchProperties(patch.properties) },
208
213
  };
209
214
  payloads.set(id, renderCardPayload(updated));
210
215
  return { outcome: 'applied' };
@@ -118,6 +118,7 @@
118
118
  // revision changing with it, and no separate write that can fail on its
119
119
  // own. `get`/`list` need no special handling: the revision is already
120
120
  // part of the value they read.
121
+ import { nonFiniteNumberReason, stringifyPatchProperties } from './board.js';
121
122
  /**
122
123
  * The reserved key under which this board keeps the list of every card
123
124
  * id it has created — an ordinary value in the same store, not a
@@ -399,9 +400,13 @@ export function createStoreBoard(store) {
399
400
  ...(current.revision !== undefined ? { currentRevision: current.revision } : {}),
400
401
  };
401
402
  }
403
+ const nonFinite = nonFiniteNumberReason(patch.properties);
404
+ if (nonFinite !== undefined) {
405
+ return { outcome: 'refused', reason: nonFinite };
406
+ }
402
407
  const updated = {
403
408
  ...current,
404
- properties: { ...current.properties, ...patch.properties },
409
+ properties: { ...current.properties, ...stringifyPatchProperties(patch.properties) },
405
410
  revision: nextRevision(current.revision),
406
411
  };
407
412
  const replaced = await store.replace(cardKey(id), updated, current);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@verevoir/aigency-work",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",