@moxn/kb-migrate 0.4.29 → 0.4.31

package/dist/sources/notion-api.js

@@ -182,9 +182,7 @@ export class NotionApiClient {
             catch (fetchError) {
                 // Network-level failure (DNS, TCP reset, timeout, etc.)
                 lastError =
-                    fetchError instanceof Error
-                        ? fetchError
-                        : new Error(String(fetchError));
+                    fetchError instanceof Error ? fetchError : new Error(String(fetchError));
                 if (attempt < MAX_RETRIES) {
                     const delay = Math.min(1000 * Math.pow(2, attempt), 30000);
                     console.warn(`Network error: ${lastError.message}. Retrying in ${delay}ms (attempt ${attempt + 1}/${MAX_RETRIES})`);

package/dist/sources/onenote/__tests__/onenote-html.test.d.ts

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

package/dist/sources/onenote/__tests__/onenote-html.test.js

@@ -0,0 +1,234 @@
+import { readFile } from 'fs/promises';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import { describe, expect, it } from 'vitest';
+import { convertOneNoteHtmlToSections, } from '../onenote-html.js';
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixtureDir = join(__dirname, 'fixtures');
+async function loadFixture(name) {
+    return readFile(join(fixtureDir, name), 'utf8');
+}
+/** Stubs every image/attachment to a predictable storage key. */
+const storageResolver = async (ctx) => {
+    const ext = ctx.kind === 'image' ? 'png' : 'bin';
+    const hash = ctx.url.split('/').slice(-2, -1)[0] ?? 'anon';
+    const key = `kb/onenote/test/${hash}.${ext}`;
+    const mediaType = ctx.declaredMimeType ??
+        (ctx.kind === 'image' ? 'image/png' : 'application/octet-stream');
+    return {
+        key,
+        mediaType,
+        filename: ctx.declaredFilename,
+    };
+};
+describe('convertOneNoteHtmlToSections', () => {
+    it('extracts title and splits sections at H2 boundaries', async () => {
+        const html = await loadFixture('simple-page.html');
+        const result = await convertOneNoteHtmlToSections(html, {
+            resolveMedia: storageResolver,
+        });
+        expect(result.title).toBe('AAPL — Long Thesis');
+        expect(result.sections.map((s) => s.name)).toEqual([
+            'Introduction',
+            'Thesis',
+            'Risks',
+        ]);
+        // Pre-H2 content (after the title H1) goes in Introduction
+        const intro = result.sections[0];
+        expect(intro.content).toHaveLength(1);
+        expect(intro.content[0].blockType).toBe('text');
+        if (intro.content[0].blockType === 'text') {
+            expect(intro.content[0].text).toContain('high-quality compounder');
+            // Bold preserved as markdown
+            expect(intro.content[0].text).toMatch(/\*\*high-quality compounder\*\*/);
+        }
+        // Thesis section has paragraph + bullet list
+        const thesis = result.sections[1];
+        const thesisText = thesis.content
+            .filter((b) => b.blockType === 'text')
+            .map((b) => b.text)
+            .join('\n');
+        expect(thesisText).toContain('Services mix shift');
+        expect(thesisText).toContain('- Installed base of 2.2B devices');
+        expect(thesisText).toContain('- Services revenue growing 14% YoY');
+        // Risks section
+        expect(result.sections[2].content).toHaveLength(1);
+    });
+    it('maps note-tags to task items and emoji prefixes', async () => {
+        const html = await loadFixture('todo-tags.html');
+        const result = await convertOneNoteHtmlToSections(html, {
+            resolveMedia: storageResolver,
+        });
+        // Only one section because no H2
+        expect(result.sections).toHaveLength(1);
+        const lines = result.sections[0].content
+            .filter((b) => b.blockType === 'text')
+            .map((b) => b.text)
+            .join('\n')
+            .split('\n');
+        expect(lines).toContainEqual(expect.stringMatching(/^- \[ \] Pull quarterly/));
+        expect(lines).toContainEqual(expect.stringMatching(/^- \[x\] Re-read/));
+        expect(lines).toContainEqual(expect.stringMatching(/^⭐ Position sizing/));
+        expect(lines).toContainEqual(expect.stringMatching(/^❓ Does the hyperscaler/));
+        expect(lines).toContainEqual(expect.stringMatching(/^💡 Pair trade/));
+        expect(lines).toContainEqual(expect.stringContaining('Plain paragraph'));
+    });
+    it('renders tables as GitHub-style markdown and re-hosts media', async () => {
+        const html = await loadFixture('table-with-media.html');
+        const resolverCalls = [];
+        const spyResolver = async (ctx) => {
+            resolverCalls.push({
+                kind: ctx.kind,
+                url: ctx.url,
+                filename: ctx.declaredFilename,
+            });
+            return storageResolver(ctx);
+        };
+        const result = await convertOneNoteHtmlToSections(html, {
+            resolveMedia: spyResolver,
+        });
+        // Section split: Introduction (table) / Charts (image) / Sellside (attachment)
+        expect(result.sections.map((s) => s.name)).toEqual([
+            'Introduction',
+            'Charts',
+            'Sellside',
+        ]);
+        // Table rendered in Introduction
+        const introText = result.sections[0].content
+            .filter((b) => b.blockType === 'text')
+            .map((b) => b.text)
+            .join('\n');
+        expect(introText).toContain('| Ticker | Thesis | Conviction | Target size |');
+        expect(introText).toContain('| NVDA |');
+        expect(introText).toContain('| AAPL |');
+        // Image block in Charts section
+        const charts = result.sections[1];
+        const imageBlock = charts.content.find((b) => b.blockType === 'image');
+        expect(imageBlock).toBeDefined();
+        if (imageBlock && imageBlock.blockType === 'image' && imageBlock.type === 'storage') {
+            expect(imageBlock.key).toMatch(/kb\/onenote\/test\/abc-123\./);
+            expect(imageBlock.mediaType).toBe('image/png');
+            expect(imageBlock.alt).toBe('semis relative performance');
+        }
+        else {
+            throw new Error('expected storage-keyed image block');
+        }
+        // Attachment block in Sellside section — PDF maps to document
+        const sellside = result.sections[2];
+        const docBlock = sellside.content.find((b) => b.blockType === 'document');
+        expect(docBlock).toBeDefined();
+        if (docBlock && docBlock.blockType === 'document' && docBlock.type === 'storage') {
+            expect(docBlock.mediaType).toBe('application/pdf');
+            expect(docBlock.filename).toBe('gs-semis-call.pdf');
+        }
+        else {
+            throw new Error('expected storage-keyed document block');
+        }
+        // Resolver was called for both media items
+        expect(resolverCalls).toHaveLength(2);
+        expect(resolverCalls[0].kind).toBe('image');
+        expect(resolverCalls[1].kind).toBe('file');
+        expect(resolverCalls[1].filename).toBe('gs-semis-call.pdf');
+        expect(result.mediaCount).toBe(2);
+    });
+    it('extracts OneNote cross-page references and preserves external links', async () => {
+        const html = await loadFixture('crosslinks.html');
+        const result = await convertOneNoteHtmlToSections(html, {
+            resolveMedia: storageResolver,
+        });
+        // Three refs expected: the onenote:// URI, the Graph URL. External skipped.
+        const refIds = result.extractedReferences.map((r) => r.targetOnenotePageId);
+        expect(refIds).toContain('1-def456');
+        expect(refIds).toContain('1-aapl789');
+        expect(refIds).not.toContain('www.example.com');
+        // Display text preserved
+        const nvdaRef = result.extractedReferences.find((r) => r.targetOnenotePageId === '1-def456');
+        expect(nvdaRef?.displayText).toBe('NVDA thesis');
+        // Section index is 0 for all (no H2 split in fixture)
+        expect(result.extractedReferences.every((r) => r.sectionIndex === 0)).toBe(true);
+        // External link rendered as plain markdown
+        const intro = result.sections[0].content
+            .filter((b) => b.blockType === 'text')
+            .map((b) => b.text)
+            .join('\n');
+        expect(intro).toContain('[Example report](https://www.example.com/report)');
+    });
+    it('handles citation footers as blockquotes by default', async () => {
+        const html = await loadFixture('citation-footer.html');
+        const result = await convertOneNoteHtmlToSections(html, {
+            resolveMedia: storageResolver,
+        });
+        const text = result.sections[0].content
+            .filter((b) => b.blockType === 'text')
+            .map((b) => b.text)
+            .join('\n\n');
+        expect(text).toContain('> From <');
+        expect(text).toContain('More of our own notes');
+    });
+    it('drops citation footers when configured', async () => {
+        const html = await loadFixture('citation-footer.html');
+        const result = await convertOneNoteHtmlToSections(html, {
+            resolveMedia: storageResolver,
+            dropCitations: true,
+        });
+        const text = result.sections[0].content
+            .filter((b) => b.blockType === 'text')
+            .map((b) => b.text)
+            .join('\n\n');
+        expect(text).not.toContain('From <');
+        expect(text).toContain('decelerated but remains above');
+    });
+    it('skips embeds when resolver returns null and records a reason', async () => {
+        const html = await loadFixture('table-with-media.html');
+        const nullResolver = async () => null;
+        const result = await convertOneNoteHtmlToSections(html, {
+            resolveMedia: nullResolver,
+        });
+        // No media blocks
+        expect(result.mediaCount).toBe(0);
+        expect(result.skippedItemCount).toBe(2);
+        expect(result.skippedReasons.length).toBe(2);
+        expect(result.skippedReasons.some((r) => r.includes('gs-semis-call.pdf'))).toBe(true);
+        // Sections still created, just without the media blocks
+        expect(result.sections.map((s) => s.name)).toEqual([
+            'Introduction',
+            'Charts',
+            'Sellside',
+        ]);
+    });
+    it('sorts absolute-positioned canvas children by (top, left)', async () => {
+        const html = `<html><body data-absolute-enabled="true">
+      <div style="position:absolute;top:400px;left:50px"><p>Third</p></div>
+      <div style="position:absolute;top:100px;left:50px"><p>First</p></div>
+      <div style="position:absolute;top:100px;left:300px"><p>Second</p></div>
+    </body></html>`;
+        const result = await convertOneNoteHtmlToSections(html, {
+            resolveMedia: storageResolver,
+        });
+        const text = result.sections[0].content
+            .filter((b) => b.blockType === 'text')
+            .map((b) => b.text)
+            .join('\n\n');
+        const firstIdx = text.indexOf('First');
+        const secondIdx = text.indexOf('Second');
+        const thirdIdx = text.indexOf('Third');
+        expect(firstIdx).toBeLessThan(secondIdx);
+        expect(secondIdx).toBeLessThan(thirdIdx);
+    });
+    it('renders nothing gracefully for an empty page', async () => {
+        const result = await convertOneNoteHtmlToSections('<html><head><title>Empty</title></head><body></body></html>', { resolveMedia: storageResolver });
+        expect(result.title).toBe('Empty');
+        expect(result.sections).toHaveLength(1);
+        expect(result.sections[0].content).toHaveLength(0);
+    });
+});
+describe('slugifyPathSegment + joinKbPath', () => {
+    it('slug round-trips realistic names', async () => {
+        const { slugifyPathSegment, joinKbPath } = await import('../onenote-tree.js');
+        expect(slugifyPathSegment('AAPL — Long Thesis')).toBe('aapl-long-thesis');
+        expect(slugifyPathSegment('Meeting Notes / 2026-04-22')).toBe('meeting-notes-2026-04-22');
+        expect(slugifyPathSegment('   ')).toBe('untitled');
+        expect(slugifyPathSegment('weird.stuff_here')).toBe('weird-stuff-here');
+        expect(joinKbPath('imported/onenote', 'research', undefined, 'aapl')).toBe('/imported/onenote/research/aapl');
+    });
+});

package/dist/sources/onenote/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * OneNote source barrel. Re-exports the pieces the trigger task and
+ * server-side code need.
+ */
+export { OneNoteApiClient } from './onenote-api.js';
+export type { OneNoteApiClientOptions } from './onenote-api.js';
+export { exchangeCodeForTokens, getAccessTokenSilent, buildAuthorizeUrl, generatePkcePair, generateOAuthState, ONENOTE_READ_SCOPES, ONENOTE_GRAPH_SCOPE, } from './onenote-auth.js';
+export type { OneNoteOAuthConfig, CodeExchangeResult, SilentTokenResult, PkcePair, } from './onenote-auth.js';
+export { discoverOneNotePages, slugifyPathSegment, joinKbPath, } from './onenote-tree.js';
+export type { DiscoverOptions } from './onenote-tree.js';
+export { convertOneNoteHtmlToSections } from './onenote-html.js';
+export type { ConvertOptions, ResolveMediaFn, ResolveMediaContext, ResolvedMedia, MediaKind, } from './onenote-html.js';
+export type { OneNoteNotebook, OneNoteSection, OneNoteSectionGroup, OneNotePage, DiscoveredOneNotePage, OneNoteExtractedReference, ConvertedOneNotePage, } from './types.js';

package/dist/sources/onenote/index.js

@@ -0,0 +1,8 @@
+/**
+ * OneNote source barrel. Re-exports the pieces the trigger task and
+ * server-side code need.
+ */
+export { OneNoteApiClient } from './onenote-api.js';
+export { exchangeCodeForTokens, getAccessTokenSilent, buildAuthorizeUrl, generatePkcePair, generateOAuthState, ONENOTE_READ_SCOPES, ONENOTE_GRAPH_SCOPE, } from './onenote-auth.js';
+export { discoverOneNotePages, slugifyPathSegment, joinKbPath, } from './onenote-tree.js';
+export { convertOneNoteHtmlToSections } from './onenote-html.js';

package/dist/sources/onenote/onenote-api.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Microsoft Graph OneNote client.
+ *
+ * Thin wrapper over fetch — no @microsoft/microsoft-graph-client dependency in
+ * this module (we only use MSAL-node for tokens). Graph's OneNote endpoints
+ * are simple enough that a hand-rolled client is cheaper than the SDK and
+ * gives us precise control over 429 handling.
+ */
+import type { OneNoteNotebook, OneNotePage, OneNoteSection, OneNoteSectionGroup } from './types.js';
+export interface OneNoteApiClientOptions {
+    /** Alternate base URL — for testing only. */
+    baseUrl?: string;
+    /** Override the userPrincipalName or `me` slug. Default: `me`. */
+    userSlug?: string;
+}
+export declare class OneNoteApiClient {
+    private readonly token;
+    private readonly baseUrl;
+    private readonly userSlug;
+    constructor(accessToken: string, options?: OneNoteApiClientOptions);
+    /** Minimal whoami used during OAuth to capture display metadata. */
+    getMe(): Promise<{
+        displayName?: string;
+        userPrincipalName?: string;
+        mail?: string;
+        id: string;
+    }>;
+    listNotebooks(): Promise<OneNoteNotebook[]>;
+    listSectionGroups(notebookId: string): Promise<OneNoteSectionGroup[]>;
+    /** Nested groups (groups inside groups). Graph supports recursion one level. */
+    listNestedSectionGroups(sectionGroupId: string): Promise<OneNoteSectionGroup[]>;
+    listSectionsInNotebook(notebookId: string): Promise<OneNoteSection[]>;
+    listSectionsInGroup(sectionGroupId: string): Promise<OneNoteSection[]>;
+    listPages(sectionId: string, options?: {
+        modifiedAfter?: Date;
+        modifiedBefore?: Date;
+    }): Promise<OneNotePage[]>;
+    getPage(pageId: string): Promise<OneNotePage>;
+    /**
+     * Get the HTML content of a page. `includeIDs=true` stamps every element
+     * with a `data-id`, which we use for stable cross-link targets.
+     */
+    getPageContent(pageId: string): Promise<{
+        html: string;
+        etag?: string;
+    }>;
+    /** Fetch a binary resource (image or file attachment). */
+    getResource(resourceId: string): Promise<{
+        buffer: Buffer;
+        contentType: string;
+    }>;
+    /**
+     * Fetch a resource from its full Graph URL — simpler than parsing out
+     * the resource ID, handy when HTML embeds `src="https://graph.microsoft..."`.
+     */
+    getResourceByUrl(url: string): Promise<{
+        buffer: Buffer;
+        contentType: string;
+    }>;
+    private paginate;
+    private requestJson;
+    private requestRaw;
+}

package/dist/sources/onenote/onenote-api.js

@@ -0,0 +1,147 @@
+/**
+ * Microsoft Graph OneNote client.
+ *
+ * Thin wrapper over fetch — no @microsoft/microsoft-graph-client dependency in
+ * this module (we only use MSAL-node for tokens). Graph's OneNote endpoints
+ * are simple enough that a hand-rolled client is cheaper than the SDK and
+ * gives us precise control over 429 handling.
+ */
+const GRAPH_BASE = 'https://graph.microsoft.com/v1.0';
+const MAX_RETRIES = 5;
+const DEFAULT_PAGE_SIZE = 100;
+export class OneNoteApiClient {
+    token;
+    baseUrl;
+    userSlug;
+    constructor(accessToken, options = {}) {
+        this.token = accessToken;
+        this.baseUrl = options.baseUrl ?? GRAPH_BASE;
+        this.userSlug = options.userSlug ?? 'me';
+    }
+    // -----------------------------------------------------------------
+    // Listings
+    // -----------------------------------------------------------------
+    /** Minimal whoami used during OAuth to capture display metadata. */
+    async getMe() {
+        return this.requestJson(`${this.baseUrl}/me?$select=id,displayName,userPrincipalName,mail`);
+    }
+    async listNotebooks() {
+        return this.paginate(`${this.baseUrl}/${this.userSlug}/onenote/notebooks?$top=${DEFAULT_PAGE_SIZE}`);
+    }
+    async listSectionGroups(notebookId) {
+        return this.paginate(`${this.baseUrl}/${this.userSlug}/onenote/notebooks/${encodeURIComponent(notebookId)}/sectionGroups?$top=${DEFAULT_PAGE_SIZE}`);
+    }
+    /** Nested groups (groups inside groups). Graph supports recursion one level. */
+    async listNestedSectionGroups(sectionGroupId) {
+        return this.paginate(`${this.baseUrl}/${this.userSlug}/onenote/sectionGroups/${encodeURIComponent(sectionGroupId)}/sectionGroups?$top=${DEFAULT_PAGE_SIZE}`);
+    }
+    async listSectionsInNotebook(notebookId) {
+        return this.paginate(`${this.baseUrl}/${this.userSlug}/onenote/notebooks/${encodeURIComponent(notebookId)}/sections?$top=${DEFAULT_PAGE_SIZE}`);
+    }
+    async listSectionsInGroup(sectionGroupId) {
+        return this.paginate(`${this.baseUrl}/${this.userSlug}/onenote/sectionGroups/${encodeURIComponent(sectionGroupId)}/sections?$top=${DEFAULT_PAGE_SIZE}`);
+    }
+    async listPages(sectionId, options) {
+        const select = '$select=id,title,lastModifiedDateTime,links';
+        const filters = [];
+        if (options?.modifiedAfter) {
+            filters.push(`lastModifiedDateTime ge ${options.modifiedAfter.toISOString()}`);
+        }
+        if (options?.modifiedBefore) {
+            filters.push(`lastModifiedDateTime le ${options.modifiedBefore.toISOString()}`);
+        }
+        const filter = filters.length ? `&$filter=${encodeURIComponent(filters.join(' and '))}` : '';
+        return this.paginate(`${this.baseUrl}/${this.userSlug}/onenote/sections/${encodeURIComponent(sectionId)}/pages?$top=${DEFAULT_PAGE_SIZE}${filter}${filter ? '' : ''}&${select.slice(1)}`);
+    }
+    async getPage(pageId) {
+        return this.requestJson(`${this.baseUrl}/${this.userSlug}/onenote/pages/${encodeURIComponent(pageId)}`);
+    }
+    /**
+     * Get the HTML content of a page. `includeIDs=true` stamps every element
+     * with a `data-id`, which we use for stable cross-link targets.
+     */
+    async getPageContent(pageId) {
+        const response = await this.requestRaw(`${this.baseUrl}/${this.userSlug}/onenote/pages/${encodeURIComponent(pageId)}/content?includeIDs=true`);
+        const html = await response.text();
+        const etag = response.headers.get('etag') ?? undefined;
+        return { html, etag };
+    }
+    /** Fetch a binary resource (image or file attachment). */
+    async getResource(resourceId) {
+        const response = await this.requestRaw(`${this.baseUrl}/${this.userSlug}/onenote/resources/${encodeURIComponent(resourceId)}/$value`);
+        const arr = await response.arrayBuffer();
+        const contentType = response.headers.get('content-type') ?? 'application/octet-stream';
+        return { buffer: Buffer.from(arr), contentType };
+    }
+    /**
+     * Fetch a resource from its full Graph URL — simpler than parsing out
+     * the resource ID, handy when HTML embeds `src="https://graph.microsoft..."`.
+     */
+    async getResourceByUrl(url) {
+        const response = await this.requestRaw(url);
+        const arr = await response.arrayBuffer();
+        const contentType = response.headers.get('content-type') ?? 'application/octet-stream';
+        return { buffer: Buffer.from(arr), contentType };
+    }
+    // -----------------------------------------------------------------
+    // HTTP internals
+    // -----------------------------------------------------------------
+    async paginate(firstUrl) {
+        const results = [];
+        let url = firstUrl;
+        while (url) {
+            const resp = await this.requestJson(url);
+            results.push(...(resp.value ?? []));
+            url = resp['@odata.nextLink'];
+        }
+        return results;
+    }
+    async requestJson(url) {
+        const response = await this.requestRaw(url);
+        return (await response.json());
+    }
+    async requestRaw(url) {
+        let lastError = null;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            let response;
+            try {
+                response = await fetch(url, {
+                    method: 'GET',
+                    headers: {
+                        Authorization: `Bearer ${this.token}`,
+                        Accept: 'application/json',
+                    },
+                });
+            }
+            catch (err) {
+                // Network-level failure — retry with exponential backoff
+                lastError = err instanceof Error ? err : new Error(String(err));
+                if (attempt < MAX_RETRIES) {
+                    await sleep(Math.min(1000 * 2 ** attempt, 30000));
+                    continue;
+                }
+                throw lastError;
+            }
+            if (response.ok)
+                return response;
+            if (response.status === 429 || response.status >= 500) {
+                const retryAfter = parseInt(response.headers.get('Retry-After') ?? '', 10);
+                const baseDelay = Number.isFinite(retryAfter) && retryAfter > 0
+                    ? retryAfter * 1000
+                    : 1000 * 2 ** attempt;
+                const delay = Math.min(baseDelay, 30000);
+                lastError = new Error(`Graph API ${response.status} on ${url} — retrying in ${delay}ms`);
+                if (attempt < MAX_RETRIES) {
+                    await sleep(delay);
+                    continue;
+                }
+            }
+            const errorBody = await response.text().catch(() => '');
+            throw new Error(`Graph API ${response.status} on ${url}: ${errorBody.slice(0, 400)}`);
+        }
+        throw lastError ?? new Error(`Graph API request failed after ${MAX_RETRIES} retries`);
+    }
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/sources/onenote/onenote-auth.d.ts

@@ -0,0 +1,83 @@
+/**
+ * MSAL wrapper for OneNote / Microsoft Graph OAuth.
+ *
+ * We use MSAL's ConfidentialClientApplication and let it handle:
+ *   - code-for-token exchange
+ *   - silent refresh via the stored token cache
+ *   - cache serialization
+ *
+ * The serialized cache JSON is what we persist (encrypted) in
+ * kb_integration_credentials. On each use we deserialize, call MSAL, and
+ * write back any updated cache.
+ */
+export interface OneNoteOAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    /** Usually "common" for multi-tenant + personal MSA */
+    tenant: string;
+    redirectUri: string;
+}
+/**
+ * Scopes we request. Read-only for v1 (see plan §OAuth design).
+ * `User.Read` is needed only during the initial code exchange to populate
+ * the credential metadata (displayName, email) — after that MSAL doesn't
+ * need it to refresh the OneNote access token.
+ */
+export declare const ONENOTE_READ_SCOPES: string[];
+export declare const ONENOTE_GRAPH_SCOPE: string[];
+export interface CodeExchangeResult {
+    accessToken: string;
+    /** Opaque MSAL cache JSON to persist encrypted. */
+    cacheBlob: string;
+    /** MSAL's "home account" identifier — use to retrieve the account later. */
+    accountId: string;
+    /** UPN (email) from the id_token, for display. */
+    userPrincipalName?: string;
+    tenantId?: string;
+    displayName?: string;
+    expiresOn?: string;
+}
+/**
+ * Exchange an authorization code (plus PKCE verifier) for tokens, and return
+ * an encrypted-cache-ready payload. Called once from the OAuth callback.
+ */
+export declare function exchangeCodeForTokens(cfg: OneNoteOAuthConfig, params: {
+    code: string;
+    codeVerifier: string;
+    /** Scopes the authorize URL requested. */
+    scopes?: string[];
+}): Promise<CodeExchangeResult>;
+export interface SilentTokenResult {
+    accessToken: string;
+    /**
+     * If MSAL updated the internal cache during this call (e.g. refreshed the
+     * access token), the new serialized blob. Caller should persist it.
+     * Null when the cache was unchanged.
+     */
+    updatedCacheBlob: string | null;
+    expiresOn?: string;
+}
+/**
+ * Silently acquire an access token using a persisted MSAL cache.
+ * Auto-refreshes if the access token is expired (needs offline_access in cache).
+ */
+export declare function getAccessTokenSilent(cfg: OneNoteOAuthConfig, params: {
+    cacheBlob: string;
+    accountId: string;
+    scopes?: string[];
+}): Promise<SilentTokenResult>;
+/**
+ * Build the Microsoft authorize URL for the popup/redirect. Called from
+ * the "Connect OneNote" server action.
+ */
+export declare function buildAuthorizeUrl(cfg: OneNoteOAuthConfig, params: {
+    state: string;
+    codeChallenge: string;
+    scopes?: string[];
+}): Promise<string>;
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+}
+export declare function generatePkcePair(): PkcePair;
+export declare function generateOAuthState(): string;