@n-dx/core 0.1.0

package/packages/rex/dist/store/notion-client.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Thin abstraction over the Notion API for rex sync.
+ *
+ * Consumers inject a concrete implementation (live or mock) into the
+ * NotionStore adapter.  This keeps HTTP concerns out of the store layer
+ * and makes the adapter fully testable without network calls.
+ */
+export interface NotionAdapterConfig {
+    /** Notion integration token (secret_xxx or ntn_xxx). */
+    token: string;
+    /** ID of the Notion database that holds the PRD. */
+    databaseId: string;
+}
+export interface NotionClient {
+    /** Retrieve database metadata (properties, schema). */
+    getDatabase(databaseId: string): Promise<any>;
+    /** Query all pages in a database (handles pagination internally). */
+    queryDatabase(databaseId: string): Promise<any[]>;
+    /** Retrieve a single page by ID. */
+    getPage(pageId: string): Promise<any>;
+    /** Create a page with properties, parent, and optional child blocks. */
+    createPage(params: {
+        parent: {
+            database_id?: string;
+            page_id?: string;
+        };
+        properties: Record<string, any>;
+        children?: any[];
+    }): Promise<any>;
+    /** Update an existing page's properties. */
+    updatePage(pageId: string, properties: Record<string, any>): Promise<any>;
+    /** Archive (soft-delete) a page. */
+    archivePage(pageId: string): Promise<void>;
+    /** Retrieve child blocks of a page (for description / acceptance criteria). */
+    getBlockChildren(pageId: string): Promise<any[]>;
+}
+export declare class LiveNotionClient implements NotionClient {
+    private token;
+    constructor(token: string);
+    private headers;
+    private request;
+    getDatabase(databaseId: string): Promise<any>;
+    queryDatabase(databaseId: string): Promise<any[]>;
+    getPage(pageId: string): Promise<any>;
+    createPage(params: {
+        parent: {
+            database_id?: string;
+            page_id?: string;
+        };
+        properties: Record<string, any>;
+        children?: any[];
+    }): Promise<any>;
+    updatePage(pageId: string, properties: Record<string, any>): Promise<any>;
+    archivePage(pageId: string): Promise<void>;
+    getBlockChildren(pageId: string): Promise<any[]>;
+}

package/packages/rex/dist/store/notion-client.js

