sunsama-api 0.12.0 → 0.13.0

package/dist/esm/src/utils/conversion.js

@@ -0,0 +1,684 @@
+/**
+ * HTML ↔ Markdown Conversion Utilities
+ *
+ * This module provides utilities for converting between HTML and Markdown formats.
+ * It uses specialized libraries for optimal performance:
+ * - Turndown for HTML → Markdown conversion
+ * - Marked for Markdown → HTML conversion
+ *
+ * These utilities are particularly useful for Sunsama API task notes and comments
+ * where content can be provided in either format and needs conversion to the other.
+ */
+import { marked } from 'marked';
+import TurndownService from 'turndown';
+import { z } from 'zod';
+import { SunsamaAuthError } from '../errors/index.js';
+/**
+ * Decodes common HTML entities back to their original characters.
+ * This is needed because marked's lexer HTML-encodes some characters.
+ */
+function decodeHtmlEntities(text) {
+    return text
+        .replace(/&/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&#x27;/g, "'")
+        .replace(/&apos;/g, "'")
+        .replace(/&#(\d+);/g, (_, code) => String.fromCharCode(parseInt(code, 10)))
+        .replace(/&#x([0-9a-fA-F]+);/g, (_, code) => String.fromCharCode(parseInt(code, 16)));
+}
+/**
+ * Validation schema for HTML input
+ */
+const htmlInputSchema = z.string().trim().min(1, 'HTML content cannot be empty');
+/**
+ * Validation schema for Markdown input
+ */
+const markdownInputSchema = z.string().trim().min(1, 'Markdown content cannot be empty');
+/**
+ * Default configuration for Turndown (HTML → Markdown)
+ */
+const defaultTurndownOptions = {
+    preserveHtml: false,
+    gfm: true,
+    linkStyle: 'inlined',
+    br: '\n',
+};
+/**
+ * Default configuration for Marked (Markdown → HTML)
+ */
+const defaultMarkedOptions = {
+    sanitize: true,
+    gfm: true,
+    breaks: true,
+};
+/**
+ * Initialize Turndown service with configuration
+ */
+function createTurndownService(options = {}) {
+    const config = { ...defaultTurndownOptions, ...options };
+    const turndownService = new TurndownService({
+        headingStyle: 'atx',
+        hr: '---',
+        bulletListMarker: '-',
+        codeBlockStyle: 'fenced',
+        fence: '```',
+        emDelimiter: '*',
+        strongDelimiter: '**',
+        linkStyle: config.linkStyle,
+        linkReferenceStyle: 'full',
+        br: config.br,
+    });
+    // Add GitHub Flavored Markdown support
+    if (config.gfm) {
+        // Support for strikethrough
+        turndownService.addRule('strikethrough', {
+            filter: ['del', 's'],
+            replacement: function (content) {
+                return '~~' + content + '~~';
+            },
+        });
+        // Support for task lists
+        turndownService.addRule('taskListItems', {
+            filter: function (node) {
+                return (node.nodeName === 'LI' &&
+                    node.querySelector &&
+                    node.querySelector('input[type="checkbox"]') !== null);
+            },
+            replacement: function (content, node) {
+                const checkbox = node.querySelector
+                    ? node.querySelector('input[type="checkbox"]')
+                    : null;
+                const isChecked = checkbox && checkbox.checked;
+                return (isChecked ? '- [x] ' : '- [ ] ') + content;
+            },
+        });
+    }
+    // Apply custom rules if provided
+    if (config.customRules) {
+        Object.entries(config.customRules).forEach(([name, rule]) => {
+            turndownService.addRule(name, rule);
+        });
+    }
+    return turndownService;
+}
+/**
+ * Initialize Marked with configuration
+ */
+function configureMarked(options = {}) {
+    const config = { ...defaultMarkedOptions, ...options };
+    marked.setOptions({
+        gfm: config.gfm,
+        breaks: config.breaks,
+        // Note: sanitize option is deprecated in newer versions of marked
+        // We'll handle sanitization separately if needed
+    });
+    if (config.renderer) {
+        marked.use({ renderer: config.renderer });
+    }
+}
+/**
+ * Converts HTML content to Markdown format
+ *
+ * @param html - The HTML content to convert
+ * @param options - Configuration options for conversion
+ * @returns The converted Markdown content
+ * @throws SunsamaAuthError if input validation fails
+ *
+ * @example
+ * ```typescript
+ * const html = '<h1>Hello World</h1><p>This is <strong>bold</strong> text.</p>';
+ * const markdown = htmlToMarkdown(html);
+ * console.log(markdown); // "# Hello World\n\nThis is **bold** text."
+ * ```
+ */
+export function htmlToMarkdown(html, options = {}) {
+    try {
+        // Validate input
+        htmlInputSchema.parse(html);
+        // Create Turndown service with options
+        const turndownService = createTurndownService(options);
+        // Convert HTML to Markdown
+        const markdown = turndownService.turndown(html);
+        // Clean up the result (remove excessive whitespace)
+        return markdown.trim().replace(/\n{3,}/g, '\n\n');
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new SunsamaAuthError(`HTML to Markdown conversion failed: ${error.message}`);
+        }
+        throw new SunsamaAuthError(`HTML to Markdown conversion failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Converts Markdown content to HTML format
+ *
+ * @param markdown - The Markdown content to convert
+ * @param options - Configuration options for conversion
+ * @returns The converted HTML content
+ * @throws SunsamaAuthError if input validation fails
+ *
+ * @example
+ * ```typescript
+ * const markdown = '# Hello World\n\nThis is **bold** text.';
+ * const html = markdownToHtml(markdown);
+ * console.log(html); // "<h1>Hello World</h1>\n<p>This is <strong>bold</strong> text.</p>"
+ * ```
+ */
+export function markdownToHtml(markdown, options = {}) {
+    try {
+        // Validate input
+        markdownInputSchema.parse(markdown);
+        // Configure Marked with options
+        configureMarked(options);
+        // Convert Markdown to HTML
+        const html = marked.parse(markdown);
+        // Return the result (marked.parse returns a Promise<string> in some versions, but string in others)
+        return typeof html === 'string' ? html : html.toString();
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new SunsamaAuthError(`Markdown to HTML conversion failed: ${error.message}`);
+        }
+        throw new SunsamaAuthError(`Markdown to HTML conversion failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+}
+/**
+ * Sanitizes HTML content to prevent XSS attacks
+ * This is a basic implementation - consider using a dedicated library like DOMPurify for production
+ *
+ * @param html - The HTML content to sanitize
+ * @returns Sanitized HTML content
+ */
+export function sanitizeHtml(html) {
+    if (!html)
+        return '';
+    // Basic HTML sanitization - remove script tags and dangerous attributes
+    let sanitized = html
+        .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
+        .replace(/<iframe\b[^<]*(?:(?!<\/iframe>)<[^<]*)*<\/iframe>/gi, '')
+        .replace(/on\w+\s*=\s*"[^"]*"/gi, '')
+        .replace(/on\w+\s*=\s*'[^']*'/gi, '')
+        .replace(/on\w+\s*=\s*[^\s>]+/gi, '')
+        .replace(/javascript:/gi, '')
+        .replace(/vbscript:/gi, '')
+        .replace(/data:/gi, '');
+    // Clean up any extra spaces left behind after removing attributes
+    sanitized = sanitized.replace(/\s+>/g, '>').replace(/<\s+/g, '<');
+    return sanitized;
+}
+/**
+ * Utility function to safely convert between HTML and Markdown with validation
+ *
+ * @param content - The content to convert
+ * @param fromFormat - Source format ('html' or 'markdown')
+ * @param toFormat - Target format ('html' or 'markdown')
+ * @param options - Conversion options
+ * @returns Converted content
+ * @throws SunsamaAuthError if conversion fails or formats are invalid
+ *
+ * @example
+ * ```typescript
+ * const html = '<p>Hello <strong>world</strong></p>';
+ * const markdown = convertContent(html, 'html', 'markdown');
+ * console.log(markdown); // "Hello **world**"
+ *
+ * const convertedBack = convertContent(markdown, 'markdown', 'html');
+ * console.log(convertedBack); // "<p>Hello <strong>world</strong></p>"
+ * ```
+ */
+export function convertContent(content, fromFormat, toFormat, options = {}) {
+    if (fromFormat === toFormat) {
+        return content; // No conversion needed
+    }
+    if (fromFormat === 'html' && toFormat === 'markdown') {
+        return htmlToMarkdown(content, options.htmlToMarkdown);
+    }
+    if (fromFormat === 'markdown' && toFormat === 'html') {
+        const html = markdownToHtml(content, options.markdownToHtml);
+        return options.markdownToHtml?.sanitize !== false ? sanitizeHtml(html) : html;
+    }
+    throw new SunsamaAuthError(`Invalid conversion format: ${fromFormat} to ${toFormat}`);
+}
+/**
+ * Parses inline tokens from marked and converts them to formatted segments
+ * with Yjs-compatible attributes
+ *
+ * @param tokens - Array of marked inline tokens
+ * @param inheritedAttributes - Attributes inherited from parent elements
+ * @returns Array of formatted segments with text and attributes
+ * @internal
+ */
+function parseInlineTokens(tokens, inheritedAttributes = {}) {
+    const segments = [];
+    for (const token of tokens) {
+        switch (token.type) {
+            case 'text': {
+                const textToken = token;
+                // Handle text tokens that may have nested tokens (from inline parsing)
+                if ('tokens' in textToken && textToken.tokens && textToken.tokens.length > 0) {
+                    segments.push(...parseInlineTokens(textToken.tokens, inheritedAttributes));
+                }
+                else {
+                    const attrs = Object.keys(inheritedAttributes).length > 0 ? inheritedAttributes : undefined;
+                    segments.push({ text: decodeHtmlEntities(textToken.text), attributes: attrs });
+                }
+                break;
+            }
+            case 'strong': {
+                const strongToken = token;
+                const newAttrs = { ...inheritedAttributes, bold: true };
+                if ('tokens' in strongToken && strongToken.tokens && strongToken.tokens.length > 0) {
+                    segments.push(...parseInlineTokens(strongToken.tokens, newAttrs));
+                }
+                else {
+                    segments.push({ text: decodeHtmlEntities(strongToken.text), attributes: newAttrs });
+                }
+                break;
+            }
+            case 'em': {
+                const emToken = token;
+                const newAttrs = { ...inheritedAttributes, italic: true };
+                if ('tokens' in emToken && emToken.tokens && emToken.tokens.length > 0) {
+                    segments.push(...parseInlineTokens(emToken.tokens, newAttrs));
+                }
+                else {
+                    segments.push({ text: decodeHtmlEntities(emToken.text), attributes: newAttrs });
+                }
+                break;
+            }
+            case 'link': {
+                const linkToken = token;
+                // Sunsama expects link as a nested object with href property
+                const newAttrs = { ...inheritedAttributes, link: { href: linkToken.href } };
+                if ('tokens' in linkToken && linkToken.tokens && linkToken.tokens.length > 0) {
+                    segments.push(...parseInlineTokens(linkToken.tokens, newAttrs));
+                }
+                else {
+                    segments.push({ text: decodeHtmlEntities(linkToken.text), attributes: newAttrs });
+                }
+                break;
+            }
+            case 'codespan': {
+                const codeToken = token;
+                const newAttrs = { ...inheritedAttributes, code: true };
+                segments.push({ text: decodeHtmlEntities(codeToken.text), attributes: newAttrs });
+                break;
+            }
+            case 'del': {
+                // Note: Sunsama's editor doesn't support strikethrough marks
+                // So we render it as plain text with ~~ delimiters preserved
+                const delToken = token;
+                if ('tokens' in delToken && delToken.tokens && delToken.tokens.length > 0) {
+                    segments.push({ text: '~~' });
+                    segments.push(...parseInlineTokens(delToken.tokens, inheritedAttributes));
+                    segments.push({ text: '~~' });
+                }
+                else {
+                    segments.push({
+                        text: `~~${decodeHtmlEntities(delToken.text)}~~`,
+                        attributes: inheritedAttributes,
+                    });
+                }
+                break;
+            }
+            case 'br': {
+                segments.push({ text: '\n' });
+                break;
+            }
+            case 'escape': {
+                const escapeToken = token;
+                const attrs = Object.keys(inheritedAttributes).length > 0 ? inheritedAttributes : undefined;
+                segments.push({ text: decodeHtmlEntities(escapeToken.text), attributes: attrs });
+                break;
+            }
+            default: {
+                // For any other token types, try to extract text
+                if ('text' in token && typeof token.text === 'string') {
+                    const attrs = Object.keys(inheritedAttributes).length > 0 ? inheritedAttributes : undefined;
+                    segments.push({
+                        text: decodeHtmlEntities(token.text),
+                        attributes: attrs,
+                    });
+                }
+                else if ('raw' in token && typeof token.raw === 'string') {
+                    const attrs = Object.keys(inheritedAttributes).length > 0 ? inheritedAttributes : undefined;
+                    segments.push({ text: token.raw, attributes: attrs });
+                }
+                break;
+            }
+        }
+    }
+    return segments;
+}
+/**
+ * Parses markdown content into formatted segments suitable for Yjs XmlText insertion.
+ *
+ * This function converts markdown text into an array of segments, where each segment
+ * contains the text content and optional formatting attributes (bold, italic, link, etc.).
+ * The segments can be used to insert rich text into a Yjs document with proper formatting.
+ *
+ * @param markdown - The markdown content to parse
+ * @returns Array of formatted segments with text and Yjs-compatible attributes
+ *
+ * @example
+ * ```typescript
+ * const segments = parseMarkdownToSegments('This is **bold** and *italic* text');
+ * // Returns:
+ * // [
+ * //   { text: 'This is ' },
+ * //   { text: 'bold', attributes: { bold: true } },
+ * //   { text: ' and ' },
+ * //   { text: 'italic', attributes: { italic: true } },
+ * //   { text: ' text' }
+ * // ]
+ *
+ * const linkSegments = parseMarkdownToSegments('Visit [Google](https://google.com)');
+ * // Returns:
+ * // [
+ * //   { text: 'Visit ' },
+ * //   { text: 'Google', attributes: { link: 'https://google.com' } }
+ * // ]
+ * ```
+ */
+export function parseMarkdownToSegments(markdown) {
+    if (!markdown || markdown.trim() === '') {
+        return [];
+    }
+    const segments = [];
+    // Configure marked for GFM (GitHub Flavored Markdown) support
+    marked.setOptions({
+        gfm: true,
+        breaks: true,
+    });
+    // Tokenize the markdown
+    const tokens = marked.lexer(markdown);
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        switch (token.type) {
+            case 'paragraph': {
+                const paragraphToken = token;
+                if (paragraphToken.tokens) {
+                    segments.push(...parseInlineTokens(paragraphToken.tokens));
+                }
+                // Add newline after paragraph if not the last token
+                if (i < tokens.length - 1) {
+                    segments.push({ text: '\n' });
+                }
+                break;
+            }
+            case 'heading': {
+                const headingToken = token;
+                if (headingToken.tokens) {
+                    // Apply bold formatting to headings
+                    segments.push(...parseInlineTokens(headingToken.tokens, { bold: true }));
+                }
+                segments.push({ text: '\n' });
+                break;
+            }
+            case 'list': {
+                const listToken = token;
+                for (let j = 0; j < listToken.items.length; j++) {
+                    const item = listToken.items[j];
+                    // Add list marker
+                    const marker = listToken.ordered ? `${j + 1}. ` : '• ';
+                    segments.push({ text: marker });
+                    if (item.tokens) {
+                        // Process list item content
+                        for (const itemToken of item.tokens) {
+                            if (itemToken.type === 'text' &&
+                                'tokens' in itemToken &&
+                                itemToken.tokens) {
+                                segments.push(...parseInlineTokens(itemToken.tokens));
+                            }
+                            else if ('tokens' in itemToken && itemToken.tokens) {
+                                segments.push(...parseInlineTokens(itemToken.tokens));
+                            }
+                            else if ('text' in itemToken) {
+                                segments.push({ text: decodeHtmlEntities(itemToken.text) });
+                            }
+                        }
+                    }
+                    segments.push({ text: '\n' });
+                }
+                break;
+            }
+            case 'code': {
+                const codeToken = token;
+                segments.push({ text: decodeHtmlEntities(codeToken.text), attributes: { code: true } });
+                segments.push({ text: '\n' });
+                break;
+            }
+            case 'blockquote': {
+                const blockquoteToken = token;
+                if (blockquoteToken.tokens) {
+                    for (const innerToken of blockquoteToken.tokens) {
+                        if (innerToken.type === 'paragraph' && 'tokens' in innerToken) {
+                            segments.push({ text: '> ' });
+                            segments.push(...parseInlineTokens(innerToken.tokens));
+                            segments.push({ text: '\n' });
+                        }
+                    }
+                }
+                break;
+            }
+            case 'hr': {
+                segments.push({ text: '---\n' });
+                break;
+            }
+            case 'space': {
+                segments.push({ text: '\n' });
+                break;
+            }
+            case 'text': {
+                const textToken = token;
+                if ('tokens' in textToken && textToken.tokens) {
+                    segments.push(...parseInlineTokens(textToken.tokens));
+                }
+                else {
+                    segments.push({ text: decodeHtmlEntities(textToken.text) });
+                }
+                break;
+            }
+            default: {
+                // Handle any other token types by extracting raw text
+                if ('raw' in token && typeof token.raw === 'string') {
+                    segments.push({ text: decodeHtmlEntities(token.raw) });
+                }
+                break;
+            }
+        }
+    }
+    // Merge adjacent segments with the same attributes for efficiency
+    return mergeAdjacentSegments(segments);
+}
+/**
+ * Merges adjacent segments that have the same attributes
+ * @param segments - Array of formatted segments
+ * @returns Merged array of segments
+ * @internal
+ */
+function mergeAdjacentSegments(segments) {
+    if (segments.length === 0)
+        return [];
+    const merged = [];
+    let current = segments[0];
+    for (let i = 1; i < segments.length; i++) {
+        const next = segments[i];
+        // Check if attributes are the same (or both undefined/empty)
+        const currentAttrs = current.attributes || {};
+        const nextAttrs = next.attributes || {};
+        const attrsEqual = JSON.stringify(currentAttrs) === JSON.stringify(nextAttrs);
+        if (attrsEqual) {
+            // Merge the text
+            current = {
+                text: current.text + next.text,
+                attributes: Object.keys(currentAttrs).length > 0 ? currentAttrs : undefined,
+            };
+        }
+        else {
+            merged.push(current);
+            current = next;
+        }
+    }
+    merged.push(current);
+    return merged;
+}
+/**
+ * Parses markdown content into a document structure with block-level elements.
+ *
+ * This function converts markdown text into an array of document blocks, where each block
+ * represents a block-level element (paragraph, blockquote, horizontal rule, etc.).
+ * This structure is suitable for creating proper Yjs XmlElement hierarchies that match
+ * Sunsama's rich text editor format.
+ *
+ * @param markdown - The markdown content to parse
+ * @returns Array of document blocks representing the document structure
+ *
+ * @example
+ * ```typescript
+ * const blocks = parseMarkdownToBlocks('Hello **world**\n\n> A quote\n\n---');
+ * // Returns:
+ * // [
+ * //   { type: 'paragraph', segments: [{ text: 'Hello ' }, { text: 'world', attributes: { bold: true } }] },
+ * //   { type: 'blockquote', children: [{ type: 'paragraph', segments: [{ text: 'A quote' }] }] },
+ * //   { type: 'horizontalRule' }
+ * // ]
+ * ```
+ */
+export function parseMarkdownToBlocks(markdown) {
+    if (!markdown || markdown.trim() === '') {
+        return [];
+    }
+    const blocks = [];
+    // Configure marked for GFM support
+    marked.setOptions({
+        gfm: true,
+        breaks: true,
+    });
+    // Tokenize the markdown
+    const tokens = marked.lexer(markdown);
+    for (const token of tokens) {
+        switch (token.type) {
+            case 'paragraph': {
+                const paragraphToken = token;
+                if (paragraphToken.tokens) {
+                    const segments = parseInlineTokens(paragraphToken.tokens);
+                    if (segments.length > 0) {
+                        blocks.push({ type: 'paragraph', segments: mergeAdjacentSegments(segments) });
+                    }
+                }
+                break;
+            }
+            case 'heading': {
+                // Convert headings to bold paragraphs (Sunsama may not support native headings)
+                const headingToken = token;
+                if (headingToken.tokens) {
+                    const segments = parseInlineTokens(headingToken.tokens, { bold: true });
+                    if (segments.length > 0) {
+                        blocks.push({ type: 'paragraph', segments: mergeAdjacentSegments(segments) });
+                    }
+                }
+                break;
+            }
+            case 'blockquote': {
+                const blockquoteToken = token;
+                const children = [];
+                if (blockquoteToken.tokens) {
+                    for (const innerToken of blockquoteToken.tokens) {
+                        if (innerToken.type === 'paragraph' && 'tokens' in innerToken) {
+                            const segments = parseInlineTokens(innerToken.tokens);
+                            if (segments.length > 0) {
+                                children.push({ type: 'paragraph', segments: mergeAdjacentSegments(segments) });
+                            }
+                        }
+                    }
+                }
+                if (children.length > 0) {
+                    blocks.push({ type: 'blockquote', children });
+                }
+                break;
+            }
+            case 'hr': {
+                blocks.push({ type: 'horizontalRule' });
+                break;
+            }
+            case 'code': {
+                const codeToken = token;
+                blocks.push({
+                    type: 'codeBlock',
+                    segments: [{ text: decodeHtmlEntities(codeToken.text) }],
+                });
+                break;
+            }
+            case 'list': {
+                // Create proper list structure with listItem elements
+                const listToken = token;
+                const items = [];
+                for (const item of listToken.items) {
+                    const segments = [];
+                    if (item.tokens) {
+                        for (const itemToken of item.tokens) {
+                            if (itemToken.type === 'text' &&
+                                'tokens' in itemToken &&
+                                itemToken.tokens) {
+                                segments.push(...parseInlineTokens(itemToken.tokens));
+                            }
+                            else if ('tokens' in itemToken && itemToken.tokens) {
+                                segments.push(...parseInlineTokens(itemToken.tokens));
+                            }
+                            else if ('text' in itemToken) {
+                                segments.push({ text: decodeHtmlEntities(itemToken.text) });
+                            }
+                        }
+                    }
+                    if (segments.length > 0) {
+                        items.push({ segments: mergeAdjacentSegments(segments) });
+                    }
+                }
+                if (items.length > 0) {
+                    blocks.push({
+                        type: listToken.ordered ? 'orderedList' : 'bulletList',
+                        items,
+                        start: listToken.ordered && typeof listToken.start === 'number'
+                            ? listToken.start
+                            : undefined,
+                    });
+                }
+                break;
+            }
+            case 'space': {
+                // Skip pure space tokens - they're handled by paragraph breaks
+                break;
+            }
+            case 'text': {
+                const textToken = token;
+                const segments = [];
+                if ('tokens' in textToken && textToken.tokens) {
+                    segments.push(...parseInlineTokens(textToken.tokens));
+                }
+                else {
+                    segments.push({ text: decodeHtmlEntities(textToken.text) });
+                }
+                if (segments.length > 0) {
+                    blocks.push({ type: 'paragraph', segments: mergeAdjacentSegments(segments) });
+                }
+                break;
+            }
+            default: {
+                // Handle any other token types by extracting raw text
+                if ('raw' in token && typeof token.raw === 'string') {
+                    const raw = token.raw.trim();
+                    if (raw) {
+                        blocks.push({ type: 'paragraph', segments: [{ text: raw }] });
+                    }
+                }
+                break;
+            }
+        }
+    }
+    return blocks;
+}
+//# sourceMappingURL=conversion.js.map