@moxn/kb-migrate 0.4.1 → 0.4.3

package/dist/client.d.ts

@@ -1,7 +1,6 @@
 /**
  * API client for Moxn KB
  */
-/// <reference types="node" resolution-mode="require"/>
 import type { ExtractedDocument, MigrationOptions, MigrationResult, DocumentListItem, DocumentDetail, ExportOptions } from './types.js';
 export declare class MoxnClient {
     private apiUrl;

package/dist/sources/notion-blocks.js

@@ -287,7 +287,7 @@ function convertImage(block) {
                 blockType: 'image',
                 type: 'url',
                 url: img.image.external.url,
-                mediaType: 'image/png',
+                mediaType: 'image/png', // Generic — Moxn will detect actual type
                 alt: caption || undefined,
             },
         ];
@@ -429,24 +429,27 @@ export function richTextToMarkdown(richText) {
             text = '*' + text + '*';
         if (rt.annotations.strikethrough)
             text = '~~' + text + '~~';
-        // Apply link
-        if (rt.href) {
-            text = `[${text}](${rt.href})`;
-        }
-        else if (rt.type === 'mention' && rt.mention) {
-            // Handle mention types
+        // Handle mentions BEFORE href — Notion sets href on mentions too
+        // (as a web URL), but we want notion:// protocol for resolution
+        if (rt.type === 'mention' && rt.mention) {
             if (rt.mention.type === 'user' && rt.mention.user?.name) {
                 text = `@${rt.mention.user.name}`;
             }
             else if (rt.mention.type === 'page' && rt.mention.page) {
                 text = `[${text}](notion://${rt.mention.page.id})`;
             }
+            else if (rt.mention.type === 'database' && rt.mention.database) {
+                text = `[${text}](notion://${rt.mention.database.id})`;
+            }
             else if (rt.mention.type === 'date' && rt.mention.date) {
                 text = rt.mention.date.start;
                 if (rt.mention.date.end)
                     text += ` → ${rt.mention.date.end}`;
             }
         }
+        else if (rt.href) {
+            text = `[${text}](${rt.href})`;
+        }
         else if (rt.type === 'equation' && rt.equation) {
             text = `$${rt.equation.expression}$`;
         }

package/dist/sources/notion-blocks.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sources/notion-blocks.test.js

@@ -0,0 +1,196 @@
+import { describe, it, expect } from 'vitest';
+import { richTextToMarkdown, normalizeId } from './notion-blocks.js';
+// ============================================
+// Helper to build NotionRichText objects
+// ============================================
+function plainText(text, overrides) {
+    return {
+        type: 'text',
+        plain_text: text,
+        annotations: {
+            bold: false,
+            italic: false,
+            strikethrough: false,
+            underline: false,
+            code: false,
+            color: 'default',
+        },
+        href: null,
+        ...overrides,
+    };
+}
+// ============================================
+// Database mention handling
+// ============================================
+describe('richTextToMarkdown', () => {
+    describe('database mentions', () => {
+        it('renders database mention as notion:// link', () => {
+            const rt = {
+                type: 'mention',
+                plain_text: 'My Database',
+                annotations: {
+                    bold: false,
+                    italic: false,
+                    strikethrough: false,
+                    underline: false,
+                    code: false,
+                    color: 'default',
+                },
+                href: null,
+                mention: {
+                    type: 'database',
+                    database: { id: 'abc123de-f456-abc1-23de-f456abc123de' },
+                },
+            };
+            const result = richTextToMarkdown([rt]);
+            expect(result).toBe('[My Database](notion://abc123de-f456-abc1-23de-f456abc123de)');
+        });
+        it('renders database mention with href using notion:// (mention takes precedence over href)', () => {
+            // Mentions should always use notion:// protocol, even when href is set
+            const rt = {
+                type: 'mention',
+                plain_text: 'My Database',
+                annotations: {
+                    bold: false,
+                    italic: false,
+                    strikethrough: false,
+                    underline: false,
+                    code: false,
+                    color: 'default',
+                },
+                href: 'https://www.notion.so/workspace/abc123de-f456-abc1-23de-f456abc123de',
+                mention: {
+                    type: 'database',
+                    database: { id: 'abc123de-f456-abc1-23de-f456abc123de' },
+                },
+            };
+            const result = richTextToMarkdown([rt]);
+            expect(result).toBe('[My Database](notion://abc123de-f456-abc1-23de-f456abc123de)');
+        });
+    });
+    describe('page mentions', () => {
+        it('renders page mention without href as notion:// link', () => {
+            const rt = {
+                type: 'mention',
+                plain_text: 'My Page',
+                annotations: {
+                    bold: false,
+                    italic: false,
+                    strikethrough: false,
+                    underline: false,
+                    code: false,
+                    color: 'default',
+                },
+                href: null,
+                mention: {
+                    type: 'page',
+                    page: { id: 'abc123de-f456-abc1-23de-f456abc123de' },
+                },
+            };
+            const result = richTextToMarkdown([rt]);
+            expect(result).toBe('[My Page](notion://abc123de-f456-abc1-23de-f456abc123de)');
+        });
+        it('renders page mention with href using notion:// (mention takes precedence over href)', () => {
+            const rt = {
+                type: 'mention',
+                plain_text: 'My Page',
+                annotations: {
+                    bold: false,
+                    italic: false,
+                    strikethrough: false,
+                    underline: false,
+                    code: false,
+                    color: 'default',
+                },
+                href: 'https://www.notion.so/workspace/abc123de-f456-abc1-23de-f456abc123de',
+                mention: {
+                    type: 'page',
+                    page: { id: 'abc123de-f456-abc1-23de-f456abc123de' },
+                },
+            };
+            const result = richTextToMarkdown([rt]);
+            expect(result).toBe('[My Page](notion://abc123de-f456-abc1-23de-f456abc123de)');
+        });
+    });
+    describe('other mention types preserved', () => {
+        it('renders user mentions as @name', () => {
+            const rt = {
+                type: 'mention',
+                plain_text: 'John',
+                annotations: {
+                    bold: false,
+                    italic: false,
+                    strikethrough: false,
+                    underline: false,
+                    code: false,
+                    color: 'default',
+                },
+                href: null,
+                mention: {
+                    type: 'user',
+                    user: { id: 'user-123', name: 'John' },
+                },
+            };
+            const result = richTextToMarkdown([rt]);
+            expect(result).toBe('@John');
+        });
+        it('renders date mentions', () => {
+            const rt = {
+                type: 'mention',
+                plain_text: '2024-01-15',
+                annotations: {
+                    bold: false,
+                    italic: false,
+                    strikethrough: false,
+                    underline: false,
+                    code: false,
+                    color: 'default',
+                },
+                href: null,
+                mention: {
+                    type: 'date',
+                    date: { start: '2024-01-15', end: '2024-01-20' },
+                },
+            };
+            const result = richTextToMarkdown([rt]);
+            expect(result).toBe('2024-01-15 → 2024-01-20');
+        });
+    });
+    describe('annotations on mentions', () => {
+        it('applies bold to database mention', () => {
+            const rt = {
+                type: 'mention',
+                plain_text: 'DB',
+                annotations: {
+                    bold: true,
+                    italic: false,
+                    strikethrough: false,
+                    underline: false,
+                    code: false,
+                    color: 'default',
+                },
+                href: null,
+                mention: {
+                    type: 'database',
+                    database: { id: 'aaaa1111bbbb2222cccc3333dddd4444' },
+                },
+            };
+            const result = richTextToMarkdown([rt]);
+            expect(result).toBe('[**DB**](notion://aaaa1111bbbb2222cccc3333dddd4444)');
+        });
+    });
+});
+// ============================================
+// normalizeId
+// ============================================
+describe('normalizeId', () => {
+    it('removes dashes from UUID', () => {
+        expect(normalizeId('abc123de-f456-abc1-23de-f456abc123de')).toBe('abc123def456abc123def456abc123de');
+    });
+    it('returns already-normalized ID unchanged', () => {
+        expect(normalizeId('abc123def456abc123def456abc123de')).toBe('abc123def456abc123def456abc123de');
+    });
+    it('handles empty string', () => {
+        expect(normalizeId('')).toBe('');
+    });
+});

package/dist/sources/notion-databases.js

@@ -6,7 +6,7 @@
  * - title → document name (not a column)
  * - All other property types → rendered as markdown in a "Properties" section
  */
-import { richTextToPlain, richTextToMarkdown, getPageTitle } from './notion-blocks.js';
+import { richTextToPlain, richTextToMarkdown, getPageTitle, normalizeId, } from './notion-blocks.js';
 // ============================================
 // Schema Parsing
 // ============================================
@@ -208,7 +208,7 @@ function renderPropertyValue(prop) {
         case 'relation':
             if (!prop.relation || prop.relation.length === 0)
                 return null;
-            return prop.relation.map((r) => r.id).join(', ');
+            return prop.relation.map((r) => `notion-ref:${normalizeId(r.id)}`).join(', ');
         case 'formula':
             if (!prop.formula)
                 return null;

package/dist/sources/notion-databases.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sources/notion-databases.test.js

@@ -0,0 +1,115 @@
+import { describe, it, expect } from 'vitest';
+import { parseEntryValues, renderPropertiesSection } from './notion-databases.js';
+// ============================================
+// Helpers
+// ============================================
+function makeEntryPage(properties) {
+    return {
+        id: 'page-123',
+        object: 'page',
+        parent: { type: 'database_id', database_id: 'db-123' },
+        created_time: '2024-01-01T00:00:00.000Z',
+        last_edited_time: '2024-01-01T00:00:00.000Z',
+        archived: false,
+        url: 'https://notion.so/page-123',
+        properties: {
+            Name: {
+                id: 'title-id',
+                type: 'title',
+                title: [
+                    {
+                        type: 'text',
+                        plain_text: 'Test Entry',
+                        annotations: {
+                            bold: false,
+                            italic: false,
+                            strikethrough: false,
+                            underline: false,
+                            code: false,
+                            color: 'default',
+                        },
+                        href: null,
+                    },
+                ],
+            },
+            ...properties,
+        },
+    };
+}
+function makeSchema(unmappedColumns) {
+    return {
+        name: 'Test DB',
+        description: '',
+        mappedColumns: [],
+        unmappedColumns: unmappedColumns.map((name) => ({
+            notionPropertyId: `prop-${name}`,
+            notionPropertyName: name,
+            notionType: 'relation',
+        })),
+    };
+}
+// ============================================
+// Relation property rendering
+// ============================================
+describe('relation property rendering', () => {
+    it('renders relation IDs with notion-ref: prefix and normalized IDs', () => {
+        const page = makeEntryPage({
+            Related: {
+                id: 'rel-id',
+                type: 'relation',
+                relation: [
+                    { id: 'abc123de-f456-abc1-23de-f456abc123de' },
+                    { id: 'eeee5555-ffff-6666-aaaa-7777bbbb8888' },
+                ],
+            },
+        });
+        const schema = makeSchema(['Related']);
+        const values = parseEntryValues(page, schema);
+        const relatedValue = values.textValues.get('Related');
+        expect(relatedValue).toBe('notion-ref:abc123def456abc123def456abc123de, notion-ref:eeee5555ffff6666aaaa7777bbbb8888');
+    });
+    it('returns null for empty relation array', () => {
+        const page = makeEntryPage({
+            Related: {
+                id: 'rel-id',
+                type: 'relation',
+                relation: [],
+            },
+        });
+        const schema = makeSchema(['Related']);
+        const values = parseEntryValues(page, schema);
+        expect(values.textValues.has('Related')).toBe(false);
+    });
+    it('renders single relation with notion-ref: prefix', () => {
+        const page = makeEntryPage({
+            Parent: {
+                id: 'rel-id',
+                type: 'relation',
+                relation: [{ id: 'aaaa1111bbbb2222cccc3333dddd4444' }],
+            },
+        });
+        const schema = makeSchema(['Parent']);
+        const values = parseEntryValues(page, schema);
+        const parentValue = values.textValues.get('Parent');
+        // Already normalized (no dashes) — should still get prefix
+        expect(parentValue).toBe('notion-ref:aaaa1111bbbb2222cccc3333dddd4444');
+    });
+    it('renders relation refs in properties section markdown table', () => {
+        const page = makeEntryPage({
+            Related: {
+                id: 'rel-id',
+                type: 'relation',
+                relation: [{ id: 'abc123de-f456-abc1-23de-f456abc123de' }],
+            },
+        });
+        const schema = makeSchema(['Related']);
+        const values = parseEntryValues(page, schema);
+        const section = renderPropertiesSection(values);
+        expect(section).not.toBeNull();
+        const textBlock = section.content[0];
+        expect(textBlock.blockType).toBe('text');
+        const text = textBlock.text;
+        expect(text).toContain('notion-ref:abc123def456abc123def456abc123de');
+        expect(text).toContain('| Related |');
+    });
+});

package/dist/sources/notion-references.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Post-processing pass to resolve Notion cross-references in imported content.
+ *
+ * Instead of threading a pagePathMap through every richTextToMarkdown() call site,
+ * this module operates on the final TextBlock strings, catching ALL reference patterns
+ * regardless of their source (paragraph, heading, list, quote, callout, table, etc.).
+ *
+ * Also extracts reference metadata for KB Reference object creation.
+ */
+import type { SectionInput } from '../types.js';
+export interface NotionIdMapping {
+    notionIdToKbPath: Map<string, string>;
+}
+export interface ExtractedReference {
+    sectionIndex: number;
+    targetNotionId: string;
+    targetKbPath: string | null;
+    displayText: string;
+}
+export interface ResolvedSections {
+    sections: SectionInput[];
+    references: ExtractedReference[];
+}
+/**
+ * Resolve Notion cross-references in section content and extract reference metadata.
+ *
+ * Processes all TextBlock content, replacing Notion URLs/IDs with KB paths
+ * where a mapping exists. Returns both the resolved sections and a list of
+ * extracted references for KB Reference object creation.
+ */
+export declare function resolveNotionReferences(sections: SectionInput[], mapping: NotionIdMapping): ResolvedSections;
+/**
+ * Resolve relation property IDs directly (for use in property rendering).
+ * Replaces notion-ref:ID markers with KB path links or bare IDs.
+ */
+export declare function resolveRelationIds(value: string, mapping: NotionIdMapping): string;

package/dist/sources/notion-references.js

@@ -0,0 +1,159 @@
+/**
+ * Post-processing pass to resolve Notion cross-references in imported content.
+ *
+ * Instead of threading a pagePathMap through every richTextToMarkdown() call site,
+ * this module operates on the final TextBlock strings, catching ALL reference patterns
+ * regardless of their source (paragraph, heading, list, quote, callout, table, etc.).
+ *
+ * Also extracts reference metadata for KB Reference object creation.
+ */
+import { normalizeId } from './notion-blocks.js';
+// ============================================
+// Patterns
+// ============================================
+// 1. notion:// links: [text](notion://abc123...)
+const NOTION_PROTOCOL_RE = /\[([^\]]*)\]\(notion:\/\/([a-f0-9-]{32,36})\)/g;
+// 2. Notion web URLs: [text](https://www.notion.so/workspace/page-id?query)
+// The ID can appear with or without dashes. It may also appear as a slug suffix (last 32 hex chars).
+const NOTION_WEB_URL_RE = /\[([^\]]*)\]\(https?:\/\/(?:www\.)?notion\.so\/(?:[a-zA-Z0-9_-]+\/)*([a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})(?:[?#][^)]*)?(?:\))/g;
+// Fallback for IDs without dashes embedded in slug URLs (e.g., ...Page-Title-abc123def456...)
+const NOTION_WEB_URL_SLUG_RE = /\[([^\]]*)\]\(https?:\/\/(?:www\.)?notion\.so\/(?:[a-zA-Z0-9_-]+\/)*[a-zA-Z0-9-]+-([a-f0-9]{32})(?:[?#][^)]*)?\)/g;
+// Bare 32-char hex on notion.so (e.g., https://www.notion.so/3004bf42cfeb818ebe8fe2f4befdad52)
+// Catches mention hrefs that leak through as web URLs
+const NOTION_WEB_URL_BARE_RE = /\[([^\]]*)\]\(https?:\/\/(?:www\.)?notion\.so\/(?:[a-zA-Z0-9_-]+\/)*([a-f0-9]{32})(?:[?#][^)]*)?\)/g;
+// 3. Unresolved placeholders from link_to_page conversion
+const LINK_PLACEHOLDER_RE = /\*\(Link to Notion page: ([a-f0-9-]{32,36})\)\*/g;
+// 4. Relation property markers
+const RELATION_REF_RE = /notion-ref:([a-f0-9]{32})/g;
+// ============================================
+// Main function
+// ============================================
+/**
+ * Resolve Notion cross-references in section content and extract reference metadata.
+ *
+ * Processes all TextBlock content, replacing Notion URLs/IDs with KB paths
+ * where a mapping exists. Returns both the resolved sections and a list of
+ * extracted references for KB Reference object creation.
+ */
+export function resolveNotionReferences(sections, mapping) {
+    const references = [];
+    const resolvedSections = sections.map((section, sectionIndex) => {
+        const resolvedContent = section.content.map((block) => {
+            if (block.blockType !== 'text')
+                return block;
+            const textBlock = block;
+            let text = textBlock.text;
+            // Pass 1: notion:// protocol links
+            text = text.replace(NOTION_PROTOCOL_RE, (_match, displayText, rawId) => {
+                const nid = normalizeId(rawId);
+                const kbPath = mapping.notionIdToKbPath.get(nid);
+                if (kbPath) {
+                    references.push({
+                        sectionIndex,
+                        targetNotionId: nid,
+                        targetKbPath: kbPath,
+                        displayText: displayText || kbPath,
+                    });
+                    return `[${displayText || kbPath}](${kbPath})`;
+                }
+                // Leave as notion:// for future re-resolution
+                return `[${displayText}](notion://${nid})`;
+            });
+            // Pass 2: Notion web URLs (with dashes in UUID)
+            text = text.replace(NOTION_WEB_URL_RE, (_match, displayText, rawId) => {
+                const nid = normalizeId(rawId);
+                const kbPath = mapping.notionIdToKbPath.get(nid);
+                if (kbPath) {
+                    references.push({
+                        sectionIndex,
+                        targetNotionId: nid,
+                        targetKbPath: kbPath,
+                        displayText: displayText || kbPath,
+                    });
+                    return `[${displayText || kbPath}](${kbPath})`;
+                }
+                // Unresolved — normalize to notion:// format
+                return `[${displayText}](notion://${nid})`;
+            });
+            // Pass 3: Notion web URLs (slug-embedded 32-char hex IDs)
+            text = text.replace(NOTION_WEB_URL_SLUG_RE, (_match, displayText, rawId) => {
+                const nid = normalizeId(rawId);
+                const kbPath = mapping.notionIdToKbPath.get(nid);
+                if (kbPath) {
+                    references.push({
+                        sectionIndex,
+                        targetNotionId: nid,
+                        targetKbPath: kbPath,
+                        displayText: displayText || kbPath,
+                    });
+                    return `[${displayText || kbPath}](${kbPath})`;
+                }
+                return `[${displayText}](notion://${nid})`;
+            });
+            // Pass 3b: Bare 32-char hex Notion URLs (safety net for mention hrefs)
+            text = text.replace(NOTION_WEB_URL_BARE_RE, (_match, displayText, rawId) => {
+                const nid = normalizeId(rawId);
+                const kbPath = mapping.notionIdToKbPath.get(nid);
+                if (kbPath) {
+                    references.push({
+                        sectionIndex,
+                        targetNotionId: nid,
+                        targetKbPath: kbPath,
+                        displayText: displayText || kbPath,
+                    });
+                    return `[${displayText || kbPath}](${kbPath})`;
+                }
+                return `[${displayText}](notion://${nid})`;
+            });
+            // Pass 4: Unresolved link_to_page placeholders
+            text = text.replace(LINK_PLACEHOLDER_RE, (_match, rawId) => {
+                const nid = normalizeId(rawId);
+                const kbPath = mapping.notionIdToKbPath.get(nid);
+                if (kbPath) {
+                    references.push({
+                        sectionIndex,
+                        targetNotionId: nid,
+                        targetKbPath: kbPath,
+                        displayText: kbPath,
+                    });
+                    return `[${kbPath}](${kbPath})`;
+                }
+                // Leave as placeholder
+                return `*(Link to Notion page: ${rawId})*`;
+            });
+            // Pass 5: Relation property markers
+            text = text.replace(RELATION_REF_RE, (_match, rawId) => {
+                const nid = normalizeId(rawId);
+                const kbPath = mapping.notionIdToKbPath.get(nid);
+                if (kbPath) {
+                    references.push({
+                        sectionIndex,
+                        targetNotionId: nid,
+                        targetKbPath: kbPath,
+                        displayText: kbPath,
+                    });
+                    return `[${kbPath}](${kbPath})`;
+                }
+                // Unresolved — keep the ID
+                return nid;
+            });
+            return { blockType: 'text', text };
+        });
+        return { name: section.name, content: resolvedContent };
+    });
+    return { sections: resolvedSections, references };
+}
+/**
+ * Resolve relation property IDs directly (for use in property rendering).
+ * Replaces notion-ref:ID markers with KB path links or bare IDs.
+ */
+export function resolveRelationIds(value, mapping) {
+    return value.replace(RELATION_REF_RE, (_match, rawId) => {
+        const nid = normalizeId(rawId);
+        const kbPath = mapping.notionIdToKbPath.get(nid);
+        if (kbPath) {
+            return `[${kbPath}](${kbPath})`;
+        }
+        return nid;
+    });
+}

package/dist/sources/notion-references.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sources/notion-references.test.js

@@ -0,0 +1,423 @@
+import { describe, it, expect } from 'vitest';
+import { resolveNotionReferences, resolveRelationIds, } from './notion-references.js';
+// ============================================
+// Helpers
+// ============================================
+function textSection(name, ...texts) {
+    return {
+        name,
+        content: texts.map((t) => ({ blockType: 'text', text: t })),
+    };
+}
+function mapping(entries) {
+    return {
+        notionIdToKbPath: new Map(Object.entries(entries)),
+    };
+}
+function getText(section, blockIndex = 0) {
+    const block = section.content[blockIndex];
+    if (block.blockType !== 'text')
+        throw new Error('Expected text block');
+    return block.text;
+}
+// ============================================
+// resolveNotionReferences
+// ============================================
+describe('resolveNotionReferences', () => {
+    describe('notion:// protocol links', () => {
+        it('resolves a notion:// link when ID is in the mapping', () => {
+            const sections = [
+                textSection('Intro', 'See [My Page](notion://abc123def456abc123def456abc123de)'),
+            ];
+            const m = mapping({ abc123def456abc123def456abc123de: '/docs/my-page' });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('See [My Page](/docs/my-page)');
+            expect(references).toHaveLength(1);
+            expect(references[0]).toEqual({
+                sectionIndex: 0,
+                targetNotionId: 'abc123def456abc123def456abc123de',
+                targetKbPath: '/docs/my-page',
+                displayText: 'My Page',
+            });
+        });
+        it('normalizes IDs with dashes before lookup', () => {
+            const sections = [
+                textSection('Intro', 'See [Page](notion://abc123de-f456-abc1-23de-f456abc123de)'),
+            ];
+            const m = mapping({ abc123def456abc123def456abc123de: '/docs/page' });
+            const { sections: resolved } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('See [Page](/docs/page)');
+        });
+        it('keeps unresolved notion:// links with normalized ID', () => {
+            const sections = [
+                textSection('Intro', 'See [Gone](notion://aaaa1111bbbb2222cccc3333dddd4444)'),
+            ];
+            const m = mapping({});
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('See [Gone](notion://aaaa1111bbbb2222cccc3333dddd4444)');
+            expect(references).toHaveLength(0);
+        });
+        it('uses KB path as display text when original display text is empty', () => {
+            const sections = [
+                textSection('Intro', 'See [](notion://abc123def456abc123def456abc123de)'),
+            ];
+            const m = mapping({ abc123def456abc123def456abc123de: '/docs/page' });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('See [/docs/page](/docs/page)');
+            expect(references[0].displayText).toBe('/docs/page');
+        });
+    });
+    describe('Notion web URLs', () => {
+        it('resolves https://www.notion.so/ URLs with UUID', () => {
+            const uuid = 'abc123de-f456-abc1-23de-f456abc123de';
+            const sections = [
+                textSection('Intro', `Check [this](https://www.notion.so/workspace/${uuid})`),
+            ];
+            const m = mapping({ abc123def456abc123def456abc123de: '/docs/target' });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('Check [this](/docs/target)');
+            expect(references).toHaveLength(1);
+        });
+        it('resolves http:// variant (no www)', () => {
+            const uuid = 'abc123de-f456-abc1-23de-f456abc123de';
+            const sections = [textSection('Intro', `See [link](http://notion.so/${uuid})`)];
+            const m = mapping({ abc123def456abc123def456abc123de: '/docs/target' });
+            const { sections: resolved } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('See [link](/docs/target)');
+        });
+        it('handles URLs with query params and hash', () => {
+            const uuid = 'abc123de-f456-abc1-23de-f456abc123de';
+            const sections = [
+                textSection('Intro', `See [link](https://www.notion.so/workspace/${uuid}?pvs=4#section)`),
+            ];
+            const m = mapping({ abc123def456abc123def456abc123de: '/docs/target' });
+            const { sections: resolved } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('See [link](/docs/target)');
+        });
+        it('handles URLs with workspace slug prefix', () => {
+            const uuid = 'abc123de-f456-abc1-23de-f456abc123de';
+            const sections = [
+                textSection('Intro', `See [link](https://www.notion.so/my-workspace/${uuid})`),
+            ];
+            const m = mapping({ abc123def456abc123def456abc123de: '/docs/target' });
+            const { sections: resolved } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('See [link](/docs/target)');
+        });
+        it('normalizes unresolved web URLs to notion:// format', () => {
+            const uuid = 'aaaa1111-bbbb-2222-cccc-3333dddd4444';
+            const sections = [
+                textSection('Intro', `See [link](https://www.notion.so/workspace/${uuid})`),
+            ];
+            const m = mapping({});
+            const { sections: resolved } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('See [link](notion://aaaa1111bbbb2222cccc3333dddd4444)');
+        });
+        it('resolves slug-embedded 32-char hex IDs', () => {
+            const sections = [
+                textSection('Intro', 'See [link](https://notion.so/My-Page-Title-abc123def456abc123def456abc123de)'),
+            ];
+            const m = mapping({ abc123def456abc123def456abc123de: '/docs/my-page' });
+            const { sections: resolved } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('See [link](/docs/my-page)');
+        });
+        it('resolves bare 32-char hex Notion URLs (no slug prefix)', () => {
+            const sections = [
+                textSection('Intro', 'See [Dev Setup](https://www.notion.so/3004bf42cfeb818ebe8fe2f4befdad52)'),
+            ];
+            const m = mapping({ '3004bf42cfeb818ebe8fe2f4befdad52': '/docs/dev-setup' });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('See [Dev Setup](/docs/dev-setup)');
+            expect(references).toHaveLength(1);
+            expect(references[0].targetNotionId).toBe('3004bf42cfeb818ebe8fe2f4befdad52');
+        });
+        it('normalizes unresolved bare hex Notion URLs to notion://', () => {
+            const sections = [
+                textSection('Intro', 'See [page](https://www.notion.so/aabbccdd11223344aabbccdd11223344)'),
+            ];
+            const m = mapping({});
+            const { sections: resolved } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('See [page](notion://aabbccdd11223344aabbccdd11223344)');
+        });
+    });
+    describe('link_to_page placeholders', () => {
+        it('resolves placeholders to KB path links', () => {
+            const sections = [
+                textSection('Intro', '*(Link to Notion page: abc123def456abc123def456abc123de)*'),
+            ];
+            const m = mapping({ abc123def456abc123def456abc123de: '/docs/linked-page' });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('[/docs/linked-page](/docs/linked-page)');
+            expect(references).toHaveLength(1);
+            expect(references[0].displayText).toBe('/docs/linked-page');
+        });
+        it('resolves placeholders with dashed UUIDs', () => {
+            const sections = [
+                textSection('Intro', '*(Link to Notion page: abc123de-f456-abc1-23de-f456abc123de)*'),
+            ];
+            const m = mapping({ abc123def456abc123def456abc123de: '/docs/page' });
+            const { sections: resolved } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('[/docs/page](/docs/page)');
+        });
+        it('keeps unresolved placeholders unchanged', () => {
+            const sections = [
+                textSection('Intro', '*(Link to Notion page: abc123def456abc123def456abc123de)*'),
+            ];
+            const m = mapping({});
+            const { sections: resolved } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('*(Link to Notion page: abc123def456abc123def456abc123de)*');
+        });
+    });
+    describe('relation property markers', () => {
+        it('resolves notion-ref: markers to KB path links', () => {
+            const sections = [
+                textSection('Properties', '| Related | notion-ref:abc123def456abc123def456abc123de |'),
+            ];
+            const m = mapping({ abc123def456abc123def456abc123de: '/docs/related' });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('| Related | [/docs/related](/docs/related) |');
+            expect(references).toHaveLength(1);
+        });
+        it('resolves multiple comma-separated relation refs', () => {
+            const sections = [
+                textSection('Properties', 'notion-ref:aaaa1111bbbb2222cccc3333dddd4444, notion-ref:eeee5555ffff6666aaaa7777bbbb8888'),
+            ];
+            const m = mapping({
+                aaaa1111bbbb2222cccc3333dddd4444: '/docs/page-a',
+                eeee5555ffff6666aaaa7777bbbb8888: '/docs/page-b',
+            });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('[/docs/page-a](/docs/page-a), [/docs/page-b](/docs/page-b)');
+            expect(references).toHaveLength(2);
+        });
+        it('keeps unresolved relation refs as bare IDs', () => {
+            const sections = [
+                textSection('Properties', 'notion-ref:aaaa1111bbbb2222cccc3333dddd4444'),
+            ];
+            const m = mapping({});
+            const { sections: resolved } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('aaaa1111bbbb2222cccc3333dddd4444');
+        });
+    });
+    describe('multiple references', () => {
+        it('resolves multiple different reference types in one text block', () => {
+            const sections = [
+                textSection('Mixed', [
+                    'See [Page A](notion://aaaa1111bbbb2222cccc3333dddd4444)',
+                    'and *(Link to Notion page: eeee5555ffff6666aaaa7777bbbb8888)*',
+                    'also notion-ref:1111222233334444555566667777aaaa',
+                ].join(' ')),
+            ];
+            const m = mapping({
+                aaaa1111bbbb2222cccc3333dddd4444: '/docs/a',
+                eeee5555ffff6666aaaa7777bbbb8888: '/docs/b',
+                '1111222233334444555566667777aaaa': '/docs/c',
+            });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            const text = getText(resolved[0]);
+            expect(text).toContain('[Page A](/docs/a)');
+            expect(text).toContain('[/docs/b](/docs/b)');
+            expect(text).toContain('[/docs/c](/docs/c)');
+            expect(references).toHaveLength(3);
+        });
+        it('handles mixed resolved and unresolved references', () => {
+            const sections = [
+                textSection('Mixed', '[Known](notion://aaaa1111bbbb2222cccc3333dddd4444) and [Unknown](notion://ffffffffffffffffffffffffffffffff)'),
+            ];
+            const m = mapping({ aaaa1111bbbb2222cccc3333dddd4444: '/docs/known' });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            const text = getText(resolved[0]);
+            expect(text).toContain('[Known](/docs/known)');
+            expect(text).toContain('[Unknown](notion://ffffffffffffffffffffffffffffffff)');
+            expect(references).toHaveLength(1);
+        });
+    });
+    describe('section indexing', () => {
+        it('tracks correct sectionIndex across multiple sections', () => {
+            const sections = [
+                textSection('Section 0', '[A](notion://aaaa1111bbbb2222cccc3333dddd4444)'),
+                textSection('Section 1', 'No references here'),
+                textSection('Section 2', '[B](notion://eeee5555ffff6666aaaa7777bbbb8888)'),
+            ];
+            const m = mapping({
+                aaaa1111bbbb2222cccc3333dddd4444: '/docs/a',
+                eeee5555ffff6666aaaa7777bbbb8888: '/docs/b',
+            });
+            const { references } = resolveNotionReferences(sections, m);
+            expect(references).toHaveLength(2);
+            expect(references[0].sectionIndex).toBe(0);
+            expect(references[1].sectionIndex).toBe(2);
+        });
+        it('assigns sectionIndex based on section position, not block position', () => {
+            const sections = [
+                {
+                    name: 'Multi-block',
+                    content: [
+                        { blockType: 'text', text: 'No ref here' },
+                        {
+                            blockType: 'text',
+                            text: '[A](notion://aaaa1111bbbb2222cccc3333dddd4444)',
+                        },
+                    ],
+                },
+            ];
+            const m = mapping({ aaaa1111bbbb2222cccc3333dddd4444: '/docs/a' });
+            const { references } = resolveNotionReferences(sections, m);
+            expect(references).toHaveLength(1);
+            expect(references[0].sectionIndex).toBe(0);
+        });
+    });
+    describe('non-text blocks', () => {
+        it('passes image blocks through unchanged', () => {
+            const sections = [
+                {
+                    name: 'Images',
+                    content: [
+                        {
+                            blockType: 'image',
+                            type: 'url',
+                            url: 'https://example.com/img.png',
+                            mediaType: 'image/png',
+                        },
+                    ],
+                },
+            ];
+            const m = mapping({ aaaa1111bbbb2222cccc3333dddd4444: '/docs/a' });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(resolved[0].content[0]).toEqual(sections[0].content[0]);
+            expect(references).toHaveLength(0);
+        });
+        it('handles mixed text and non-text blocks', () => {
+            const sections = [
+                {
+                    name: 'Mixed',
+                    content: [
+                        {
+                            blockType: 'text',
+                            text: '[A](notion://aaaa1111bbbb2222cccc3333dddd4444)',
+                        },
+                        {
+                            blockType: 'image',
+                            type: 'url',
+                            url: 'https://example.com/img.png',
+                            mediaType: 'image/png',
+                        },
+                        { blockType: 'text', text: 'Plain text, no refs' },
+                    ],
+                },
+            ];
+            const m = mapping({ aaaa1111bbbb2222cccc3333dddd4444: '/docs/a' });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0], 0)).toBe('[A](/docs/a)');
+            expect(resolved[0].content[1].blockType).toBe('image');
+            expect(getText(resolved[0], 2)).toBe('Plain text, no refs');
+            expect(references).toHaveLength(1);
+        });
+    });
+    describe('edge cases', () => {
+        it('handles empty sections array', () => {
+            const { sections, references } = resolveNotionReferences([], mapping({}));
+            expect(sections).toEqual([]);
+            expect(references).toEqual([]);
+        });
+        it('handles sections with empty content', () => {
+            const sections = [{ name: 'Empty', content: [] }];
+            const { sections: resolved, references } = resolveNotionReferences(sections, mapping({}));
+            expect(resolved).toHaveLength(1);
+            expect(resolved[0].content).toEqual([]);
+            expect(references).toEqual([]);
+        });
+        it('handles text blocks with no references', () => {
+            const sections = [
+                textSection('Plain', 'Just some normal text with [a link](https://example.com)'),
+            ];
+            const m = mapping({ aaaa1111bbbb2222cccc3333dddd4444: '/docs/a' });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('Just some normal text with [a link](https://example.com)');
+            expect(references).toHaveLength(0);
+        });
+        it('preserves section names', () => {
+            const sections = [textSection('My Section Name', 'text')];
+            const { sections: resolved } = resolveNotionReferences(sections, mapping({}));
+            expect(resolved[0].name).toBe('My Section Name');
+        });
+        it('does not modify the original sections (immutability)', () => {
+            const original = [
+                textSection('Intro', '[A](notion://aaaa1111bbbb2222cccc3333dddd4444)'),
+            ];
+            const originalText = getText(original[0]);
+            const m = mapping({ aaaa1111bbbb2222cccc3333dddd4444: '/docs/a' });
+            resolveNotionReferences(original, m);
+            // Original should be unchanged
+            expect(getText(original[0])).toBe(originalText);
+        });
+        it('handles duplicate references to the same target in one block', () => {
+            const id = 'aaaa1111bbbb2222cccc3333dddd4444';
+            const sections = [
+                textSection('Intro', `[First](notion://${id}) and [Second](notion://${id})`),
+            ];
+            const m = mapping({ [id]: '/docs/target' });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('[First](/docs/target) and [Second](/docs/target)');
+            // Both occurrences are recorded as references
+            expect(references).toHaveLength(2);
+            expect(references[0].displayText).toBe('First');
+            expect(references[1].displayText).toBe('Second');
+        });
+        it('handles self-references (resolves in content, does not filter)', () => {
+            const id = 'aaaa1111bbbb2222cccc3333dddd4444';
+            const sections = [textSection('Self', `[Self Link](notion://${id})`)];
+            const m = mapping({ [id]: '/docs/self-page' });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('[Self Link](/docs/self-page)');
+            // Resolution function doesn't filter self-refs — that's the caller's job
+            expect(references).toHaveLength(1);
+        });
+        it('handles circular references (A→B and B→A)', () => {
+            const idA = 'aaaa1111bbbb2222cccc3333dddd4444';
+            const idB = 'eeee5555ffff6666aaaa7777bbbb8888';
+            const sections = [
+                textSection('Page A', `Link to [B](notion://${idB})`),
+                textSection('Page B', `Link to [A](notion://${idA})`),
+            ];
+            const m = mapping({
+                [idA]: '/docs/page-a',
+                [idB]: '/docs/page-b',
+            });
+            const { sections: resolved, references } = resolveNotionReferences(sections, m);
+            expect(getText(resolved[0])).toBe('Link to [B](/docs/page-b)');
+            expect(getText(resolved[1])).toBe('Link to [A](/docs/page-a)');
+            expect(references).toHaveLength(2);
+        });
+    });
+});
+// ============================================
+// resolveRelationIds
+// ============================================
+describe('resolveRelationIds', () => {
+    it('resolves a single notion-ref marker', () => {
+        const m = mapping({ aaaa1111bbbb2222cccc3333dddd4444: '/docs/target' });
+        const result = resolveRelationIds('notion-ref:aaaa1111bbbb2222cccc3333dddd4444', m);
+        expect(result).toBe('[/docs/target](/docs/target)');
+    });
+    it('resolves multiple comma-separated markers', () => {
+        const m = mapping({
+            aaaa1111bbbb2222cccc3333dddd4444: '/docs/a',
+            eeee5555ffff6666aaaa7777bbbb8888: '/docs/b',
+        });
+        const result = resolveRelationIds('notion-ref:aaaa1111bbbb2222cccc3333dddd4444, notion-ref:eeee5555ffff6666aaaa7777bbbb8888', m);
+        expect(result).toBe('[/docs/a](/docs/a), [/docs/b](/docs/b)');
+    });
+    it('returns bare ID for unresolved markers', () => {
+        const result = resolveRelationIds('notion-ref:aaaa1111bbbb2222cccc3333dddd4444', mapping({}));
+        expect(result).toBe('aaaa1111bbbb2222cccc3333dddd4444');
+    });
+    it('handles mix of resolved and unresolved', () => {
+        const m = mapping({ aaaa1111bbbb2222cccc3333dddd4444: '/docs/known' });
+        const result = resolveRelationIds('notion-ref:aaaa1111bbbb2222cccc3333dddd4444, notion-ref:ffffffffffffffffffffffffffffffff', m);
+        expect(result).toBe('[/docs/known](/docs/known), ffffffffffffffffffffffffffffffff');
+    });
+    it('returns input unchanged if no markers present', () => {
+        const result = resolveRelationIds('just plain text', mapping({}));
+        expect(result).toBe('just plain text');
+    });
+});

package/dist/sources/notion.js

@@ -12,7 +12,8 @@ import { NotionApiClient } from './notion-api.js';
 import { blocksToSections, getPageTitle, normalizeId, } from './notion-blocks.js';
 import { NotionMediaDownloader } from './notion-media.js';
 import { parseDatabaseSchema, parseEntryValues, renderPropertiesSection, } from './notion-databases.js';
-const MAX_DOCUMENT_COUNT = 10000;
+import { resolveNotionReferences } from './notion-references.js';
+const MAX_DOCUMENT_COUNT = 10_000;
 // ============================================
 // Source
 // ============================================
@@ -302,6 +303,9 @@ export class NotionSource extends MigrationSource {
             let sections = await blocksToSections(blocks, this.client, this.pagePathMap);
             // Download Notion-hosted media files
             sections = await this.downloadSectionMedia(sections);
+            // Resolve cross-references
+            const { sections: resolvedSections, references } = resolveNotionReferences(sections, { notionIdToKbPath: this.pagePathMap });
+            sections = resolvedSections;
             if (sections.length === 0) {
                 console.log(`  Skipping page with no content: ${node.title}`);
                 return null;
@@ -311,6 +315,7 @@ export class NotionSource extends MigrationSource {
                 name: node.title,
                 sections,
                 sourcePath: `notion://${node.page.id}`,
+                references: references.length > 0 ? references : undefined,
             };
         }
         catch (error) {
@@ -337,7 +342,10 @@ export class NotionSource extends MigrationSource {
                 sections.push(...contentSections);
             }
             // Download media
-            const processedSections = await this.downloadSectionMedia(sections);
+            let processedSections = await this.downloadSectionMedia(sections);
+            // Resolve cross-references
+            const { sections: resolvedSections, references } = resolveNotionReferences(processedSections, { notionIdToKbPath: this.pagePathMap });
+            processedSections = resolvedSections;
             const nid = normalizeId(entry.id);
             const kbPath = this.pagePathMap.get(nid) ?? slug;
             return {
@@ -352,6 +360,7 @@ export class NotionSource extends MigrationSource {
                         },
                     ],
                 sourcePath: `notion://${entry.id}`,
+                references: references.length > 0 ? references : undefined,
             };
         }
         catch (error) {

package/dist/types.d.ts

@@ -72,6 +72,16 @@ export interface SectionInput {
     name: string;
     content: ContentBlock[];
 }
+/**
+ * A cross-reference discovered during Notion import resolution.
+ * Re-exported from notion-references for convenience.
+ */
+export interface ExtractedReference {
+    sectionIndex: number;
+    targetNotionId: string;
+    targetKbPath: string | null;
+    displayText: string;
+}
 /**
  * A document extracted from a source
  */
@@ -86,6 +96,8 @@ export interface ExtractedDocument {
     sections: SectionInput[];
     /** Original source path/identifier for logging */
     sourcePath: string;
+    /** Cross-references discovered during resolution */
+    references?: ExtractedReference[];
 }
 /**
  * Status of a single document migration

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxn/kb-migrate",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Migration tool for importing documents into Moxn Knowledge Base from local files, Notion, Google Docs, and more",
   "type": "module",
   "main": "dist/index.js",
@@ -26,6 +26,10 @@
       "types": "./dist/sources/notion-databases.d.ts",
       "default": "./dist/sources/notion-databases.js"
     },
+    "./sources/notion-references": {
+      "types": "./dist/sources/notion-references.d.ts",
+      "default": "./dist/sources/notion-references.js"
+    },
     "./sources/notion-media": {
       "types": "./dist/sources/notion-media.d.ts",
       "default": "./dist/sources/notion-media.js"
@@ -53,6 +57,8 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
@@ -63,7 +69,8 @@
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=18.0.0"