writr 5.0.4 → 6.0.1

package/README.md

@@ -2,6 +2,7 @@
 
 # Markdown Rendering Simplified
 [![tests](https://github.com/jaredwray/writr/actions/workflows/tests.yml/badge.svg)](https://github.com/jaredwray/writr/actions/workflows/tests.yml)
+[![ai-integration-tests](https://github.com/jaredwray/writr/actions/workflows/ai-integration-tests.yml/badge.svg)](https://github.com/jaredwray/writr/actions/workflows/ai-integration-tests.yml)
 [![GitHub license](https://img.shields.io/github/license/jaredwray/writr)](https://github.com/jaredwray/writr/blob/master/LICENSE)
 [![codecov](https://codecov.io/gh/jaredwray/writr/branch/master/graph/badge.svg?token=1YdMesM07X)](https://codecov.io/gh/jaredwray/writr)
 [![npm](https://img.shields.io/npm/dm/writr)](https://npmjs.com/package/writr)
@@ -22,21 +23,13 @@
 * Emoji Support (remark-emoji).
 * MDX Support (remark-mdx).
 * Built in Hooks for adding code to render pipeline.
-
-# Unified Processor Engine
-
-Writr builds on top of the open source [unified](https://github.com/unifiedjs/unified) processor – the core project that powers
-[remark](https://github.com/remarkjs/remark), [rehype](https://github.com/rehypejs/rehype), and many other content tools. Unified
-provides a pluggable pipeline where each plugin transforms a syntax tree. Writr configures a default set of plugins to turn
-Markdown into HTML, but you can access the processor through the `.engine` property to add your own behavior with
-`writr.engine.use(myPlugin)`. The [unified documentation](https://unifiedjs.com/) has more details and guides for building
-plugins and working with the processor directly.
+* AI-powered metadata generation, SEO, and translation via the [Vercel AI SDK](https://sdk.vercel.ai).
 
 # Table of Contents
-- [Unified Processor Engine](#unified-processor-engine)
 - [Getting Started](#getting-started)
 - [API](#api)
   - [`new Writr(arg?: string | WritrOptions, options?: WritrOptions)`](#new-writrarg-string--writroptions-options-writroptions)
+  - [`.ai`](#writrai)
   - [`.content`](#content)
   - [`.body`](#body)
   - [`.options`](#options)
@@ -68,6 +61,19 @@ plugins and working with the processor directly.
   - [Methods that Emit Errors](#methods-that-emit-errors)
   - [Error Event Examples](#error-event-examples)
   - [Event Emitter Methods](#event-emitter-methods)
+- [AI](#ai)
+  - [AI Options](#ai-options)
+  - [AI Provider Configuration](#ai-provider-configuration)
+  - [Metadata](#metadata)
+    - [Generating Metadata](#generating-metadata)
+    - [Applying Metadata to Frontmatter](#applying-metadata-to-frontmatter)
+    - [Overwrite](#overwrite)
+    - [Field Mapping](#field-mapping)
+  - [SEO](#seo)
+  - [Translation](#translation)
+  - [Using WritrAI Directly](#using-writrai-directly)
+- [Migrating to v6](#migrating-to-v6)
+- [Unified Processor Engine](#unified-processor-engine)
 - [Benchmarks](#benchmarks)
 - [ESM and Node Version Support](#esm-and-node-version-support)
 - [Code of Conduct and Contributing](#code-of-conduct-and-contributing)
@@ -104,7 +110,6 @@ An example passing in the options also via the constructor:
 ```javascript
 import { Writr, WritrOptions } from 'writr';
 const writrOptions = {
-  throwErrors: true,
   renderOptions: {
     emoji: true,
     toc: true,
@@ -129,7 +134,6 @@ By default the constructor takes in a markdown `string` or `WritrOptions` in the
 ```javascript
 import { Writr, WritrOptions } from 'writr';
 const writrOptions = {
-  throwErrors: true,
   renderOptions: {
     emoji: true,
     toc: true,
@@ -178,7 +182,6 @@ Accessing the default options for this instance of Writr. Here is the default se
 
 ```javascript
 {
-  throwErrors: false,
   renderOptions: {
     emoji: true,
     toc: true,
@@ -186,8 +189,8 @@ Accessing the default options for this instance of Writr. Here is the default se
     highlight: true,
     gfm: true,
     math: true,
-    mdx: true,
-    caching: false,
+    mdx: false,
+    caching: true,
   }
 }
 ```
@@ -335,7 +338,7 @@ console.log(writr.content); // Still "# Hello World\n\nThis is a test."
 const invalidWritr = new Writr('Put invalid markdown here');
 const errorResult = await invalidWritr.validate();
 console.log(errorResult.valid); // false
-console.log(errorResult.error?.message); // "Failed to render markdown: Invalid plugin"
+console.log(errorResult.error?.message); // "Invalid plugin"
 ```
 
 ## `.validateSync(content?: string, options?: RenderOptions)`
@@ -623,38 +626,35 @@ writr.on('error', (error) => {
   // Log to error tracking service, display to user, etc.
 });
 
-// Now when any error occurs, your listener will be notified
-try {
-  await writr.render();
-} catch (error) {
-  // Error is also thrown, so you can handle it here too
-}
+// With a listener registered, errors are emitted to the listener
+// and the method returns its fallback value (e.g. "" for render)
+const html = await writr.render();
 ```
 
 ### Methods that Emit Errors
 
-The following methods emit error events when they fail:
+All methods use an emit-only error pattern — they call `this.emit('error', error)` but never explicitly re-throw. If no error listener is registered and `throwOnEmptyListeners` is `true` (the default), the `emit('error')` call itself will throw, following standard Node.js EventEmitter behavior.
 
-**Rendering Methods:**
-- `render()` - Emits error before throwing when markdown rendering fails
-- `renderSync()` - Emits error before throwing when markdown rendering fails
-- `renderReact()` - Emits error before throwing when React rendering fails
-- `renderReactSync()` - Emits error before throwing when React rendering fails
+**Rendering Methods** — emit error, return `""`:
+- `render()` - Emits error when markdown rendering fails, returns empty string
+- `renderSync()` - Emits error when markdown rendering fails, returns empty string
+- `renderReact()` - Emits error when React rendering fails, returns empty string
+- `renderReactSync()` - Emits error when React rendering fails, returns empty string
 
 **Validation Methods:**
-- `validate()` - Emits error when validation fails (returns error in result object)
-- `validateSync()` - Emits error when validation fails (returns error in result object)
-
-**File Operations:**
-- `renderToFile()` - Emits error when file writing fails (does not throw if `throwErrors: false`)
-- `renderToFileSync()` - Emits error when file writing fails (does not throw if `throwErrors: false`)
-- `loadFromFile()` - Emits error when file reading fails (does not throw if `throwErrors: false`)
-- `loadFromFileSync()` - Emits error when file reading fails (does not throw if `throwErrors: false`)
-- `saveToFile()` - Emits error when file writing fails (does not throw if `throwErrors: false`)
-- `saveToFileSync()` - Emits error when file writing fails (does not throw if `throwErrors: false`)
-
-**Front Matter Operations:**
-- `frontMatter` getter - Emits error when YAML parsing fails
+- `validate()` - Does **not** emit errors. Returns `{ valid: false, error }` on failure
+- `validateSync()` - Emits error and returns `{ valid: false, error }` on failure
+
+**File Operations** — emit error, return void:
+- `renderToFile()` - Emits error when rendering or file writing fails
+- `renderToFileSync()` - Emits error when rendering or file writing fails
+- `loadFromFile()` - Emits error when file reading fails
+- `loadFromFileSync()` - Emits error when file reading fails
+- `saveToFile()` - Emits error when file writing fails
+- `saveToFileSync()` - Emits error when file writing fails
+
+**Front Matter Operations** — emit error, return fallback:
+- `frontMatter` getter - Emits error when YAML parsing fails, returns `{}`
 - `frontMatter` setter - Emits error when YAML serialization fails
 
 ### Error Event Examples
@@ -706,15 +706,16 @@ if (!result.valid) {
 ```javascript
 import { Writr } from 'writr';
 
-const writr = new Writr('# Content', { throwErrors: false });
+const writr = new Writr('# Content');
 
 writr.on('error', (error) => {
   console.error('File operation failed:', error.message);
   // Handle gracefully - maybe use default content
 });
 
-// Won't throw, but will emit error event if file doesn't exist
+// With a listener registered, errors are emitted and the method returns normally
 await writr.loadFromFile('./maybe-missing.md');
+// Note: without a listener, this will throw by default (throwOnEmptyListeners is true)
 ```
 
 ### Event Emitter Methods
@@ -728,6 +729,319 @@ Since Writr extends Hookified, you have access to standard event emitter methods
 
 For more information about event handling capabilities, see the [Hookified documentation](https://github.com/jaredwray/hookified).
 
+# AI
+
+Writr includes built-in AI capabilities for metadata generation, SEO, and translation powered by the [Vercel AI SDK](https://sdk.vercel.ai). Plug in any supported model provider (OpenAI, Anthropic, Google, etc.) via the `ai` option.
+
+```typescript
+import { Writr } from 'writr';
+import { openai } from '@ai-sdk/openai';
+
+const writr = new Writr('# My Document\n\nSome markdown content here.', {
+  ai: { model: openai('gpt-4.1-mini') },
+});
+
+// Generate metadata
+const metadata = await writr.ai.getMetadata();
+
+// Generate only specific fields
+const metadata = await writr.ai.getMetadata({ title: true, description: true });
+
+// Generate SEO metadata
+const seo = await writr.ai.getSEO();
+
+// Translate to Spanish
+const translated = await writr.ai.getTranslation({ to: 'es' });
+
+// Apply generated metadata to frontmatter
+const result = await writr.ai.applyMetadata({
+  generate: { description: true, category: true },
+  overwrite: true,
+});
+```
+
+## AI Options
+
+Pass `ai` in the `WritrOptions` to enable AI features:
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `model` | `LanguageModel` | Yes | The AI SDK model instance (e.g. `openai("gpt-4.1-mini")`). |
+| `cache` | `boolean` | No | Enables in-memory caching of AI results. |
+| `prompts` | `WritrAIPrompts` | No | Custom prompt overrides for metadata, SEO, and translation. |
+
+```typescript
+const writr = new Writr('# My Document', {
+  ai: {
+    model: openai('gpt-4.1-mini'),
+    cache: true,
+  },
+});
+```
+
+## AI Provider Configuration
+
+By default, the provider imports read API keys from environment variables:
+
+| Provider | Import | Environment Variable |
+|----------|--------|---------------------|
+| OpenAI | `openai` from `@ai-sdk/openai` | `OPENAI_API_KEY` |
+| Anthropic | `anthropic` from `@ai-sdk/anthropic` | `ANTHROPIC_API_KEY` |
+| Google | `google` from `@ai-sdk/google` | `GOOGLE_GENERATIVE_AI_API_KEY` |
+
+```typescript
+// Uses OPENAI_API_KEY from environment
+import { openai } from '@ai-sdk/openai';
+
+const writr = new Writr('# Hello', { ai: { model: openai('gpt-4.1-mini') } });
+```
+
+To set API keys programmatically, use the provider factory functions instead:
+
+```typescript
+import { Writr } from 'writr';
+import { createOpenAI } from '@ai-sdk/openai';
+import { createAnthropic } from '@ai-sdk/anthropic';
+import { createGoogleGenerativeAI } from '@ai-sdk/google';
+
+// OpenAI
+const openai = createOpenAI({ apiKey: 'your-openai-key' });
+const writr = new Writr('# Hello', { ai: { model: openai('gpt-4.1-mini') } });
+
+// Anthropic
+const anthropic = createAnthropic({ apiKey: 'your-anthropic-key' });
+const writr = new Writr('# Hello', { ai: { model: anthropic('claude-sonnet-4-20250514') } });
+
+// Google
+const google = createGoogleGenerativeAI({ apiKey: 'your-google-key' });
+const writr = new Writr('# Hello', { ai: { model: google('gemini-2.0-flash') } });
+```
+
+## Metadata
+
+Generate metadata from your document content using `writr.ai.getMetadata()`, or generate and apply it directly to frontmatter with `writr.ai.applyMetadata()`.
+
+### Generating Metadata
+
+`getMetadata()` analyzes the document and returns a `WritrMetadata` object. By default all fields are generated. Pass options to select specific fields.
+
+```typescript
+// Generate all metadata fields
+const metadata = await writr.ai.getMetadata();
+console.log(metadata.title);       // "Getting Started with Writr"
+console.log(metadata.tags);        // ["markdown", "rendering", "typescript"]
+console.log(metadata.description); // "A guide to using Writr for markdown processing."
+console.log(metadata.readingTime); // 3 (minutes)
+console.log(metadata.wordCount);   // 450
+
+// Generate only specific fields
+const partial = await writr.ai.getMetadata({
+  title: true,
+  description: true,
+  tags: true,
+});
+```
+
+**Generated fields:**
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | The best-fit title for the document. |
+| `description` | `string` | A concise meta-style description of the document. |
+| `tags` | `string[]` | Human-friendly labels for organizing the document. |
+| `keywords` | `string[]` | Search-oriented terms related to the document content. |
+| `preview` | `string` | A short teaser or preview snippet of the content. |
+| `summary` | `string` | A slightly longer overview of the document. |
+| `category` | `string` | A broad grouping such as "docs", "guide", or "blog". |
+| `topic` | `string` | The primary subject the document is about. |
+| `audience` | `string` | The intended audience for the document. |
+| `difficulty` | `"beginner" \| "intermediate" \| "advanced"` | The estimated skill level required. |
+| `readingTime` | `number` | Estimated reading time in minutes (computed, not AI-generated). |
+| `wordCount` | `number` | Total word count of the document (computed, not AI-generated). |
+
+### Applying Metadata to Frontmatter
+
+`applyMetadata()` generates metadata and writes it into the document's frontmatter. The result tells you exactly what happened:
+
+- **`applied`** — fields that were newly written because they were missing from frontmatter.
+- **`skipped`** — fields that already existed and were not overwritten.
+- **`overwritten`** — fields that replaced existing frontmatter values.
+
+```typescript
+const result = await writr.ai.applyMetadata();
+console.log(result.applied);     // ["description", "tags", "category"]
+console.log(result.skipped);     // ["title"] (already existed)
+console.log(result.overwritten); // []
+```
+
+### Overwrite
+
+By default, `applyMetadata()` only fills in missing fields — existing frontmatter values are never touched. The `overwrite` option changes this behavior:
+
+- **Default (no overwrite):** Only missing fields are written. Existing values are preserved.
+- **`overwrite: true`:** All generated fields replace existing frontmatter values.
+- **`overwrite: ['field1', 'field2']`:** Only the listed fields are overwritten. Other existing values are preserved.
+
+```typescript
+// Overwrite all generated fields, even if they already exist
+const result = await writr.ai.applyMetadata({
+  generate: { title: true, description: true },
+  overwrite: true,
+});
+
+// Only overwrite title, leave description alone if it already exists
+const result = await writr.ai.applyMetadata({
+  generate: { title: true, description: true, category: true },
+  overwrite: ['title'],
+});
+```
+
+### Field Mapping
+
+The `fieldMap` option maps generated metadata keys to different frontmatter field names. This is useful when your frontmatter schema uses different naming conventions than the default metadata keys.
+
+```typescript
+const result = await writr.ai.applyMetadata({
+  generate: { description: true, tags: true },
+  fieldMap: {
+    description: 'meta_description',
+    tags: 'labels',
+  },
+});
+// writr.frontMatter.meta_description === "A guide to..."
+// writr.frontMatter.labels === ["markdown", "rendering"]
+```
+
+The mapping applies to all behaviors — field existence checks, overwrites, and skips all use the mapped key when checking frontmatter.
+
+## SEO
+
+Generate SEO metadata using `writr.ai.getSEO()`. By default all fields are generated. Pass options to select specific fields.
+
+```typescript
+const seo = await writr.ai.getSEO();
+console.log(seo.slug);              // "getting-started-with-writr"
+console.log(seo.openGraph?.title);  // "Getting Started with Writr"
+
+// Generate only a slug
+const seo = await writr.ai.getSEO({ slug: true });
+```
+
+**Available fields:** `slug`, `openGraph` (includes `title`, `description`, `image`).
+
+## Translation
+
+Translate the document into another language using `writr.ai.getTranslation()`. Returns a new `Writr` instance with the translated content.
+
+```typescript
+const spanish = await writr.ai.getTranslation({ to: 'es' });
+console.log(spanish.body); // Spanish markdown
+
+// With source language and frontmatter translation
+const french = await writr.ai.getTranslation({
+  to: 'fr',
+  from: 'en',
+  translateFrontMatter: true,
+});
+```
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `to` | `string` | Yes | Target language or locale. |
+| `from` | `string` | No | Source language or locale. |
+| `translateFrontMatter` | `boolean` | No | Also translate frontmatter string values. |
+
+## Using WritrAI Directly
+
+`WritrAI` is exported as a named export and can be instantiated independently from the `Writr` constructor. This is useful when you want to configure the AI instance separately or swap models on the fly.
+
+```typescript
+import { Writr, WritrAI } from 'writr';
+import { openai } from '@ai-sdk/openai';
+
+const writr = new Writr('# My Document\n\nSome markdown content here.');
+const ai = new WritrAI(writr, {
+  model: openai('gpt-4.1-mini'),
+  cache: true,
+});
+
+// Generate metadata
+const metadata = await ai.getMetadata();
+console.log(metadata.title);
+console.log(metadata.tags);
+
+// Generate SEO data
+const seo = await ai.getSEO();
+console.log(seo.slug);
+
+// Translate
+const translated = await ai.getTranslation({ to: 'es' });
+console.log(translated.body);
+
+// Apply metadata to frontmatter
+const result = await ai.applyMetadata({
+  generate: { title: true, description: true, tags: true },
+  overwrite: true,
+});
+```
+
+# Migrating to v6
+
+Writr v6 upgrades [hookified](https://github.com/jaredwray/hookified) from v1 to v2 and removes `throwErrors` in favor of hookified's built-in error handling options.
+
+## Breaking Changes
+
+### `throwErrors` removed
+
+The `throwErrors` option has been removed from `WritrOptions`. Use `throwOnEmitError` instead, which is provided by hookified's `HookifiedOptions` (now spread into `WritrOptions`).
+
+**Before (v5):**
+
+```typescript
+const writr = new Writr('# Hello', { throwErrors: true });
+```
+
+**After (v6):**
+
+```typescript
+const writr = new Writr('# Hello', { throwOnEmitError: true });
+```
+
+### Error handling redesign
+
+All methods now use an **emit-only** pattern — errors are emitted via `emit('error', error)` but never explicitly re-thrown. Methods return fallback values on error (`""` for render methods, `{}` for frontMatter getter, `{ valid: false, error }` for validate).
+
+**How errors propagate:**
+
+- **With a listener registered:** Errors are passed to the listener. The method returns its fallback value without throwing.
+- **Without a listener (default behavior):** Since `throwOnEmptyListeners` defaults to `true`, the `emit('error')` call itself throws, following standard Node.js EventEmitter behavior. This means unhandled errors will still surface as exceptions.
+- **With `throwOnEmitError: true`:** Every `emit('error')` call throws, even when listeners are registered. This affects all methods that emit errors.
+
+**Other changes:**
+
+- `render()` and `renderSync()` no longer throw wrapped `"Failed to render markdown: ..."` errors. They emit the original error and return `""`.
+- `validate()` (async) no longer emits errors — it only returns `{ valid: false, error }`. `validateSync()` still emits.
+
+### hookified v2
+
+Writr now uses hookified v2 which introduces several new options available through `WritrOptions`:
+
+- `throwOnEmitError` — Throw when `emit("error")` is called, even with listeners (default: `false`)
+- `throwOnHookError` — Throw when a hook handler throws (default: `false`)
+- `throwOnEmptyListeners` — Throw when emitting `error` with no listeners (default: `true`)
+- `eventLogger` — Logger instance for event logging
+
+See the [hookified documentation](https://github.com/jaredwray/hookified) for full details.
+
+# Unified Processor Engine
+
+Writr builds on top of the open source [unified](https://github.com/unifiedjs/unified) processor – the core project that powers
+[remark](https://github.com/remarkjs/remark), [rehype](https://github.com/rehypejs/rehype), and many other content tools. Unified
+provides a pluggable pipeline where each plugin transforms a syntax tree. Writr configures a default set of plugins to turn
+Markdown into HTML, but you can access the processor through the `.engine` property to add your own behavior with
+`writr.engine.use(myPlugin)`. The [unified documentation](https://unifiedjs.com/) has more details and guides for building
+plugins and working with the processor directly.
+
 # Benchmarks
 
 This is a comparison with minimal configuration where we have disabled all rendering pipeline and just did straight caching + rendering to compare it against the fastest: