@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 +23 -0
- package/README.md +59 -0
- package/dist/asf-board.js +6 -1
- package/dist/board.d.ts +21 -2
- package/dist/board.js +30 -1
- package/dist/in-memory-board.js +6 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/notion-board.d.ts +49 -0
- package/dist/notion-board.js +161 -31
- package/dist/payload-board.js +6 -1
- package/dist/store-board.js +6 -1
- package/package.json +1 -1
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
|
|
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
|
-
|
|
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
|
+
}
|
package/dist/in-memory-board.js
CHANGED
|
@@ -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';
|
package/dist/notion-board.d.ts
CHANGED
|
@@ -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;
|
package/dist/notion-board.js
CHANGED
|
@@ -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 {
|
|
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 {
|
|
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
|
|
1071
|
-
* safely without more information than a flat
|
|
1121
|
+
* flat value: only `rich_text`, `url` and `number` can be written back
|
|
1122
|
+
* safely without more information than a flat value carries (a `select`
|
|
1072
1123
|
* needs to know whether the option already exists, `multi_select` needs
|
|
1073
|
-
* a list, `
|
|
1074
|
-
*
|
|
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 === '
|
|
1080
|
-
|
|
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 {
|
|
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`)
|
|
1149
|
-
//
|
|
1150
|
-
//
|
|
1151
|
-
//
|
|
1152
|
-
|
|
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(
|
|
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
|
-
|
|
1219
|
-
|
|
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
|
+
}
|
package/dist/payload-board.js
CHANGED
|
@@ -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' };
|
package/dist/store-board.js
CHANGED
|
@@ -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);
|