\n
\n A TypeScript library that splits LLM-generated markdown into WhatsApp-friendly chat message chunks.\n
\n\n\n\n Problem •\n Quickstart •\n Features •\n Splitting Rules •\n API Reference\n
\n\n---\n\n## The Problem\n\nLLMs generate long, structured markdown responses—paragraphs, numbered lists, product cards, nested bullet points. Sending these as a single WhatsApp message creates a wall of text that users won't read.\n\nNaively splitting at character limits breaks mid-sentence, mid-list, or mid-URL. Splitting at every period creates fragmented messages that feel robotic. Neither approach understands the structure of the content.\n\nAdditionally:\n\n- **URLs, emails, and numbers contain periods.** Splitting at `Nike.com.co` or `$1.000.000` or `juan.perez@gmail.com` produces broken fragments.\n- **Lists should stay together.** A numbered list of products or a bullet list of options is a single logical unit—splitting inside an item destroys readability.\n- **Questions need context.** A short trailing question like \"¿Te interesa?\" should stay attached to the preceding sentence, not become its own tiny message.\n\nThis library handles all of this. One function call, zero configuration. Pass in the LLM's markdown output, get back an array of WhatsApp-ready message chunks.\n\n## How It Works\n\nThe library takes a markdown string and splits it into an array of smaller chunks optimized for chat readability. It applies a priority-ordered chain of processors:\n\n1. Pre-processes text (normalizes inline lists, removes periods after URLs)\n2. Tries structural splits first (intro + list, product cards, markdown sections, double newlines)\n3. Falls back to semantic splits (question marks, periods) with intelligent protection\n4. Merges chunks that are too small (<20 chars) with their neighbors\n5. Normalizes Spanish punctuation (¿/¡ capitalization rules)\n\n## Features\n\n| Feature | Description |\n| ----------------------------- | ------------------------------------------------------------------------------ |\n| **Smart Question Splitting** | Splits at question marks while keeping contiguous questions together |\n| **List Preservation** | Keeps numbered and bullet lists intact, splits only when items are very long |\n| **Product Card Detection** | Recognizes product card patterns (with emojis or markdown) and splits per card |\n| **URL/Email/Number Safety** | Never splits inside URLs, emails, domain names, or formatted numbers |\n| **Parentheses Protection** | Avoids splitting inside parenthetical expressions |\n| **Abbreviation Awareness** | Protects periods in `etc.`, `Dr.`, `D.C.`, `S.A.`, version numbers |\n| **Spanish Punctuation** | Normalizes capitalization after mid-sentence ¿ and ¡ marks |\n| **Small Chunk Merging** | Prevents tiny fragments by merging small chunks with adjacent ones |\n| **Markdown Table Support** | Converts tables to monospace blocks (small) or row-per-chunk format (wide) |\n| **Markdown Section Support** | Splits at markdown headers (`*Title*` or `_Title_`) as natural boundaries |\n| **Zero Configuration** | Single function, no setup required—just pass text, get chunks |\n\n## Quickstart\n\n```bash\nnpm install @daviddh/llm-markdown-whatsapp\n```\n\n### Basic Usage\n\n```typescript\nimport { splitChatText } from '@daviddh/llm-markdown-whatsapp';\n\nconst llmResponse = 'Thanks for reaching out. I understand your situation and I want to help you resolve it in the best way possible. You can send your product back at no extra cost. Would you prefer a full refund or an exchange for a different model?';\n\nconst chunks = splitChatText(llmResponse);\nconsole.log(chunks);\n// [\n// 'Thanks for reaching out.',\n// 'I understand your situation and I want to help you resolve it in the best way possible.',\n// 'You can send your product back at no extra cost.',\n// 'Would you prefer a full refund or an exchange for a different model?',\n// ]\n```\n\n### Lists Stay Together\n\n```typescript\nconst llmResponse = `I found these options:\n\n- Nike Pegasus Plus – High-performance running shoes for marathons and daily runs, featuring ZoomX Foam cushioning and a Flyknit upper that adapts to your foot. Available in black and a multicolor combination.\n- Nike Air Max 90 – Classic model with a waffle sole and the iconic visible Air cushioning, in neutral tones like light bone/olive/university grey.\nWhich of these models interests you the most? 😊`;\n\nconst chunks = splitChatText(llmResponse);\n// [\n// 'I found these options:',\n// '- Nike Pegasus Plus – High-performance running shoes for marathons...',\n// '- Nike Air Max 90 – Classic model with a waffle sole...',\n// 'Which of these models interests you the most? 😊',\n// ]\n```\n\n### Product Cards Split Per Card\n\n```typescript\nconst llmResponse = `I found these options:\n\n1. 🛍️ Pegasus Plus Shoes: 💵 $1.015.000\n📏 Color: Black, Glacier Blue/Mint Foam/Impact Green/Black.\n📏 Shoe Size: 43, 41, 38.\n✅ Ultra-lightweight, with ZoomX cushioning and great breathability.\n\n2. 🛍️ ISPA Sense Shoes: 💵 $804.900\n📏 Shoe Size: 38, 39, 40, 41, 42, 43.\n✅ Casual style with great comfort for daily use.\n\nWhich of these products do you like?`;\n\nconst chunks = splitChatText(llmResponse);\n// [\n// 'I found these options:',\n// '🛍️ Pegasus Plus Shoes: 💵 $1.015.000\\n📏 Color: ...\\n✅ Ultra-lightweight...',\n// '🛍️ ISPA Sense Shoes: 💵 $804.900\\n📏 Shoe Size: ...\\n✅ Casual style...',\n// 'Which of these products do you like?',\n// ]\n```\n\n### Markdown Tables\n\nTables are automatically detected and converted into WhatsApp-friendly formats. Small tables render as monospace blocks, while wide tables split each row into its own chunk.\n\n**Small table (monospace format)** — when total width is ≤ 45 characters:\n\n```typescript\nconst llmResponse = `Here are the sizes:\n\n| Size | Stock |\n| --- | --- |\n| 38 | 5 |\n| 40 | 12 |\n| 42 | 3 |`;\n\nconst chunks = splitChatText(llmResponse);\n// [\n// 'Here are the sizes:',\n// '```\\nSize Stock\\n38 5\\n40 12\\n42 3\\n```',\n// ]\n```\n\n**Wide table (row-per-chunk format)** — when total width exceeds 45 characters:\n\n```typescript\nconst llmResponse = `Here is the comparison:\n\n| Model | Description | Price |\n| --- | --- | --- |\n| Nike Pegasus | Lightweight running shoe with ZoomX | $1.015.000 |\n| Nike Air Max | Classic design with visible Air unit | $804.900 |`;\n\nconst chunks = splitChatText(llmResponse);\n// [\n// 'Here is the comparison:',\n// '*Model:* Nike Pegasus\\n*Description:* Lightweight running shoe with ZoomX\\n*Price:* $1.015.000',\n// '*Model:* Nike Air Max\\n*Description:* Classic design with visible Air unit\\n*Price:* $804.900',\n// ]\n```\n\n---\n\n## Splitting Rules\n\nThe library applies processors in priority order. The first processor that finds a valid split point wins, and the remaining text is re-evaluated from the top.\n\n### Structural Splits (highest priority)\n\n| Pattern | Behavior |\n| -------------------------- | ------------------------------------------------------------------------------------ |\n| **Intro + List** | Text ending with `:` followed by a numbered/bullet list splits after the intro |\n| **Question + Numbered List** | Short question followed by numbered options stays together as one chunk |\n| **Product Cards** | Numbered items with `🛍️` or `*Title*` formatting split into one chunk per card |\n| **List Sections** | Numbered/bullet lists kept as one chunk; split per-item only when items are >150 chars |\n| **Markdown Sections** | `*Header*` or `_Header_` with content splits at section boundaries |\n| **Section Breaks** | Double newlines (`\\n\\n`) act as natural split points |\n\n### Semantic Splits (fallback)\n\n| Pattern | Behavior |\n| -------------------------- | ------------------------------------------------------------------------------------ |\n| **Question Marks** | Splits after `?` unless followed by lowercase (sentence continuation) or emoji |\n| **Contiguous Questions** | Multiple questions without periods between them stay together |\n| **Period Splits** | Splits at `.` for text >100 chars, skipping protected positions |\n\n### Protected Content (never split inside)\n\n| Content | Examples |\n| -------------------------- | ------------------------------------------------------------------------------------ |\n| **URLs** | `https://example.com/path`, `www.site.com` |\n| **Plain Domains** | `Nike.com.co`, `shop.example.co.uk` |\n| **Emails** | `john.perez@gmail.com` |\n| **Formatted Numbers** | `$1.000.000`, `2.5.1`, `15.5` |\n| **Abbreviations** | `etc.`, `Dr.`, `D.C.`, `S.A.`, `E.U.A.` |\n| **Parenthetical Expressions** | `(street, number, ref, etc.)` |\n| **Bullet Point Content** | Content within `- item` or `• item` lines |\n\n### Post-processing\n\n- **Small Chunk Merging:** Chunks under 20 characters merge with the next chunk (or previous, if last).\n- **Spanish Punctuation:** After mid-sentence `¿` or `¡` (not at start or after `.`/`!`/`?`), the following letter is lowercased. Example: `ayudarte ¿Cómo estás?` becomes `ayudarte ¿cómo estás?`.\n\n---\n\n## API Reference\n\n### `splitChatText(text)`\n\n```typescript\nfunction splitChatText(text: string | null | undefined): string[]\n```\n\nSplits a markdown text string into an array of chat-ready chunks.\n\n- **Input:** A string of markdown text (typically an LLM response). Accepts `null` or `undefined` safely.\n- **Output:** An array of strings, each suitable for sending as an individual WhatsApp message.\n- Returns `[]` for `null`, `undefined`, or empty string.\n\n```typescript\nimport { splitChatText } from '@daviddh/llm-markdown-whatsapp';\n\nconst chunks = splitChatText(llmMarkdownText);\n```\n\n## Project Structure\n\n```\nllm-markdown-whatsapp/\n├── packages/\n│ └── core/ # Core splitting library\n│ └── src/\n│ ├── index.ts # Public API — exports splitChatText\n│ └── chatSplit/\n│ ├── splitChatText.ts # Main orchestrator\n│ ├── splitProcessors.ts # Intro + list processors\n│ ├── productCardProcessor.ts # Product card detection and splitting\n│ ├── listProcessor.ts # Numbered/bullet list processing\n│ ├── paragraphProcessor.ts # Long paragraph and markdown sections\n│ ├── breakProcessor.ts # Double newline section breaks\n│ ├── questionProcessor.ts # Question mark splitting logic\n│ ├── periodProcessor.ts # Period splitting with protected ranges\n│ ├── mergeProcessor.ts # Small chunk merging\n│ ├── sections.ts # Markdown/list section detection\n│ ├── textHelpers.ts # Smart trim, emoji detection, text utilities\n│ ├── positionHelpers.ts # Parentheses/bullet position checks\n│ ├── listNormalization.ts # Inline list normalization\n│ ├── urlNormalization.ts # URL period removal\n│ ├── punctuationNormalization.ts # Spanish ¿/¡ capitalization\n│ ├── constants.ts # Threshold constants\n│ └── splitConstants.ts # Split-specific constants\n└── README.md\n```\n\n\n\n## Architecture\n\n```mermaid\nflowchart TB\n subgraph Input[\"Input\"]\n T[\"LLM markdown text\"]\n end\n\n Input --> Pre\n\n subgraph Pre[\"Pre-processing\"]\n direction LR\n A[\"Normalize\n Built with TypeScript • Zero Dependencies • WhatsApp-Optimized Chat Splitting\n
\n","readmeFilename":"README.md"}