@moxn/kb-migrate 0.4.20 → 0.4.22

package/dist/client.d.ts

@@ -72,6 +72,7 @@ export declare class MoxnClient {
         path: string;
         description?: string;
         color?: string;
+        displayName?: string;
     }): Promise<{
         id: string;
         path: string;
@@ -81,6 +82,20 @@ export declare class MoxnClient {
      * Assign a tag to a document.
      */
     assignTag(documentId: string, tagId: string, branchId: string): Promise<void>;
+    /**
+     * Batch-create references from a document's sections to other documents.
+     * Returns { created, skipped, errors }.
+     */
+    createReferences(documentId: string, references: Array<{
+        sourceSectionId: string;
+        branchId: string;
+        targetDocumentId: string;
+        displayTitle?: string | null;
+    }>): Promise<{
+        created: number;
+        skipped: number;
+        errors: number;
+    }>;
     /**
      * List all KB databases for the tenant.
      */

package/dist/client.js

@@ -51,6 +51,9 @@ export class MoxnClient {
                 documentId: createResult.id,
                 branchId: createResult.branchId,
                 sectionsCount: createResult.sections.length,
+                sectionIds: createResult.sections.map((s) => s.id),
+                references: doc.references,
+                sourcePageId: doc.metadata?.notionPageId,
                 duration: Date.now() - startTime,
             };
         }
@@ -82,6 +85,9 @@ export class MoxnClient {
                         documentId: updateResult.id,
                         branchId: updateResult.branchId,
                         sectionsCount: updateResult.sections.length,
+                        sectionIds: updateResult.sections.map((s) => s.id),
+                        references: doc.references,
+                        sourcePageId: doc.metadata?.notionPageId,
                         duration: Date.now() - startTime,
                     };
                 }
@@ -414,6 +420,25 @@ export class MoxnClient {
             throw new Error(body.error || `Failed to assign tag: ${response.status}`);
         }
     }
+    /**
+     * Batch-create references from a document's sections to other documents.
+     * Returns { created, skipped, errors }.
+     */
+    async createReferences(documentId, references) {
+        const response = await fetch(`${this.apiUrl}/api/v1/kb/documents/${documentId}/references`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+            },
+            body: JSON.stringify({ references }),
+        });
+        if (!response.ok) {
+            const body = await response.json().catch(() => ({}));
+            throw new Error(body.error || `Failed to create references: ${response.status}`);
+        }
+        return response.json();
+    }
     /**
      * List all KB databases for the tenant.
      */

package/dist/index.js

@@ -140,6 +140,85 @@ function printNotionExportSummary(log) {
         console.log('\n(Dry run - no changes made)');
     }
 }
+/**
+ * Resolve cross-references after migration.
+ *
+ * Builds a notionId → { documentId, branchId, sectionIds } mapping from results,
+ * then creates KB Reference objects for each extracted cross-reference.
+ */
+async function resolveReferences(client, results) {
+    // Build notionId → document info mapping
+    const notionIdMap = new Map();
+    for (const result of results) {
+        if (result.sourcePageId &&
+            result.documentId &&
+            result.branchId &&
+            result.sectionIds &&
+            (result.status === 'created' || result.status === 'updated')) {
+            notionIdMap.set(result.sourcePageId, {
+                documentId: result.documentId,
+                branchId: result.branchId,
+                sectionIds: result.sectionIds,
+            });
+        }
+    }
+    let totalCreated = 0;
+    let totalSkipped = 0;
+    let totalErrors = 0;
+    let unresolvedTargets = 0;
+    let invalidSectionIndexes = 0;
+    for (const result of results) {
+        if (!result.references?.length ||
+            !result.documentId ||
+            !result.branchId ||
+            !result.sectionIds) {
+            continue;
+        }
+        if (result.status !== 'created' && result.status !== 'updated') {
+            continue;
+        }
+        const refs = [];
+        for (const ref of result.references) {
+            // Resolve target Notion ID → Moxn document ID
+            const target = notionIdMap.get(ref.targetNotionId);
+            if (!target) {
+                unresolvedTargets++;
+                continue;
+            }
+            // Map sectionIndex → sourceSectionId
+            const sourceSectionId = result.sectionIds[ref.sectionIndex];
+            if (!sourceSectionId) {
+                invalidSectionIndexes++;
+                continue;
+            }
+            refs.push({
+                sourceSectionId,
+                branchId: result.branchId,
+                targetDocumentId: target.documentId,
+                displayTitle: ref.displayText || null,
+            });
+        }
+        if (refs.length === 0)
+            continue;
+        try {
+            const { created, skipped, errors } = await client.createReferences(result.documentId, refs);
+            totalCreated += created;
+            totalSkipped += skipped;
+            totalErrors += errors;
+        }
+        catch (error) {
+            console.error(`  Failed to create references for ${result.documentPath}: ${error instanceof Error ? error.message : error}`);
+            totalErrors += refs.length;
+        }
+    }
+    if (unresolvedTargets > 0) {
+        console.log(`  ${unresolvedTargets} reference(s) skipped: target page not in import scope`);
+    }
+    if (invalidSectionIndexes > 0) {
+        console.log(`  ${invalidSectionIndexes} reference(s) skipped: section index out of bounds`);
+    }
+    return { created: totalCreated, skipped: totalSkipped, errors: totalErrors };
+}
 const program = new Command();
 program
     .name('moxn-kb-migrate')
@@ -354,7 +433,17 @@ program
         }
         // Step 3: Run page migration (validate is idempotent, extract uses databaseIdMap)
         const log = await runMigration(source, migrationOptions);
-        // Step 4: Finalize databases — create columns, link entries, assign tags.
+        // Step 4: Resolve cross-references (between page migration and database finalization)
+        if (!opts.dryRun) {
+            const refsWithData = log.results.filter((r) => r.references?.length && r.sectionIds?.length);
+            if (refsWithData.length > 0) {
+                console.log(`\nResolving cross-references from ${refsWithData.length} document(s)...`);
+                const refClient = new MoxnClient(migrationOptions);
+                const refResult = await resolveReferences(refClient, log.results);
+                console.log(`  Created ${refResult.created} reference(s) (${refResult.skipped} skipped, ${refResult.errors} errors)`);
+            }
+        }
+        // Step 5: Finalize databases — create columns, link entries, assign tags.
         // Database records already exist from pre-create; this step adds schema + data.
         if (!opts.dryRun && dbImports.length > 0) {
             console.log(`\nFinalizing ${dbImports.length} database(s)...`);
@@ -537,6 +626,7 @@ async function importNotionDatabase(client, dbImport, log, options, preCreatedDb
                 const tag = await client.createTag({
                     path: tagPath,
                     color: notionColorToHex(option.color),
+                    displayName: option.name,
                 });
                 optionTagMap.set(option.name, tag.id);
                 tagIds.push(tag.id);

package/dist/sources/notion.d.ts

@@ -10,6 +10,7 @@
 import type { ExtractedDocument } from '../types.js';
 import { MigrationSource, type SourceConfig } from './base.js';
 import type { NotionPage } from './notion-api.js';
+import { type PagePathMap } from './notion-blocks.js';
 import { type ParsedDatabaseSchema } from './notion-databases.js';
 export interface NotionSourceConfig extends SourceConfig {
     token: string;
@@ -18,6 +19,15 @@ export interface NotionSourceConfig extends SourceConfig {
     /** Date filter for source pages */
     dateFilter?: import('../date-filter.js').DateFilter;
 }
+export interface PageTreeNode {
+    page: NotionPage;
+    title: string;
+    slug: string;
+    children: PageTreeNode[];
+    kbPath: string;
+    isDatabaseEntry: boolean;
+    parentDatabaseId?: string;
+}
 /** Info yielded to the migration runner for database import (post-document pass). */
 export interface NotionDatabaseImportInfo {
     notionDatabaseId: string;
@@ -62,14 +72,35 @@ export declare class NotionSource extends MigrationSource<NotionSourceConfig> {
     extract(): AsyncGenerator<ExtractedDocument, void, unknown>;
     /** Clean up temp files after migration completes. */
     cleanup(): Promise<void>;
-    private buildPageTree;
-    private getParentPageId;
+    private buildPageTreeInternal;
     private processDatabases;
     private getDatabaseParentId;
     private extractPage;
     private extractDatabaseEntry;
     private downloadSectionMedia;
 }
+/** Options for building the page tree. */
+export interface BuildPageTreeOptions {
+    rootPageId?: string;
+    maxDepth?: number;
+}
+/** Result of building the page tree. */
+export interface PageTreeResult {
+    tree: PageTreeNode[];
+    allPages: PageTreeNode[];
+    pagePathMap: PagePathMap;
+    databaseEntryPageIds: Set<string>;
+}
+/**
+ * Build a hierarchical page tree from a flat list of Notion pages.
+ *
+ * Computes kbPath for each page based on parent-child relationships,
+ * deduplicates sibling slugs, and identifies database entries.
+ *
+ * Exported so the import-orchestrator can build hierarchical paths
+ * without instantiating a full NotionSource.
+ */
+export declare function buildPageTree(pages: NotionPage[], options?: BuildPageTreeOptions): PageTreeResult;
 /**
  * Slugify a page title for use as a KB path segment.
  * Lowercase, spaces→hyphens, strip special chars, ltree-compatible.

package/dist/sources/notion.js

@@ -85,7 +85,7 @@ export class NotionSource extends MigrationSource {
         const allNotionDatabases = await this.client.searchDatabases();
         console.log(`  Found ${allNotionDatabases.length} databases.`);
         // 4. Build page tree
-        this.buildPageTree(allNotionPages);
+        this.buildPageTreeInternal(allNotionPages);
         // 5. Process databases — identify entries and build schemas
         await this.processDatabases(allNotionDatabases);
         // 6. Count and validate
@@ -169,123 +169,17 @@ export class NotionSource extends MigrationSource {
         await this.mediaDownloader.cleanup();
     }
     // ============================================
-    // Tree building
+    // Tree building (delegates to standalone function)
     // ============================================
-    buildPageTree(pages) {
-        // Build lookup maps
-        const pageById = new Map();
-        const childrenByParent = new Map();
-        for (const page of pages) {
-            const nid = normalizeId(page.id);
-            pageById.set(nid, page);
-            const parentId = this.getParentPageId(page);
-            if (parentId) {
-                const npid = normalizeId(parentId);
-                if (!childrenByParent.has(npid)) {
-                    childrenByParent.set(npid, []);
-                }
-                childrenByParent.get(npid).push(page);
-            }
-        }
-        // Identify database entries
-        for (const page of pages) {
-            if (page.parent.type === 'database_id' && page.parent.database_id) {
-                this.databaseEntryPageIds.add(normalizeId(page.id));
-            }
-        }
-        // Find root pages
-        const rootPages = [];
-        if (this.config.rootPageId) {
-            // Subtree mode: start from specified page
-            const rootId = normalizeId(this.config.rootPageId);
-            const rootPage = pageById.get(rootId);
-            if (rootPage) {
-                rootPages.push(rootPage);
-            }
-            else {
-                // Root page itself wasn't in search results — search for its children
-                const children = childrenByParent.get(rootId) ?? [];
-                rootPages.push(...children);
-            }
-        }
-        else {
-            // Full workspace mode: pages with workspace parent or no parent in our set
-            for (const page of pages) {
-                if (page.parent.type === 'workspace') {
-                    rootPages.push(page);
-                }
-                else {
-                    const parentId = this.getParentPageId(page);
-                    if (parentId && !pageById.has(normalizeId(parentId))) {
-                        // Parent is not in our page set — treat as root
-                        if (page.parent.type !== 'database_id') {
-                            rootPages.push(page);
-                        }
-                    }
-                }
-            }
-        }
-        // Build tree recursively
-        const buildNode = (page, parentPath, depth, siblingSlugCounts) => {
-            if (this.config.maxDepth !== undefined && depth > this.config.maxDepth) {
-                return null;
-            }
-            const title = getPageTitle(page);
-            let slug = slugify(title);
-            // Deduplicate sibling slugs
-            const existing = siblingSlugCounts.get(slug) ?? 0;
-            siblingSlugCounts.set(slug, existing + 1);
-            if (existing > 0) {
-                slug = `${slug}-${existing + 1}`;
-            }
-            const kbPath = parentPath ? `${parentPath}/${slug}` : slug;
-            const nid = normalizeId(page.id);
-            const isDatabaseEntry = this.databaseEntryPageIds.has(nid);
-            const node = {
-                page,
-                title,
-                slug,
-                kbPath,
-                isDatabaseEntry,
-                parentDatabaseId: page.parent.type === 'database_id' ? page.parent.database_id : undefined,
-                children: [],
-            };
-            // Register in path map
-            this.pagePathMap.set(nid, kbPath);
-            // Process children
-            const childPages = childrenByParent.get(nid) ?? [];
-            const childSlugCounts = new Map();
-            for (const childPage of childPages) {
-                const childNode = buildNode(childPage, kbPath, depth + 1, childSlugCounts);
-                if (childNode) {
-                    node.children.push(childNode);
-                }
-            }
-            return node;
-        };
-        // Build roots
-        const rootSlugCounts = new Map();
-        for (const rootPage of rootPages) {
-            const node = buildNode(rootPage, '', 0, rootSlugCounts);
-            if (node) {
-                this.pageTree.push(node);
-            }
-        }
-        // Flatten tree to depth-first list
-        const flatten = (nodes) => {
-            for (const node of nodes) {
-                this.allPages.push(node);
-                flatten(node.children);
-            }
-        };
-        flatten(this.pageTree);
-    }
-    getParentPageId(page) {
-        if (page.parent.type === 'page_id')
-            return page.parent.page_id ?? null;
-        if (page.parent.type === 'block_id')
-            return page.parent.block_id ?? null;
-        return null;
+    buildPageTreeInternal(pages) {
+        const result = buildPageTree(pages, {
+            rootPageId: this.config.rootPageId,
+            maxDepth: this.config.maxDepth,
+        });
+        this.pageTree = result.tree;
+        this.allPages = result.allPages;
+        this.pagePathMap = result.pagePathMap;
+        this.databaseEntryPageIds = result.databaseEntryPageIds;
     }
     // ============================================
     // Database processing
@@ -421,6 +315,133 @@ export class NotionSource extends MigrationSource {
         return result;
     }
 }
+/**
+ * Build a hierarchical page tree from a flat list of Notion pages.
+ *
+ * Computes kbPath for each page based on parent-child relationships,
+ * deduplicates sibling slugs, and identifies database entries.
+ *
+ * Exported so the import-orchestrator can build hierarchical paths
+ * without instantiating a full NotionSource.
+ */
+export function buildPageTree(pages, options) {
+    const pagePathMap = new Map();
+    const databaseEntryPageIds = new Set();
+    const tree = [];
+    const allPages = [];
+    // Build lookup maps
+    const pageById = new Map();
+    const childrenByParent = new Map();
+    for (const page of pages) {
+        const nid = normalizeId(page.id);
+        pageById.set(nid, page);
+        const parentId = getParentPageId(page);
+        if (parentId) {
+            const npid = normalizeId(parentId);
+            if (!childrenByParent.has(npid)) {
+                childrenByParent.set(npid, []);
+            }
+            childrenByParent.get(npid).push(page);
+        }
+    }
+    // Identify database entries
+    for (const page of pages) {
+        if (page.parent.type === 'database_id' && page.parent.database_id) {
+            databaseEntryPageIds.add(normalizeId(page.id));
+        }
+    }
+    // Find root pages
+    const rootPages = [];
+    if (options?.rootPageId) {
+        const rootId = normalizeId(options.rootPageId);
+        const rootPage = pageById.get(rootId);
+        if (rootPage) {
+            rootPages.push(rootPage);
+        }
+        else {
+            const children = childrenByParent.get(rootId) ?? [];
+            rootPages.push(...children);
+        }
+    }
+    else {
+        for (const page of pages) {
+            if (page.parent.type === 'workspace') {
+                rootPages.push(page);
+            }
+            else {
+                const parentId = getParentPageId(page);
+                if (parentId && !pageById.has(normalizeId(parentId))) {
+                    if (page.parent.type !== 'database_id') {
+                        rootPages.push(page);
+                    }
+                }
+            }
+        }
+    }
+    // Build tree recursively
+    const buildNode = (page, parentPath, depth, siblingSlugCounts) => {
+        if (options?.maxDepth !== undefined && depth > options.maxDepth) {
+            return null;
+        }
+        const title = getPageTitle(page);
+        let slug = slugify(title);
+        // Deduplicate sibling slugs
+        const existing = siblingSlugCounts.get(slug) ?? 0;
+        siblingSlugCounts.set(slug, existing + 1);
+        if (existing > 0) {
+            slug = `${slug}-${existing + 1}`;
+        }
+        const kbPath = parentPath ? `${parentPath}/${slug}` : slug;
+        const nid = normalizeId(page.id);
+        const isDatabaseEntry = databaseEntryPageIds.has(nid);
+        const node = {
+            page,
+            title,
+            slug,
+            kbPath,
+            isDatabaseEntry,
+            parentDatabaseId: page.parent.type === 'database_id' ? page.parent.database_id : undefined,
+            children: [],
+        };
+        // Register in path map
+        pagePathMap.set(nid, kbPath);
+        // Process children
+        const childPages = childrenByParent.get(nid) ?? [];
+        const childSlugCounts = new Map();
+        for (const childPage of childPages) {
+            const childNode = buildNode(childPage, kbPath, depth + 1, childSlugCounts);
+            if (childNode) {
+                node.children.push(childNode);
+            }
+        }
+        return node;
+    };
+    // Build roots
+    const rootSlugCounts = new Map();
+    for (const rootPage of rootPages) {
+        const node = buildNode(rootPage, '', 0, rootSlugCounts);
+        if (node) {
+            tree.push(node);
+        }
+    }
+    // Flatten tree to depth-first list
+    const flatten = (nodes) => {
+        for (const node of nodes) {
+            allPages.push(node);
+            flatten(node.children);
+        }
+    };
+    flatten(tree);
+    return { tree, allPages, pagePathMap, databaseEntryPageIds };
+}
+/** Extract the parent page ID from a Notion page's parent field. */
+function getParentPageId(page) {
+    if (page.parent.type === 'page_id')
+        return page.parent.page_id ?? null;
+    if (page.parent.type === 'block_id')
+        return page.parent.block_id ?? null;
+    return null;
+}
 // ============================================
 // Path helpers
 // ============================================

package/dist/targets/notion-database-export.js

@@ -292,7 +292,10 @@ async function createDatabaseEntries(ctx, dataSourceId, resolved) {
                 }
                 else {
                     // Scalar columns (number, date, text, url, email)
-                    if (propValue.textValue == null && propValue.numberValue == null && propValue.dateValue == null && propValue.booleanValue == null)
+                    if (propValue.textValue == null &&
+                        propValue.numberValue == null &&
+                        propValue.dateValue == null &&
+                        propValue.booleanValue == null)
                         continue;
                     switch (propValue.columnType) {
                         case 'number':

package/dist/types.d.ts

@@ -139,6 +139,12 @@ export interface MigrationResult {
     documentId?: string;
     branchId?: string;
     sectionsCount?: number;
+    /** Ordered section IDs from create/update response (for cross-reference resolution) */
+    sectionIds?: string[];
+    /** Cross-references extracted from source (for post-migration resolution) */
+    references?: ExtractedReference[];
+    /** Source page ID (e.g. Notion page ID) for building cross-ref mappings */
+    sourcePageId?: string;
     error?: string;
     duration?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moxn/kb-migrate",
-  "version": "0.4.20",
+  "version": "0.4.22",
   "description": "Migration tool for importing documents into Moxn Knowledge Base from local files, Notion, Google Docs, and more",
   "type": "module",
   "main": "dist/index.js",