@kaelio/ktx 0.13.1 → 0.15.0

package/dist/context/ingest/adapters/gdrive/detect.js

@@ -0,0 +1,20 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+export async function detectGdriveStagedDir(stagedDir) {
+    try {
+        const manifest = JSON.parse(await readFile(join(stagedDir, 'manifest.json'), 'utf-8'));
+        if (manifest.source === 'gdrive') {
+            return true;
+        }
+    }
+    catch {
+        // Fall through to structural detection.
+    }
+    try {
+        const entries = await readdir(stagedDir, { withFileTypes: true, recursive: true });
+        return entries.some((entry) => entry.isFile() && entry.name === 'page.md');
+    }
+    catch {
+        return false;
+    }
+}

package/dist/context/ingest/adapters/gdrive/fetch.d.ts

@@ -0,0 +1,6 @@
+import type { GdriveManifest, GdrivePullConfig } from './types.js';
+export declare function fetchGdriveSnapshot(params: {
+    key: unknown;
+    config: GdrivePullConfig;
+    stagedDir: string;
+}): Promise<GdriveManifest>;

package/dist/context/ingest/adapters/gdrive/fetch.js

@@ -0,0 +1,95 @@
+import { createHash } from 'node:crypto';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { createGoogleDocsClients, driveFolderChildrenQuery } from './gdrive-client.js';
+import { normalizeGoogleDocToMarkdown } from './normalize.js';
+import { GDRIVE_DOC_MIME_TYPE, GDRIVE_FOLDER_MIME_TYPE, GDRIVE_SOURCE_KEY } from './types.js';
+async function writeJson(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+}
+async function writeText(path, value) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, value.endsWith('\n') ? value : `${value}\n`, 'utf-8');
+}
+function slugifySegment(value) {
+    const normalized = value
+        .normalize('NFKD')
+        .replace(/[^\x00-\x7F]/g, '')
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+    return normalized || 'untitled';
+}
+function compactSegment(value, maxLength = 24) {
+    const slug = slugifySegment(value);
+    return slug.length > maxLength ? slug.slice(0, maxLength).replace(/-+$/g, '') || 'untitled' : slug;
+}
+function shortHash(value, length = 10) {
+    return createHash('sha1').update(value).digest('hex').slice(0, length);
+}
+function gdriveDocDirName(title, fileId) {
+    return `${compactSegment(title)}-${shortHash(fileId)}`;
+}
+async function listFolderFiles(drive, folderId, recursive, parents = []) {
+    const q = driveFolderChildrenQuery(folderId);
+    const docs = [];
+    const skipped = [];
+    let pageToken;
+    do {
+        const page = await drive.listFiles({ q, pageToken });
+        for (const file of page.files) {
+            if (file.mimeType === GDRIVE_FOLDER_MIME_TYPE) {
+                if (recursive) {
+                    const nested = await listFolderFiles(drive, file.id, true, [...parents, file.name]);
+                    docs.push(...nested.docs);
+                    skipped.push(...nested.skipped);
+                }
+                continue;
+            }
+            if (file.mimeType !== GDRIVE_DOC_MIME_TYPE) {
+                skipped.push({ externalId: file.id, reason: `unsupported mime type: ${file.mimeType}` });
+                continue;
+            }
+            docs.push({ file, drivePath: parents, folderId });
+        }
+        pageToken = page.nextPageToken ?? undefined;
+    } while (pageToken);
+    return { docs, skipped };
+}
+export async function fetchGdriveSnapshot(params) {
+    await mkdir(params.stagedDir, { recursive: true });
+    const clients = createGoogleDocsClients(params.key);
+    const { docs, skipped } = await listFolderFiles(clients.drive, params.config.folderId, params.config.recursive);
+    for (const { file, drivePath, folderId } of docs) {
+        const document = await clients.docs.getDocument(file.id);
+        const title = (document.title?.trim() || file.name).trim();
+        const relDir = join('docs', ...drivePath.map((segment) => compactSegment(segment)), gdriveDocDirName(title, file.id));
+        const markdownBody = normalizeGoogleDocToMarkdown(document);
+        const pageMarkdown = [`# ${title}`, markdownBody].filter(Boolean).join('\n\n');
+        await writeJson(join(params.stagedDir, relDir, 'metadata.json'), {
+            id: file.id,
+            title,
+            path: [...drivePath, title].join(' / ') || title,
+            url: file.webViewLink,
+            mimeType: file.mimeType,
+            folderId,
+            drivePath,
+            modifiedTime: file.modifiedTime,
+        });
+        await writeText(join(params.stagedDir, relDir, 'page.md'), pageMarkdown);
+    }
+    const manifest = {
+        source: GDRIVE_SOURCE_KEY,
+        folderId: params.config.folderId,
+        recursive: params.config.recursive,
+        fetchedAt: new Date().toISOString(),
+        fileCount: docs.length,
+        skipped,
+        warnings: skipped.length > 0
+            ? [`Skipped ${skipped.length} non-Google-Doc file(s); only Google Docs are ingested in v1.`]
+            : [],
+    };
+    await writeJson(join(params.stagedDir, 'manifest.json'), manifest);
+    return manifest;
+}

