# mentionwell

> Tiny TypeScript SDK around the public API: getBlogPostsViaApi, getBlogPostViaApi, getAllBlogSlugsViaApi, prepareArticleHtml.

The official SDK. Tiny TypeScript wrapper around the public API plus a few HTML cleanup helpers.

```bash
npm install mentionwell
```

## Modules

- `mentionwell/api` — typed fetch helpers for the public API.
- `mentionwell/html-utils` — helpers for preparing `post.html`: strip duplicate title/hero chrome, remove legacy `[CTA]` placeholders, and optionally move the inline TOC.
- `mentionwell/styles` — optional default CSS for the `wb-*` class names that the writer emits.

## Config

The exported config type is currently named `MentionwellApiConfig` for backwards compatibility.

```ts
export interface MentionwellApiConfig {
  apiUrl: string;     // MENTIONWELL_API_URL
  siteSlug: string;   // MENTIONWELL_SITE_SLUG
  apiKey: string;     // MENTIONWELL_API_KEY
  fetch?: typeof fetch;
}
```

## API helpers

### `getBlogPostsViaApi(config, page = 1, perPage = 12)`

Wraps `GET /api/public/{siteSlug}/posts?limit=100`. Returns `{ posts, total, totalPages }` by slicing that response locally. The hosted API currently caps lists at 100 posts.

### `getBlogPostViaApi(config, slug)`

Wraps `GET /api/public/{siteSlug}/posts/{slug}`. Returns the post or `null` on 404.

### `getAllBlogSlugsViaApi(config)`

Fetches the list endpoint once and returns up to 100 published slugs. Useful for `generateStaticParams`.

### `getBlogPostSummariesViaApi(config)`

Returns a lightweight `{ slug, updatedAt, publishedAt }[]` for sitemap generation without pulling full post bodies.

## HTML utils

### `prepareArticleHtml(html: string): string`

Returns HTML with duplicate article chrome and legacy `[CTA]` placeholders removed. It does not sanitize scripts, rewrite image alt text, or normalize heading levels. Single argument — no options object.

### `extractTocHtml(html: string): string | null`

Returns the inline TOC block as HTML, or `null` if the article has no TOC. Useful when you want to render the TOC in a sidebar.

### `stripTocFromArticle(html: string): string`

Returns the article body with the inline TOC removed (since you're now rendering it in the sidebar).

### `stripDuplicateChrome(html: string): string`

Removes duplicated header/hero image chrome from `post.html`. `prepareArticleHtml` already calls this — only call it directly if you need finer control.

### `stripLegacyCtaLeaks(html: string): string`

Removes literal `[CTA]` placeholder tokens older articles sometimes carried. Also called by `prepareArticleHtml`.

## Source

- npm: [`mentionwell`](https://www.npmjs.com/package/mentionwell)
- Versioning: semver. Patch releases never break the wire format.


---

Canonical URL: https://mentionwell.com/docs/sdk
Live HTML version: https://mentionwell.com/docs/sdk
Section: SDK reference
Site index for AI ingestion: https://mentionwell.com/llms.txt
Full reference: https://mentionwell.com/llms-full.txt