@@ -0,0 +1,82 @@
+/**
+ * Thin abstraction over the Notion API for rex sync.
+ *
+ * Consumers inject a concrete implementation (live or mock) into the
+ * NotionStore adapter.  This keeps HTTP concerns out of the store layer
+ * and makes the adapter fully testable without network calls.
+ */
+// ---------------------------------------------------------------------------
+// Live implementation — calls the Notion REST API directly
+// ---------------------------------------------------------------------------
+const NOTION_API = "https://api.notion.com/v1";
+const NOTION_VERSION = "2022-06-28";
+export class LiveNotionClient {
+    token;
+    constructor(token) {
+        this.token = token;
+    }
+    headers() {
+        return {
+            Authorization: `Bearer ${this.token}`,
+            "Notion-Version": NOTION_VERSION,
+            "Content-Type": "application/json",
+        };
+    }
+    async request(method, path, body) {
+        const url = `${NOTION_API}${path}`;
+        const res = await fetch(url, {
+            method,
+            headers: this.headers(),
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Notion API ${method} ${path} failed (${res.status}): ${text}`);
+        }
+        // 204 No Content (e.g. archive) returns no body
+        if (res.status === 204)
+            return undefined;
+        return res.json();
+    }
+    async getDatabase(databaseId) {
+        return this.request("GET", `/databases/${databaseId}`);
+    }
+    async queryDatabase(databaseId) {
+        const pages = [];
+        let cursor;
+        do {
+            const body = {};
+            if (cursor)
+                body.start_cursor = cursor;
+            const res = await this.request("POST", `/databases/${databaseId}/query`, body);
+            pages.push(...(res.results ?? []));
+            cursor = res.has_more ? res.next_cursor : undefined;
+        } while (cursor);
+        return pages;
+    }
+    async getPage(pageId) {
+        return this.request("GET", `/pages/${pageId}`);
+    }
+    async createPage(params) {
+        return this.request("POST", "/pages", params);
+    }
+    async updatePage(pageId, properties) {
+        return this.request("PATCH", `/pages/${pageId}`, { properties });
+    }
+    async archivePage(pageId) {
+        await this.request("PATCH", `/pages/${pageId}`, { archived: true });
+    }
+    async getBlockChildren(pageId) {
+        const blocks = [];
+        let cursor;
+        do {
+            const path = `/blocks/${pageId}/children${cursor ? `?start_cursor=${cursor}` : ""}`;
+            const res = await this.request("GET", path);
+            blocks.push(...(res.results ?? []));
+            cursor = res.has_more ? res.next_cursor : undefined;
+        } while (cursor);
+        return blocks;
+    }
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+//# sourceMappingURL=notion-client.js.map

package/packages/rex/dist/store/notion-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-client.js","sourceRoot":"","sources":["../../src/store/notion-client.ts"],"names":[],"mappings":"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"}

package/packages/rex/dist/store/notion-map.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Maps PRD hierarchy to Notion database structure.
+ *
+ * Notion model:
+ * - Epics are top-level pages in the database
+ * - Features, tasks, and subtasks are sub-pages nested under their parents
+ * - Status uses Notion's **native status property type** (not a select)
+ *   with three built-in groups: To-do, In progress, Complete
+ * - Priority uses a **select** property (Notion has no native priority type)
+ * - Other fields use title, rich_text, multi_select as appropriate
+ *
+ * This module handles bidirectional conversion between PRDItem trees
+ * and Notion's flat page + parent reference model.
+ */
+import type { ItemLevel, ItemStatus, PRDItem, PRDDocument, Priority } from "../schema/index.js";
+export interface NotionRichText {
+    text: {
+        content: string;
+    };
+}
+export interface NotionPageProperties {
+    Name: {
+        title: NotionRichText[];
+    };
+    /** Notion native status property (not a select). */
+    Status: {
+        status: {
+            name: string;
+        };
+    };
+    Level: {
+        select: {
+            name: string;
+        };
+    };
+    "PRD ID": {
+        rich_text: NotionRichText[];
+    };
+    Description?: {
+        rich_text: NotionRichText[];
+    };
+    /** Select property — Notion has no native priority type. */
+    Priority?: {
+        select: {
+            name: string;
+        };
+    };
+    Tags?: {
+        multi_select: Array<{
+            name: string;
+        }>;
+    };
+    Source?: {
+        rich_text: NotionRichText[];
+    };
+    "Blocked By"?: {
+        rich_text: NotionRichText[];
+    };
+    /** ISO 8601 timestamp of when work started. Stored as rich_text. */
+    "Started At"?: {
+        rich_text: NotionRichText[];
+    };
+    /** ISO 8601 timestamp of when item was completed. Stored as rich_text. */
+    "Completed At"?: {
+        rich_text: NotionRichText[];
+    };
+}
+/**
+ * Notion's three built-in status groups. Every Status property has exactly
+ * these three groups; options are assigned to one of them.
+ */
+export type NotionStatusGroup = "To-do" | "In progress" | "Complete";
+export interface NotionStatusOption {
+    name: string;
+    color: string;
+    group: NotionStatusGroup;
+}
+/**
+ * Map from each PRD ItemStatus to its Notion status option name and group.
+ * The group assignment tells Notion which column/category the status belongs to,
+ * which is the key differentiator of the native status type vs a plain select.
+ */
+export declare const STATUS_OPTIONS: Record<ItemStatus, NotionStatusOption>;
+/**
+ * Priority options for the select property. Title-cased for Notion display.
+ */
+export interface NotionSelectOption {
+    name: string;
+    color: string;
+}
+export declare const PRIORITY_OPTIONS: Record<Priority, NotionSelectOption>;
+export interface NotionPropertySchema {
+    type: "title" | "status" | "select" | "multi_select" | "rich_text";
+    /** For status/select types: the expected options. */
+    options?: Array<{
+        name: string;
+        color: string;
+    }>;
+    /** For status type: which group each option belongs to. */
+    groups?: Array<{
+        name: NotionStatusGroup;
+        color: string;
+        option_names: string[];
+    }>;
+}
+/**
+ * Expected database property schema for a rex-managed Notion database.
+ * Use this to validate that a database is correctly configured or to
+ * document what manual setup is required (since the Status property type
+ * cannot be created via the Notion API).
+ */
+export declare const DATABASE_SCHEMA: Record<string, NotionPropertySchema>;
+export interface NotionBlock {
+    object: "block";
+    type: string;
+    [key: string]: unknown;
+}
+export interface NotionParent {
+    database_id?: string;
+    page_id?: string;
+}
+export interface NotionPageDescriptor {
+    item: PRDItem;
+    parent: NotionParent;
+    parentItemId?: string;
+    properties: NotionPageProperties;
+    children?: NotionBlock[];
+}
+export interface LevelConfig {
+    parentLevel: ItemLevel | null;
+    statusMap: Record<ItemStatus, string>;
+}
+export declare const NOTION_LEVEL_CONFIG: Record<ItemLevel, LevelConfig>;
+/**
+ * Convert a single PRDItem into Notion page properties + body blocks.
+ * Does not set the `parent` field — use `resolveParentPage` for that.
+ */
+export declare function mapItemToNotion(item: PRDItem): {
+    properties: NotionPageProperties;
+    children?: NotionBlock[];
+};
+/**
+ * Convert a Notion page object into a PRDItem.
+ * Expects the page to have the properties defined by `NotionPageProperties`.
+ *
+ * For the native Status property, reads `status.name` (and optionally the
+ * status group from the database schema) to resolve to a PRD ItemStatus.
+ * Custom status options (e.g. "Blocked") are resolved via their group
+ * when `statusGroupMap` is provided.
+ *
+ * @param notionPage      Notion page object with properties and optional children.
+ * @param statusGroupMap  Optional map of status option name → group name, from
+ *                        the database schema. Enables group-based fallback for
+ *                        custom status options.
+ */
+export declare function mapNotionToItem(notionPage: any, statusGroupMap?: Map<string, NotionStatusGroup>): PRDItem;
+export declare function resolveStatusFromNotion(statusName: string, group?: NotionStatusGroup): ItemStatus;
+export interface SchemaValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validate that a Notion database has the expected property configuration
+ * for rex sync. Checks property names and types; does not validate individual
+ * option values (those can be added via the Notion UI).
+ */
+export declare function validateDatabaseSchema(databaseProperties: Record<string, any>): SchemaValidationResult;
+/**
+ * Determine the Notion parent reference for an item.
+ *
+ * @param item       The PRDItem being placed.
+ * @param databaseId The root Notion database ID (used for top-level items).
+ * @param idMap      Map of PRD item ID → Notion page ID (for already-synced items).
+ * @param parentId   The PRD ID of this item's parent (from the tree walk).
+ */
+export declare function resolveParentPage(item: PRDItem, databaseId: string, idMap: Map<string, string>, parentId?: string): NotionParent;
+/**
+ * Flatten an entire PRD document into an ordered list of Notion page descriptors.
+ * Items are yielded in DFS order so parents are created before children.
+ *
+ * Each descriptor includes the PRDItem, its mapped Notion properties, body blocks,
+ * the resolved Notion parent reference, and the PRD parent ID (for post-creation
+ * ID mapping).
+ */
+export declare function mapDocumentToNotion(doc: PRDDocument, databaseId: string): NotionPageDescriptor[];
+/**
+ * Reconstruct a PRDDocument tree from a flat list of Notion pages.
+ * Uses each page's `parent.page_id` or `parent.database_id` to determine nesting.
+ *
+ * Pages whose parent.database_id is set are treated as roots.
+ * Pages whose parent.page_id matches another page's Notion ID become children.
+ * Orphaned pages (parent not found) are placed at root level.
+ *
+ * @param statusGroupMap  Optional map of status option name → group name, for
+ *                        group-based status resolution of custom options.
+ */
+export declare function mapNotionToDocument(notionPages: any[], projectTitle: string, statusGroupMap?: Map<string, NotionStatusGroup>): PRDDocument;
+/**
+ * Build a status group map from a Notion database schema response.
+ * Extracts the Status property's groups and maps each option name to its group.
+ *
+ * @example
+ *   const db = await notion.databases.retrieve({ database_id: "..." });
+ *   const groupMap = buildStatusGroupMap(db.properties);
+ *   const doc = mapNotionToDocument(pages, "Project", groupMap);
+ */
+export declare function buildStatusGroupMap(databaseProperties: Record<string, any>): Map<string, NotionStatusGroup>;