package/dist/context/ingest/adapters/gdrive/gdrive-client.d.ts

@@ -0,0 +1,30 @@
+import type { GdriveFileRecord, GoogleDocsDocument } from './types.js';
+export interface GoogleDriveClient {
+    listFiles(args: {
+        q: string;
+        pageToken?: string;
+    }): Promise<{
+        files: GdriveFileRecord[];
+        nextPageToken: string | null;
+    }>;
+    getFile(fileId: string): Promise<GdriveFileRecord | null>;
+}
+export interface GoogleDocsClients {
+    drive: GoogleDriveClient;
+    docs: {
+        getDocument(documentId: string): Promise<GoogleDocsDocument>;
+    };
+}
+/** @internal Retries transient Google API responses (429/5xx) honoring Retry-After. */
+export declare function fetchWithGoogleRetry(doFetch: () => Promise<Response>, options?: {
+    maxAttempts?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<Response>;
+/** Builds the Drive query for the non-trashed direct children of a folder, escaping the folder id. */
+export declare function driveFolderChildrenQuery(folderId: string): string;
+/**
+ * Confirms `folderId` resolves to a folder the service account can read, then counts the
+ * Google Docs directly inside it. Throws a caller-facing error when the id is missing or not a folder.
+ */
+export declare function verifyGdriveFolderAndCountDocs(drive: GoogleDriveClient, folderId: string): Promise<number>;
+export declare function createGoogleDocsClients(rawKey: unknown): GoogleDocsClients;

package/dist/context/ingest/adapters/gdrive/gdrive-client.js

@@ -0,0 +1,132 @@
+import { JWT } from 'google-auth-library';
+import { GDRIVE_DOC_MIME_TYPE, GDRIVE_FOLDER_MIME_TYPE, GDRIVE_SCOPES, gdriveServiceAccountKeySchema } from './types.js';
+const GOOGLE_DRIVE_BASE_URL = 'https://www.googleapis.com/drive/v3';
+const GOOGLE_DOCS_BASE_URL = 'https://docs.googleapis.com/v1';
+const GOOGLE_FILE_FIELDS = 'id,name,mimeType,parents,webViewLink,modifiedTime';
+const RETRYABLE_STATUSES = new Set([408, 429, 500, 502, 503, 504]);
+const MAX_REQUEST_ATTEMPTS = 4;
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function retryDelayMs(attempt, retryAfterHeader) {
+    const retryAfterSeconds = retryAfterHeader ? Number.parseInt(retryAfterHeader, 10) : Number.NaN;
+    if (Number.isFinite(retryAfterSeconds) && retryAfterSeconds >= 0) {
+        return Math.min(retryAfterSeconds * 1000, 30_000);
+    }
+    return Math.min(500 * 2 ** attempt, 8_000);
+}
+/** @internal Retries transient Google API responses (429/5xx) honoring Retry-After. */
+export async function fetchWithGoogleRetry(doFetch, options = {}) {
+    const maxAttempts = options.maxAttempts ?? MAX_REQUEST_ATTEMPTS;
+    const sleep = options.sleep ?? defaultSleep;
+    let response = await doFetch();
+    for (let attempt = 1; attempt < maxAttempts && !response.ok && RETRYABLE_STATUSES.has(response.status); attempt += 1) {
+        await sleep(retryDelayMs(attempt - 1, response.headers.get('retry-after')));
+        response = await doFetch();
+    }
+    return response;
+}
+async function parseGoogleResponse(response) {
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`Google API request failed (${response.status}): ${body || response.statusText}`);
+    }
+    return (await response.json());
+}
+async function authorizedFetch(client, url) {
+    return fetchWithGoogleRetry(async () => {
+        const headers = await client.getRequestHeaders(url);
+        return fetch(url, { headers });
+    });
+}
+function isGoogleApiFileRecord(file) {
+    return typeof file.id === 'string' && typeof file.name === 'string' && typeof file.mimeType === 'string';
+}
+function toFileRecord(file) {
+    return {
+        id: file.id,
+        name: file.name,
+        mimeType: file.mimeType,
+        parents: Array.isArray(file.parents) ? file.parents.filter((parent) => typeof parent === 'string') : [],
+        webViewLink: typeof file.webViewLink === 'string' ? file.webViewLink : null,
+        modifiedTime: typeof file.modifiedTime === 'string' ? file.modifiedTime : null,
+    };
+}
+function escapeDriveQueryValue(value) {
+    return value.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
+}
+/** Builds the Drive query for the non-trashed direct children of a folder, escaping the folder id. */
+export function driveFolderChildrenQuery(folderId) {
+    return `'${escapeDriveQueryValue(folderId)}' in parents and trashed = false`;
+}
+/**
+ * Confirms `folderId` resolves to a folder the service account can read, then counts the
+ * Google Docs directly inside it. Throws a caller-facing error when the id is missing or not a folder.
+ */
+export async function verifyGdriveFolderAndCountDocs(drive, folderId) {
+    const folder = await drive.getFile(folderId);
+    if (!folder) {
+        throw new Error(`Google Drive folder "${folderId}" is not accessible. Share it with the service account email and verify folder_id.`);
+    }
+    if (folder.mimeType !== GDRIVE_FOLDER_MIME_TYPE) {
+        throw new Error(`Google Drive id "${folderId}" is not a folder (mimeType: ${folder.mimeType}).`);
+    }
+    const q = driveFolderChildrenQuery(folderId);
+    let docs = 0;
+    let pageToken;
+    do {
+        const page = await drive.listFiles({ q, pageToken });
+        docs += page.files.filter((file) => file.mimeType === GDRIVE_DOC_MIME_TYPE).length;
+        pageToken = page.nextPageToken ?? undefined;
+    } while (pageToken);
+    return docs;
+}
+export function createGoogleDocsClients(rawKey) {
+    const key = gdriveServiceAccountKeySchema.parse(rawKey);
+    const client = new JWT({
+        email: key.client_email,
+        key: key.private_key,
+        scopes: [...GDRIVE_SCOPES],
+    });
+    return {
+        drive: {
+            async listFiles(args) {
+                const params = new URLSearchParams({
+                    q: args.q,
+                    supportsAllDrives: 'true',
+                    includeItemsFromAllDrives: 'true',
+                    pageSize: '1000',
+                    fields: `nextPageToken,files(${GOOGLE_FILE_FIELDS})`,
+                });
+                if (args.pageToken) {
+                    params.set('pageToken', args.pageToken);
+                }
+                const response = await authorizedFetch(client, `${GOOGLE_DRIVE_BASE_URL}/files?${params.toString()}`);
+                const parsed = await parseGoogleResponse(response);
+                return {
+                    files: (parsed.files ?? []).filter(isGoogleApiFileRecord).map(toFileRecord),
+                    nextPageToken: typeof parsed.nextPageToken === 'string' ? parsed.nextPageToken : null,
+                };
+            },
+            async getFile(fileId) {
+                const params = new URLSearchParams({ supportsAllDrives: 'true', fields: GOOGLE_FILE_FIELDS });
+                const response = await authorizedFetch(client, `${GOOGLE_DRIVE_BASE_URL}/files/${encodeURIComponent(fileId)}?${params.toString()}`);
+                if (response.status === 404) {
+                    return null;
+                }
+                const file = await parseGoogleResponse(response);
+                return isGoogleApiFileRecord(file) ? toFileRecord(file) : null;
+            },
+        },
+        docs: {
+            async getDocument(documentId) {
+                const params = new URLSearchParams({
+                    includeTabsContent: 'true',
+                    suggestionsViewMode: 'PREVIEW_WITHOUT_SUGGESTIONS',
+                });
+                const response = await authorizedFetch(client, `${GOOGLE_DOCS_BASE_URL}/documents/${documentId}?${params.toString()}`);
+                return await parseGoogleResponse(response);
+            },
+        },
+    };
+}

