@glidecms/cms-sdk 2.2.0

package/AGENT.md

@@ -0,0 +1,206 @@
+# @glidecms/glide-cms-sdk — Agent Guide
+
+Write API for Glide CMS. Manages articles, images, files, taxonomies, users, and webhooks across four services: Composer, Media, Users, Transmit.
+
+## When to use this SDK
+
+- Creating, updating, publishing, or deleting CMS content
+- Uploading images or files
+- Managing users, roles, and permissions
+- Registering webhook subscribers
+- Discovering available resources (article types, workflows, taxonomies)
+
+Use **Connect SDK** for reading published content. Use **Gaia SDK** for AI search/suggestions/answers.
+
+## Setup
+
+```typescript
+import { Client } from '@glidecms/glide-cms-sdk';
+
+const { composer, media, users, transmit } = new Client({
+  host: 'acme.glidecms.com',
+  username: 'user@acme.com',
+  password: 'secret',
+  accountId: 1,
+});
+```
+
+Constructor validates config — throws immediately on missing/invalid fields.
+
+## Important: call discover() first
+
+Never hardcode IDs. Use `discover()` to get valid article types, workflow states, taxonomies, locales, and authors for the target environment.
+
+```typescript
+const ctx = await client.discover();
+const typeId = ctx.composer.articleTypes[0].id;
+const statusId = ctx.composer.workflow.publishableStatusId;
+```
+
+`discover()` fails hard on composer errors. Media/user count failures are soft — check `ctx.warnings`.
+
+## Task cards
+
+### Discover environment resources
+
+Use: `client.discover()`
+Supports: none (uses internal timeouts)
+Throws: any composer API error; media/users errors captured in `warnings`
+Returns: `DiscoverResult` with article types, taxonomies, locales, authors, workflow states, media counts, user counts
+
+### Create and publish an article
+
+Use: `composer.article.createAndPublish(payload, workflow)`
+Supports: signal, timeout (via opts on individual calls)
+Throws: `ValidationError`, `AuthError`, `ServerError`
+Requires: `articleTypeId`, `statusId` (must be publishable), `contentLocaleId`, `body`
+
+```typescript
+const workflow = await composer.workflow.getActive();
+await composer.article.createAndPublish({
+  headline: 'Title', articleTypeId: typeId, statusId: statusId,
+  contentLocaleId: 1, body: parsedBody,
+}, workflow.data);
+```
+
+### Safely update an article
+
+Use: `composer.article.update(id, payload, opts?)`
+Supports: signal, timeout
+Throws: `ValidationError`, `AuthError`, `NotFoundError`, `TimeoutError`
+Behavior: fetches the latest revision, merges supplied fields over existing fields, then saves a full PUT payload
+
+```typescript
+await composer.article.update(articleId, {
+  headline: 'Updated headline',
+  body: { html: '<p>Updated body</p>' },
+});
+```
+
+Use `partialUpdate(id, payload)` only when you explicitly want the backend PATCH endpoint. Backend PATCH support varies by field, so agents should prefer `update()` for content and metadata changes that must preserve omitted fields.
+
+### Read article metadata with body
+
+Use: `composer.article.getWithBody(id, opts?)`
+Supports: signal, timeout
+Returns: article metadata plus `data.body` and `data.bodyRevision`
+
+```typescript
+const article = await composer.article.getWithBody(articleId);
+const bodyJson = article.data.body;
+```
+
+### Build article body mentions
+
+Use: `taxonomyMention(input)` from `@glidecms/glide-cms-sdk/article-body`
+
+```typescript
+import { taxonomyMention } from '@glidecms/glide-cms-sdk/article-body';
+
+const mention = taxonomyMention({ id: 42, name: 'Markets', slug: 'markets' });
+```
+
+### Upload an image
+
+Use: `media.image.upload(meta, body, opts?)`
+Supports: signal, timeout
+Throws: `UploadError` (non-2xx from S3), `TimeoutError`, `AuthError`
+Returns: `ImageCreateResponse` with `image_id` and `upload_url`
+
+```typescript
+const image = await media.image.upload(
+  { name: 'photo.jpg', type: 'image/jpeg' },
+  fs.readFileSync('photo.jpg'),
+);
+```
+
+Do not use deprecated `uploadToS3()` in new code.
+
+### Upload a file
+
+Use: `media.file.upload(meta, body, opts?)`
+Supports: signal, timeout
+Throws: `UploadError`, `TimeoutError`, `AuthError`
+
+```typescript
+const file = await media.file.upload(
+  { filename: 'report.pdf', contentType: 'application/pdf' },
+  fs.readFileSync('report.pdf'),
+);
+```
+
+### List and paginate articles
+
+Use: `composer.article.list(query?, opts?)` or `composer.article.paginate(query?)`
+Supports: signal, timeout
+
+```typescript
+const page = await composer.article.list({ size: 20, page: 0 });
+// Or iterate all pages:
+for await (const page of composer.article.paginate({ size: 50 })) {
+  console.log(page.items.length);
+}
+```
+
+### Register a webhook subscriber
+
+Use: `transmit.subscriber.create(payload)`
+Supports: signal, timeout
+Throws: `ValidationError`, `AuthError`
+
+```typescript
+await transmit.subscriber.create({
+  name: 'My Webhook', type: 'webhook',
+  config: { url: 'https://example.com/hook', headers: {} },
+  events: ['article:published', 'article:updated'],
+  enabled: true,
+});
+```
+
+## Agent mutation guardrails
+
+- Publishing, unpublishing, deleting, user changes, and webhook changes require explicit user confirmation in agent/MCP contexts.
+- Prefer `discover()` before writes so IDs come from the target environment.
+- Prefer `media.image.upload()` and `media.file.upload()` over presigned upload primitives.
+- Prefer `composer.article.update()` over `partialUpdate()` unless the caller specifically asked for PATCH semantics.
+
+### Authenticate with a static token
+
+Use: `Client.withAccessToken(config)` instead of `new Client(config)`
+
+```typescript
+const { composer } = Client.withAccessToken({
+  host: 'acme.glidecms.com',
+  accessToken: 'eyJhbG...',
+});
+```
+
+## Error handling
+
+```typescript
+import { NotFoundError, AuthError, ValidationError, UploadError, TimeoutError } from '@glidecms/glide-cms-sdk';
+
+try {
+  await composer.article.get(id);
+} catch (err) {
+  if (err instanceof NotFoundError) { /* 404 */ }
+  if (err instanceof AuthError) { /* 401 — bad credentials or expired */ }
+  if (err instanceof ValidationError) { /* 422 — err.details has field errors */ }
+  if (err instanceof UploadError) { /* S3 presigned PUT failed */ }
+  if (err instanceof TimeoutError) { /* request or auth timed out */ }
+}
+```
+
+## Cancellation and timeout rules
+
+- All methods accept `{ signal, timeout }` as the last argument
+- Aborted requests throw immediately — never retried
+- Timed-out requests throw `TimeoutError` — never retried
+- 5xx and network errors retry up to 3 times with exponential backoff
+- 4xx errors throw immediately — never retried (except 401 triggers one token refresh)
+- Auth and refresh have a 15s hard timeout
+
+## Deprecated paths — avoid these
+
+- `media.image.uploadToS3()` → use `media.image.upload()` instead
+- `media.file.uploadToS3()` → use `media.file.upload()` instead

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+## 2.1.0 (NEXT)
+
+### Bug Fixes
+
+- **Aborted and timed-out requests are no longer retried.** `AbortError` (from `signal`) and `TimeoutError` (from `AbortSignal.timeout()`) now propagate immediately instead of being wrapped as `NetworkError` and retried. This was especially dangerous for mutating calls (POST/PUT/DELETE).
+- **Presigned uploads now validate the S3 response.** `image.upload()` and `file.upload()` check `response.ok` and throw `UploadError` on non-2xx. Previously a 403/500 from S3 was silently ignored and the method returned as if the upload succeeded.
+- **GET deduplication skipped when `opts` is provided.** Two concurrent GETs to the same URL with different `signal`/`timeout` are no longer coupled to the same promise.
+- **Auth token validation fails fast.** `GlideToken` now throws `AuthError` immediately when the auth or refresh response is missing `accessToken` or `refreshToken`, instead of proceeding with an empty bearer token.
+- **`composer.article.update()` is now safe by default.** It fetches the latest revision, merges supplied fields over the existing revision, and saves a full PUT payload so omitted fields are preserved.
+- **`composer.collection.update()` preserves required fields.** It backfills `name`, `typeId`, and `statusId` from the existing collection when callers send a focused update.
+
+### Added
+
+- `TimeoutError` — thrown when a request exceeds its timeout. Extends `GlideError` with `statusCode: 0`.
+- `UploadError` — thrown when a presigned upload returns a non-2xx response. Extends `GlideError` with the S3 status code.
+- Shared `uploadToPresignedUrl()` helper used by both `ImageClient` and `FileClient`. Supports `signal` for cancellation.
+- `composer.article.getWithBody()` — fetches article metadata plus the latest revision body in one helper.
+- `renderArticleBody()` and `taxonomyMention()` in `@glidecms/glide-cms-sdk/article-body`.
+- Collection convenience methods: `addItems`, `addArticles`, `removeItems`, and `removeArticles`.
+- `prepack` and `pack:check` scripts for npm release validation.
+
+### Migration Notes
+
+- If your code catches errors from `image.upload()` or `file.upload()`, uploads that previously appeared to succeed may now throw `UploadError`. This is a correctness fix — the old behavior silently produced incomplete uploads.
+- If your code catches `AuthError` from 401 responses, you may now also see `AuthError` thrown earlier during token acquisition when the auth endpoint returns a malformed response.
+- `composer.article.update()` no longer behaves like a raw destructive PUT for omitted fields. `partialUpdate()` is now internal (protected). Use `.update()` for all updates — it preserves GET-visible fields.
+- `ArticlePartialUpdatePayload` is deprecated in favor of `ArticleUpdatePayload`.
+- `partialUpdateAndPublish(id, payload, workflow)` remains public for PATCH+publish workflows.
+- `jsdom` is now an optional peer dependency used by the `article-body` parser. Install it if your app calls `parseArticleBody()` or passes `{ html }` article bodies.
+
+## 2.0.0 (2026-04-14)
+
+### Breaking Changes
+
+- **Class renamed: `GlideCmsSdk` → `Client`.**
+  A deprecated `GlideCmsSdk` alias is exported — existing imports still work but will be removed in v4.
+
+  ```ts
+  // Before
+  import { GlideCmsSdk } from '@glidecms/cms-sdk';
+  const sdk = new GlideCmsSdk({ composerApiEndpoint, mediaApiEndpoint, usersApiEndpoint, ... });
+
+  // After
+  import { Client } from '@glidecms/cms-sdk';
+  const { composer, media, users } = new Client({ baseUrl: 'https://acme.glidecms.com', ... });
+  ```
+
+- **Config types renamed: `GlideCmsSdkConfig` → `ClientConfig`, `GlideCmsSdkAccessTokenConfig` → `ClientAccessTokenConfig`.**
+  Old names exported as deprecated aliases.
+
+### Added
+
+- **`baseUrl` config option** — single URL instead of 3 separate endpoint URLs. Endpoints derived internally. Explicit endpoints still supported as an escape hatch.
+
+  ```ts
+  // New (preferred)
+  new Client({ baseUrl: 'https://acme.glidecms.com', username, password, accountId });
+
+  // Still works
+  new Client({ composerApiEndpoint, mediaApiEndpoint, usersApiEndpoint, username, password, accountId });
+  ```
+
+- **`RequestOpts` type** — `{ signal?: AbortSignal; timeout?: number }`.
+- **`opts?` parameter on every public method** — pass `signal` or `timeout` per-request.
+
+  ```ts
+  const ac = new AbortController();
+  composer.article.get(1, { signal: ac.signal });
+  media.image.upload(meta, body, { timeout: 120_000 });
+  composer.article.list(query, { timeout: 60_000 });
+  ```

