@verevoir/aigency-work 0.2.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,7 +2,10 @@
2
2
  // stand in for a real tracker in a demo or a test. A card moving needs
3
3
  // something to move it on, and a tracker nobody has access to cannot be
4
4
  // that thing.
5
- export function createInMemoryBoard(initial = []) {
5
+ import { normalizeStatus } from './status.js';
6
+ import { nonFiniteNumberReason, stringifyPatchProperties } from './board.js';
7
+ export function createInMemoryBoard(initial = [], options = {}) {
8
+ const statusMap = options.statusMap;
6
9
  const cards = new Map();
7
10
  const revisions = new Map();
8
11
  for (const card of initial) {
@@ -25,7 +28,20 @@ export function createInMemoryBoard(initial = []) {
25
28
  delete copy.revision;
26
29
  return copy;
27
30
  }
28
- function withRevision(card, id) {
31
+ // Status is derived on the way out, never stored independently, so it
32
+ // cannot contradict `state`. Any supplied status is dropped; with no map
33
+ // there is nothing to derive it from, so it stays absent.
34
+ function withDerivedStatus(card) {
35
+ const rest = { ...card };
36
+ delete rest.status;
37
+ if (statusMap === undefined) {
38
+ return rest;
39
+ }
40
+ const derived = normalizeStatus(card.state, statusMap);
41
+ return derived.kind === 'mapped' ? { ...rest, status: derived.status } : rest;
42
+ }
43
+ function withRevision(stored, id) {
44
+ const card = withDerivedStatus(stored);
29
45
  const revision = revisions.get(id);
30
46
  return revision === undefined ? card : { ...card, revision: String(revision) };
31
47
  }
@@ -139,10 +155,14 @@ export function createInMemoryBoard(initial = []) {
139
155
  if (mismatch !== undefined) {
140
156
  return mismatch;
141
157
  }
158
+ const nonFinite = nonFiniteNumberReason(patch.properties);
159
+ if (nonFinite !== undefined) {
160
+ return { outcome: 'refused', reason: nonFinite };
161
+ }
142
162
  bumpRevision(id);
143
163
  cards.set(id, {
144
164
  ...card,
145
- properties: { ...card.properties, ...patch.properties },
165
+ properties: { ...card.properties, ...stringifyPatchProperties(patch.properties) },
146
166
  });
147
167
  return { outcome: 'applied' };
148
168
  },
package/dist/index.d.ts CHANGED
@@ -1,12 +1,18 @@
1
1
  export { parseCard } from './card.js';
2
2
  export type { Card, Problem, ParseResult, State } from './card.js';
3
+ export { normalizeStatus, nativeStateFor } from './status.js';
4
+ export type { Status, StatusMap, NormalizeResult, NativeStateResult } from './status.js';
3
5
  export type { CardSource, CardSink, GetResult, ListResult, WriteResult, UnparseableRecord, AnnotatePatch, WriteOptions, CardClaimer, ClaimResult, NominateClaimResult, CompletionOptions, CompletionResult, RunOutcome, } from './board.js';
4
6
  export { createInMemoryBoard } from './in-memory-board.js';
5
- export type { InMemoryBoard } from './in-memory-board.js';
7
+ export type { InMemoryBoard, InMemoryBoardOptions } from './in-memory-board.js';
6
8
  export { createPayloadBoard } from './payload-board.js';
7
9
  export type { PayloadBoard } from './payload-board.js';
8
- export { createNotionBoard, NOTION_VERSION } from './notion-board.js';
9
- 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
+ export { createTrelloBoard } from './trello-board.js';
13
+ export type { TrelloBoard, TrelloBoardConfig, TrelloFetch, TrelloFetchInit, TrelloFetchResponse, } from './trello-board.js';
14
+ export { createBacklogBoard, BACKLOG_STATUS_MAP } from './backlog-board.js';
15
+ export type { BacklogBoardOptions } from './backlog-board.js';
10
16
  export { asfBoard } from './asf-board.js';
11
17
  export type { AsfBoardOptions, AsfFetch, AsfFetchInit, AsfFetchResponse } from './asf-board.js';
12
18
  export { parseCardPayload, renderCardPayload } from './payload.js';
package/dist/index.js CHANGED
@@ -3,9 +3,12 @@
3
3
  // typecheck, lint and test — is gone: this project's first real export has
4
4
  // landed, which was the condition it was written to be removed on.
5
5
  export { parseCard } from './card.js';
6
+ export { normalizeStatus, nativeStateFor } from './status.js';
6
7
  export { createInMemoryBoard } from './in-memory-board.js';
7
8
  export { createPayloadBoard } from './payload-board.js';
8
- export { createNotionBoard, NOTION_VERSION } from './notion-board.js';
9
+ export { createNotionBoard, createNotionPageReader, NOTION_VERSION, NOTION_DEFAULT_STATUS_MAP, } from './notion-board.js';
10
+ export { createTrelloBoard } from './trello-board.js';
11
+ export { createBacklogBoard, BACKLOG_STATUS_MAP } from './backlog-board.js';
9
12
  export { asfBoard } from './asf-board.js';
10
13
  export { parseCardPayload, renderCardPayload } from './payload.js';
11
14
  export { moveCard } from './move-card.js';
@@ -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,61 @@ 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;
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;