package/dist/context/ingest/adapters/gdrive/gdrive.adapter.d.ts

@@ -0,0 +1,11 @@
+import type { ChunkResult, DiffSet, FetchContext, ScopeDescriptor, SourceAdapter } from '../../types.js';
+export declare class GdriveSourceAdapter implements SourceAdapter {
+    readonly source = "gdrive";
+    readonly skillNames: string[];
+    readonly reconcileSkillNames: string[];
+    readonly evidenceIndexing: "documents";
+    detect(stagedDir: string): Promise<boolean>;
+    fetch(pullConfig: unknown, stagedDir: string, _ctx: FetchContext): Promise<void>;
+    chunk(stagedDir: string, diffSet?: DiffSet): Promise<ChunkResult>;
+    describeScope(stagedDir: string): Promise<ScopeDescriptor>;
+}

package/dist/context/ingest/adapters/gdrive/gdrive.adapter.js

@@ -0,0 +1,27 @@
+import { chunkGdriveStagedDir, describeGdriveScope } from './chunk.js';
+import { detectGdriveStagedDir } from './detect.js';
+import { fetchGdriveSnapshot } from './fetch.js';
+import { gdrivePullConfigSchema } from './types.js';
+export class GdriveSourceAdapter {
+    source = 'gdrive';
+    skillNames = ['gdrive_synthesize'];
+    reconcileSkillNames = [];
+    evidenceIndexing = 'documents';
+    detect(stagedDir) {
+        return detectGdriveStagedDir(stagedDir);
+    }
+    async fetch(pullConfig, stagedDir, _ctx) {
+        const config = gdrivePullConfigSchema.parse(pullConfig);
+        await fetchGdriveSnapshot({
+            key: JSON.parse(config.serviceAccountKey),
+            config,
+            stagedDir,
+        });
+    }
+    chunk(stagedDir, diffSet) {
+        return chunkGdriveStagedDir(stagedDir, diffSet);
+    }
+    describeScope(stagedDir) {
+        return describeGdriveScope(stagedDir);
+    }
+}