package/README.md

@@ -0,0 +1,41 @@
+# @glidecms/glide-cms-sdk
+
+TypeScript SDK for the Glide CMS APIs: Composer, Media, Users, and Transmit.
+
+Native `fetch`. Typed errors. Automatic JWT authentication with refresh. Optional article body HTML conversion via `jsdom`. Node.js >= 22.
+
+```bash
+npm install @glidecms/glide-cms-sdk
+```
+
+## API surface
+
+41 clients across 4 APIs, accessed via destructured service namespaces:
+
+- **Composer** (26): article, articleType, author, collection, collectionType, contentFilter, contentLocale, contentPanel, contentTag, customFieldGroup, htmlSnippet, liveReport, liveReportPost, liveReportSummary, liveReportType, menu, page, pathRedirect, resourceLock, route, systemWidget, taxonomy, template, thirdPartyWidget, verifyAccessBundle, workflow
+- **Media** (10): file, folder, gallery, image, tag, settings, workflow, bedrock, account (settings init only), integration
+- **Users** (3): user, role, permission
+- **Transmit** (2): subscriber, event
+
+## Documentation
+
+| | |
+|---|---|
+| [Tutorial](docs/tutorial.md) | Build your first integration from scratch |
+| [How-to guides](docs/howto.md) | Articles, images, pagination, errors, request options, logging, migration |
+| [API reference](docs/reference.md) | Full method signatures, config options, error classes |
+| [Migration notes](docs/migration.md) | `update()` safety, article body helpers, collection helpers |
+| [Agent guide](AGENT.md) | Agent/MCP usage guidance and mutation guardrails |
+| [Architecture](docs/architecture.md) | Design decisions and internals |
+
+## Guarantees
+
+- **Authentication.** SDK authenticates on first request, refreshes automatically before expiry, re-authenticates when the refresh token expires (8h). Auth failures throw `AuthError` immediately.
+- **Timeouts.** All methods accept per-request timeout via opts. Auth and refresh have a 15s hard timeout. Default request timeout is 30s.
+- **Cancellation.** All methods accept `AbortSignal` via opts. Aborted requests throw immediately without retry.
+- **Retry.** 5xx responses and network errors are retried up to 3 times with exponential backoff. 4xx errors, aborts, and timeouts are never retried.
+- **Uploads.** Presigned PUT responses are validated. Non-2xx from S3 throws `UploadError`. Uploads accept `AbortSignal` for cancellation.
+- **Rate limiting.** 429 responses throw `RateLimitError` with `retryAfter` populated from the response.
+- **discover().** Composer resource failures throw immediately. Media and user count failures are soft — results include a `warnings` array.
+- **Safe article update.** `composer.article.update()` fetches the latest revision, merges supplied fields, and saves a full payload so omitted fields are preserved.
+- **Deduplication.** Concurrent identical GETs without per-request opts share one fetch. GETs with opts always make independent requests.