package/dist/context/ingest/adapters/gdrive/normalize.d.ts

@@ -0,0 +1,2 @@
+import type { GoogleDocsDocument } from './types.js';
+export declare function normalizeGoogleDocToMarkdown(document: GoogleDocsDocument): string;

package/dist/context/ingest/adapters/gdrive/normalize.js

@@ -0,0 +1,256 @@
+function escapeMarkdownText(value) {
+    return value.replace(/([*_~`])/g, '\\$1');
+}
+function normalizeInternalLinkTarget(prefix, target) {
+    const id = typeof target === 'string' ? target : target?.id;
+    if (!id?.trim()) {
+        return null;
+    }
+    return `#${prefix}-${id.trim()}`;
+}
+function resolveLinkHref(element) {
+    const link = element.textRun?.textStyle?.link;
+    const href = link?.url?.trim();
+    if (href) {
+        return href;
+    }
+    return (normalizeInternalLinkTarget('heading', link?.heading) ??
+        normalizeInternalLinkTarget('heading', link?.headingId) ??
+        normalizeInternalLinkTarget('bookmark', link?.bookmark) ??
+        normalizeInternalLinkTarget('bookmark', link?.bookmarkId) ??
+        null);
+}
+function normalizeTextRun(element) {
+    const content = element.textRun?.content ?? '';
+    const style = element.textRun?.textStyle;
+    let text = escapeMarkdownText(content.replace(/\r/g, ''));
+    if (!text && element.inlineObjectElement) {
+        return '[Embedded object]';
+    }
+    if (!text && element.pageBreak) {
+        return '\n---\n';
+    }
+    if (!text) {
+        return '';
+    }
+    const href = resolveLinkHref(element);
+    const isCode = style?.weightedFontFamily?.fontFamily === 'Courier New';
+    if (isCode) {
+        text = `\`${text.replace(/`/g, '\\`')}\``;
+    }
+    if (style?.bold) {
+        text = `**${text}**`;
+    }
+    if (style?.italic) {
+        text = `*${text}*`;
+    }
+    if (style?.underline) {
+        text = `<u>${text}</u>`;
+    }
+    if (style?.strikethrough) {
+        text = `~~${text}~~`;
+    }
+    if (href) {
+        text = `[${text}](${href.replace(/\)/g, '\\)')})`;
+    }
+    if (style?.baselineOffset === 'SUPERSCRIPT') {
+        text = `<sup>${text}</sup>`;
+    }
+    else if (style?.baselineOffset === 'SUBSCRIPT') {
+        text = `<sub>${text}</sub>`;
+    }
+    return text;
+}
+function paragraphText(paragraph) {
+    return (paragraph?.elements ?? [])
+        .map((element) => normalizeTextRun(element))
+        .join('')
+        .replace(/\n/g, '')
+        .trim();
+}
+function headingPrefix(namedStyleType) {
+    if (namedStyleType === 'TITLE') {
+        return '#';
+    }
+    if (namedStyleType === 'SUBTITLE') {
+        return '##';
+    }
+    if (!namedStyleType?.startsWith('HEADING_')) {
+        return null;
+    }
+    const level = Number.parseInt(namedStyleType.slice('HEADING_'.length), 10);
+    if (Number.isNaN(level) || level < 1) {
+        return null;
+    }
+    return '#'.repeat(Math.min(level, 6));
+}
+function isOrderedListLevel(level) {
+    const glyphType = level?.glyphType?.toUpperCase();
+    if (glyphType) {
+        return (glyphType.includes('NUMBER') ||
+            glyphType.includes('DECIMAL') ||
+            glyphType.includes('ALPHA') ||
+            glyphType.includes('ROMAN') ||
+            glyphType.includes('LATIN'));
+    }
+    const glyphSymbol = level?.glyphSymbol?.trim();
+    return glyphSymbol === '%0.' || glyphSymbol === '%0)' || glyphSymbol === '1.' || glyphSymbol === '1)';
+}
+function listPrefix(paragraph, lists) {
+    if (!paragraph.bullet) {
+        return null;
+    }
+    const level = Math.max(paragraph.bullet.nestingLevel ?? 0, 0);
+    const indent = '  '.repeat(level);
+    const listDefinition = paragraph.bullet.listId ? lists?.[paragraph.bullet.listId] : undefined;
+    const listLevel = listDefinition?.listProperties?.nestingLevels?.[level];
+    return `${indent}${isOrderedListLevel(listLevel) ? '1. ' : '- '}`;
+}
+function paragraphToMarkdown(paragraph, lists) {
+    const text = paragraphText(paragraph);
+    if (!text) {
+        return null;
+    }
+    const prefix = paragraph ? listPrefix(paragraph, lists) : null;
+    if (prefix) {
+        return `${prefix}${text}`;
+    }
+    const heading = headingPrefix(paragraph?.paragraphStyle?.namedStyleType);
+    if (heading) {
+        const headingLine = `${heading} ${text}`;
+        const headingId = paragraph?.paragraphStyle?.headingId?.trim();
+        return headingId ? `<a id="heading-${headingId}"></a>\n${headingLine}` : headingLine;
+    }
+    return text;
+}
+function normalizeTableCell(cell, lists) {
+    const blocks = normalizeStructuralElements(cell?.content ?? [], lists);
+    return blocks
+        .map((block) => block.replace(/\n/g, ' <br> '))
+        .join(' / ')
+        .replace(/\|/g, '\\|')
+        .trim();
+}
+function markdownTableDivider(columnCount) {
+    return `| ${Array.from({ length: columnCount }, () => '---').join(' | ')} |`;
+}
+function normalizeTable(table, lists) {
+    const rows = table?.tableRows ?? [];
+    const normalizedRows = rows
+        .map((row) => (row.tableCells ?? []).map((cell) => normalizeTableCell(cell, lists)))
+        .filter((cells) => cells.length > 0);
+    if (normalizedRows.length === 0) {
+        return [];
+    }
+    const columnCount = Math.max(...normalizedRows.map((cells) => cells.length));
+    const paddedRows = normalizedRows.map((cells) => Array.from({ length: columnCount }, (_, index) => cells[index] ?? ''));
+    const [header, ...body] = paddedRows;
+    const blocks = [`| ${header.join(' | ')} |`, markdownTableDivider(columnCount)];
+    for (const row of body) {
+        blocks.push(`| ${row.join(' | ')} |`);
+    }
+    return [blocks.join('\n')];
+}
+function normalizeStructuralElements(elements, lists) {
+    const blocks = [];
+    for (const element of elements) {
+        const line = paragraphToMarkdown(element.paragraph, lists);
+        if (line) {
+            blocks.push(line);
+            continue;
+        }
+        if (element.table) {
+            blocks.push(...normalizeTable(element.table, lists));
+        }
+    }
+    return blocks;
+}
+function headerFooterRoleMap(label, documentStyle) {
+    const roleMap = new Map();
+    const roleEntries = label === 'Headers'
+        ? [
+            [documentStyle?.defaultHeaderId, 'Default Header'],
+            [documentStyle?.firstPageHeaderId, 'First Page Header'],
+            [documentStyle?.evenPageHeaderId, 'Even Page Header'],
+        ]
+        : [
+            [documentStyle?.defaultFooterId, 'Default Footer'],
+            [documentStyle?.firstPageFooterId, 'First Page Footer'],
+            [documentStyle?.evenPageFooterId, 'Even Page Footer'],
+        ];
+    for (const [id, role] of roleEntries) {
+        const normalizedId = id?.trim();
+        if (!normalizedId || roleMap.has(normalizedId)) {
+            continue;
+        }
+        roleMap.set(normalizedId, role ?? normalizedId);
+    }
+    return roleMap;
+}
+function normalizeHeaderFooterMap(label, entries, lists, documentStyle) {
+    if (!entries) {
+        return null;
+    }
+    const ids = Object.keys(entries).sort();
+    const roles = headerFooterRoleMap(label, documentStyle);
+    const sections = [];
+    for (const id of ids) {
+        const blocks = normalizeStructuralElements(entries[id]?.content ?? [], lists);
+        if (blocks.length === 0) {
+            continue;
+        }
+        const title = roles.get(id) ?? `${label.slice(0, -1)} ${escapeMarkdownText(id)}`;
+        sections.push(`### ${title}\n\n${blocks.join('\n\n').trim()}`);
+    }
+    if (sections.length === 0) {
+        return null;
+    }
+    return `## ${label}\n\n${sections.join('\n\n').trim()}`;
+}
+function joinNonEmptySections(sections) {
+    const nonEmpty = sections.filter((section) => Boolean(section?.trim()));
+    if (nonEmpty.length === 0) {
+        return null;
+    }
+    return nonEmpty.join('\n\n').trim();
+}
+function flattenGoogleDocsTabs(tabs) {
+    if (!tabs?.length) {
+        return [];
+    }
+    const flattened = [];
+    for (const tab of tabs) {
+        flattened.push(tab);
+        flattened.push(...flattenGoogleDocsTabs(tab.childTabs));
+    }
+    return flattened;
+}
+function normalizeTab(tab, fallbackLists) {
+    const lists = tab.documentTab?.lists ?? fallbackLists;
+    const headerSection = normalizeHeaderFooterMap('Headers', tab.documentTab?.headers, lists, tab.documentTab?.documentStyle);
+    const bodySection = normalizeStructuralElements(tab.documentTab?.body?.content ?? [], lists).join('\n\n').trim();
+    const footerSection = normalizeHeaderFooterMap('Footers', tab.documentTab?.footers, lists, tab.documentTab?.documentStyle);
+    const content = joinNonEmptySections([headerSection, bodySection, footerSection]);
+    if (!content) {
+        return null;
+    }
+    const title = tab.tabProperties?.title?.trim();
+    if (!title) {
+        return content;
+    }
+    return [`# ${escapeMarkdownText(title)}`, content].join('\n\n').trim();
+}
+export function normalizeGoogleDocToMarkdown(document) {
+    const normalizedTabs = flattenGoogleDocsTabs(document.tabs)
+        .map((tab) => normalizeTab(tab, document.lists))
+        .filter((tab) => Boolean(tab));
+    if (normalizedTabs.length > 0) {
+        return normalizedTabs.join('\n\n').trim();
+    }
+    const bodySection = normalizeStructuralElements(document.body?.content ?? [], document.lists).join('\n\n').trim();
+    return (joinNonEmptySections([
+        normalizeHeaderFooterMap('Headers', document.headers, document.lists, document.documentStyle),
+        bodySection,
+        normalizeHeaderFooterMap('Footers', document.footers, document.lists, document.documentStyle),
+    ]) ?? '');
+}