package/dist/article-body.d.ts

@@ -0,0 +1,319 @@
+/**
+ * Branded type for article body content that has been processed by {@link parseArticleBody}.
+ *
+ * The Composer API expects body content as a JSON string in its internal content-node format,
+ * not raw HTML. This branded type enforces that at compile time — passing a plain `string`
+ * to `ArticleCreatePayload.body` or `ArticleUpdatePayload.body` will produce a type error.
+ *
+ * @example
+ * ```typescript
+ * import { parseArticleBody } from '@glidecms/glide-cms-sdk/article-body';
+ *
+ * const body = parseArticleBody('<p>Hello world</p>');
+ * await composer.article.create({ headline: 'Test', body }); // ✅ compiles
+ * await composer.article.create({ headline: 'Test', body: '<p>raw</p>' }); // ❌ type error
+ * ```
+ */
+declare const __parsedArticleBody: unique symbol;
+export type ParsedArticleBody = string & {
+    readonly [__parsedArticleBody]: 'ParsedArticleBody';
+};
+/**
+ * Input type for article body content. Accepts either:
+ *
+ * - **`{ html: string }`** — Raw HTML that the SDK will automatically convert
+ *   to Composer's JSON format via {@link parseArticleBody}. Optionally include
+ *   `patternReplacements` to transform image/media tags during conversion.
+ *
+ * - **`ParsedArticleBody`** — Pre-parsed body from a prior {@link parseArticleBody} call.
+ *
+ * @example
+ * ```typescript
+ * // Let the SDK parse HTML automatically (recommended)
+ * await composer.article.createAndPublish({
+ *   body: { html: '<p>Hello world</p>' },
+ * });
+ *
+ * // With image pattern replacements
+ * import { IMAGE_PATTERN_REPLACEMENTS } from '@glidecms/glide-cms-sdk/article-body';
+ * await composer.article.createAndPublish({
+ *   body: { html: htmlWithImages, patternReplacements: IMAGE_PATTERN_REPLACEMENTS },
+ * });
+ *
+ * // Pre-parsed (advanced)
+ * import { parseArticleBody } from '@glidecms/glide-cms-sdk/article-body';
+ * await composer.article.createAndPublish({
+ *   body: parseArticleBody(html),
+ * });
+ * ```
+ */
+export type ArticleBodyInput = ParsedArticleBody | ({
+    html: string;
+} & HtmlToBodyJsonOptions);
+/**
+ * Standard Glide image embed replacement string.
+ * Use with pattern replacements to convert image tags to Composer's format.
+ * Expects `$1` to be the image src URL.
+ *
+ * @example
+ * ```typescript
+ * const body = glideSdk.composer.articleBody.htmlToBodyJson(html, {
+ *   patternReplacements: [
+ *     { pattern: IMAGE_IN_PARAGRAPH_PATTERN, replacement: GLIDE_EXTERNAL_IMAGE_EMBED },
+ *     { pattern: IMAGE_IN_DIV_PATTERN, replacement: GLIDE_EXTERNAL_IMAGE_EMBED }
+ *   ]
+ * });
+ * ```
+ */
+export declare const GLIDE_EXTERNAL_IMAGE_EMBED = "<p class=\"fr-embedded\"><span class=\"fr-img-caption gd-ember-wrapper fr-fic fr-dib --url\" data-type=\"image/url\"><span class=\"fr-img-wrap gd-ember-wrapper\"><img class=\"fr-embedded gd-embedded\" src=\"$1\"></span></span></p>";
+/**
+ * Pattern to match `<p><img src="..."></p>` structures.
+ * Captures the image src URL in group `$1`.
+ *
+ * @example
+ * ```typescript
+ * { pattern: IMAGE_IN_PARAGRAPH_PATTERN, replacement: GLIDE_EXTERNAL_IMAGE_EMBED }
+ * ```
+ */
+export declare const IMAGE_IN_PARAGRAPH_PATTERN: RegExp;
+/**
+ * Pattern to match `<div>...<img src="...">...</div>` structures.
+ * Captures the image src URL in group `$1`.
+ *
+ * @example
+ * ```typescript
+ * { pattern: IMAGE_IN_DIV_PATTERN, replacement: GLIDE_EXTERNAL_IMAGE_EMBED }
+ * ```
+ */
+export declare const IMAGE_IN_DIV_PATTERN: RegExp;
+/**
+ * Pattern to match standalone `<img src="...">` tags.
+ * Captures the image src URL in group `$1`.
+ *
+ * @example
+ * ```typescript
+ * { pattern: STANDALONE_IMAGE_PATTERN, replacement: GLIDE_EXTERNAL_IMAGE_EMBED }
+ * ```
+ */
+export declare const STANDALONE_IMAGE_PATTERN: RegExp;
+/**
+ * Predefined pattern replacements for common image structures.
+ * Handles `<p><img></p>`, `<div><img></div>`, and standalone `<img>` tags.
+ *
+ * @example
+ * ```typescript
+ * const body = glideSdk.composer.articleBody.htmlToBodyJson(html, {
+ *   patternReplacements: IMAGE_PATTERN_REPLACEMENTS
+ * });
+ * ```
+ */
+export declare const IMAGE_PATTERN_REPLACEMENTS: PatternReplacement[];
+/**
+ * Represents a node in the content structure tree.
+ * This structure is used by Composer to render article body content.
+ */
+export interface ContentStructureNode {
+    /** Unique identifier for the node */
+    id: string;
+    /** HTML tag name (e.g., 'P', 'H1', 'STRONG') or 'TEXT' for text nodes */
+    tagName: string;
+    /** HTML attributes of the element */
+    attributes: Record<string, string>;
+    /** Text content for TEXT nodes */
+    innerText: string;
+    /** D of the parent node */
+    parentId: string;
+    /** Child nodes */
+    childNodes: ContentStructureNode[];
+}
+/**
+ * Result structure for content node conversion.
+ * This is the format expected by Composer for article body content.
+ */
+export interface ContentNodeResult {
+    /** Array of root-level content structure nodes */
+    contentStructure: ContentStructureNode[];
+    /** Additional content nodes metadata (reserved for future use) */
+    contentNodes: Record<string, unknown>;
+}
+/**
+ * Metadata for embedded content nodes like images.
+ * This structure is required by Composer for media elements.
+ */
+export interface ContentNodeMetadata {
+    /** Unique identifier matching the node in contentStructure */
+    id: string;
+    /** Content type (e.g., 'image/url', 'content/link') */
+    type: string;
+    /** Alignment of the content (for images) */
+    alignment?: string;
+    /** Whether the content is inline (for images) */
+    isInline?: boolean;
+    /** Data identifier (usually the URL for images) */
+    dataId?: string;
+    /** Data URL (the URL for images or links) */
+    dataUrl?: string;
+    /** Caption text (for images) */
+    caption?: string;
+    /** Alt text for accessibility (for images) */
+    alt?: string;
+    /** Credit/attribution text (for images) */
+    credit?: string;
+    /** Image display style (for images) */
+    imageStyle?: string;
+    /** Inner text content (for links) */
+    innerText?: string;
+    /** Inner HTML content (for links) */
+    innerHTML?: string;
+}
+export interface TaxonomyMentionInput {
+    id: number | string;
+    name: string;
+    slug: string;
+    href?: string;
+}
+/**
+ * Builds the Composer/Froala HTML shape for an inline taxonomy mention.
+ */
+export declare function taxonomyMention(input: TaxonomyMentionInput): string;
+/**
+ * Converts Composer article body JSON back to HTML for previews and rendering.
+ */
+export declare function renderArticleBody(bodyJson: string | ContentNodeResult): string;
+/**
+ * Configuration for regex-based pattern replacement on raw HTML strings.
+ * Pattern replacements are applied before DOM parsing, making them ideal for
+ * complex nested structures that are difficult to handle with DOM traversal.
+ *
+ * @example
+ * ```typescript
+ * // Replace <p><img></p> with standardized Composer image format
+ * const replacement: PatternReplacement = {
+ *   pattern: /<p[^>]*>\s*<img[^>]*src="([^"]*)"[^>]*\/?>\s*<\/p>/gi,
+ *   replacement: '<p class="fr-embedded"><span class="fr-img-caption gd-ember-wrapper fr-fic fr-dib --url" data-type="image/url"><span class="fr-img-wrap gd-ember-wrapper"><img class="fr-embedded gd-embedded" src="$1"></span></span></p>'
+ * };
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using a function for dynamic replacement
+ * const replacement: PatternReplacement = {
+ *   pattern: /<div[^>]*>[\s\S]*?<img[^>]*src="([^"]*)"[^>]*\/?>[\s\S]*?<\/div>/gi,
+ *   replacement: (match, src) => {
+ *     const sanitizedSrc = src.replace(/[<>"]/g, '');
+ *     return `<p class="fr-embedded"><span class="fr-img-caption gd-ember-wrapper fr-fic fr-dib --url" data-type="image/url"><span class="fr-img-wrap gd-ember-wrapper"><img class="fr-embedded gd-embedded" src="${sanitizedSrc}"></span></span></p>`;
+ *   }
+ * };
+ * ```
+ */
+export interface PatternReplacement {
+    /**
+     * Regex pattern to match in the HTML string.
+     * Use capture groups to extract values for use in the replacement.
+     * Recommended to use `gi` flags for global and case-insensitive matching.
+     *
+     * @example
+     * ```typescript
+     * // Match <p> containing only an <img>, capture the src
+     * pattern: /<p[^>]*>\s*<img[^>]*src="([^"]*)"[^>]*\/?>\s*<\/p>/gi
+     * ```
+     */
+    pattern: RegExp;
+    /**
+     * Replacement string or function.
+     *
+     * When using a string:
+     * - Use `$1`, `$2`, etc. to reference capture groups from the pattern
+     * - Use `$&` to reference the entire match
+     *
+     * When using a function:
+     * - First argument is the full match
+     * - Subsequent arguments are capture groups in order
+     * - Return the replacement string
+     *
+     * @example
+     * ```typescript
+     * // String replacement with capture group
+     * replacement: '<p class="fr-embedded"><img src="$1"></p>'
+     *
+     * // Function replacement for complex logic
+     * replacement: (match, src) => `<p><img src="${encodeURI(src)}"></p>`
+     * ```
+     */
+    replacement: string | ((...args: string[]) => string);
+}
+/**
+ * Configuration options for HTML to body JSON conversion.
+ */
+export interface HtmlToBodyJsonOptions {
+    /**
+     * Pattern replacements applied to the raw HTML string before DOM parsing.
+     * This is the recommended approach for transforming HTML elements like images,
+     * videos, and other media into Composer's standardized format.
+     *
+     * Patterns are applied in the order they are defined, allowing you to chain
+     * multiple transformations. Each pattern's output becomes the input for the next.
+     *
+     * Common use cases:
+     * - Converting `<img>` tags to Composer's embedded image format
+     * - Transforming `<div>` wrappers containing media elements
+     * - Standardizing `<p><img></p>` patterns
+     * - Removing or replacing unsupported HTML structures
+     *
+     * @example
+     * ```typescript
+     * const body = glideSdk.composer.articleBody.htmlToBodyJson(html, {
+     *   patternReplacements: [
+     *     // Handle <p><img></p> pattern
+     *     {
+     *       pattern: /<p[^>]*>\s*<img[^>]*src="([^"]*)"[^>]*\/?>\s*<\/p>/gi,
+     *       replacement: '<p class="fr-embedded"><span class="fr-img-caption gd-ember-wrapper fr-fic fr-dib --url" data-type="image/url"><span class="fr-img-wrap gd-ember-wrapper"><img class="fr-embedded gd-embedded" src="$1"></span></span></p>'
+     *     },
+     *     // Handle <div><img></div> pattern
+     *     {
+     *       pattern: /<div[^>]*>[\s\S]*?<img[^>]*src="([^"]*)"[^>]*\/?>[\s\S]*?<\/div>/gi,
+     *       replacement: '<p class="fr-embedded"><span class="fr-img-caption gd-ember-wrapper fr-fic fr-dib --url" data-type="image/url"><span class="fr-img-wrap gd-ember-wrapper"><img class="fr-embedded gd-embedded" src="$1"></span></span></p>'
+     *     }
+     *   ]
+     * });
+     * ```
+     */
+    patternReplacements?: PatternReplacement[];
+}
+/**
+ * Converts an HTML string to Composer's content node structure JSON format.
+ *
+ * Parses HTML content and transforms it into the JSON structure required by
+ * Composer for article body content. The resulting JSON can be used directly
+ * in article create/update payloads.
+ *
+ * Supported tags: p, h1-h6, span, strong, b, em, i, code, pre, ul, ol, li, a, br, blockquote, table elements.
+ * Stripped tags: div, img, figure, figcaption, video, audio, iframe (require custom Composer handling).
+ *
+ * @param htmlString - The HTML string to convert (can include body tags or raw HTML)
+ * @param options - Optional configuration including pattern replacements
+ * @returns JSON string in Composer's content node format, ready for the article body field
+ *
+ * @example
+ * ```typescript
+ * import { parseArticleBody, IMAGE_PATTERN_REPLACEMENTS } from '@glidecms/glide-cms-sdk/article-body';
+ *
+ * // Basic usage
+ * const body = parseArticleBody('<p>Hello <strong>world</strong></p>');
+ *
+ * // With image pattern replacements
+ * const body = parseArticleBody(html, { patternReplacements: IMAGE_PATTERN_REPLACEMENTS });
+ *
+ * // Use in article creation
+ * await composer.article.create({ headline: 'My Article', body });
+ * ```
+ */
+export declare function parseArticleBody(htmlString: string, options?: HtmlToBodyJsonOptions): ParsedArticleBody;
+/** @internal Resolve ArticleBodyInput to ParsedArticleBody, auto-parsing `{ html }` objects. */
+export declare function resolveBody(body: ArticleBodyInput): ParsedArticleBody;
+/** @deprecated Use `parseArticleBody()` instead. Will be removed in next major. */
+export declare class ArticleBodyProcessingService {
+    htmlToBodyJson(htmlString: string, options?: HtmlToBodyJsonOptions): ParsedArticleBody;
+}
+export {};
+//# sourceMappingURL=article-body.d.ts.map

package/dist/article-body.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"article-body.d.ts","sourceRoot":"","sources":["../src/article-body.ts"],"names":[],"mappings":"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"}