featurebase-node 0.14.1 → 0.14.3

package/src/resources/help-center/articles.ts

@@ -344,6 +344,89 @@ export class Articles extends APIResource {
     });
   }
 
+  /**
+   * Surgically edit an article's body with a find/replace instruction, without
+   * re-uploading the whole HTML. Designed for AI agents doing high-precision,
+   * byte-stable edits (e.g. renaming a product across many articles).
+   *
+   * ### Two-tier matching
+   *
+   * Matching runs against the article's **stored** body and is tried in two tiers:
+   *
+   * 1. **Text nodes only** (`mode: "text"`, preferred): `oldText` is matched only
+   *    inside visible text — markup, tags, and attributes are never searched or
+   *    altered, so the result is byte-identical everywhere outside the replaced
+   *    spans. Matching is entity-aware, so `oldText: "A & B"` matches a stored
+   *    `A & B`.
+   * 2. **Raw markup fallback** (`mode: "html"`): only used when tier 1 finds
+   *    nothing. `oldText` is matched as a literal substring over the raw body string
+   *    (markup included), so you can swap an attribute value or tag. Because this
+   *    can introduce markup, the full result is re-run through the XSS sanitizer
+   *    before it is stored.
+   *
+   * Do **not** include `<img>` tags in `oldText` — their stored `src` differs from
+   * the API representation and will not match.
+   *
+   * ### Uniqueness rule
+   *
+   * By default the edit requires `oldText` to match **exactly once** and returns
+   * `400` if it is ambiguous. To edit multiple occurrences, either set
+   * `replaceAll: true` or assert the exact count with `expectedReplacements` (which
+   * takes precedence over `replaceAll`).
+   *
+   * ### Dry-run workflow
+   *
+   * Set `dryRun: true` to preview: the response reports the match count, the
+   * matching `mode`, and `previews` (each changed span framed by surrounding
+   * context) without writing. Recommended flow for bulk edits: dry-run across the
+   * target articles first, confirm the counts and previews, then re-issue each call
+   * with `dryRun: false`.
+   *
+   * ### Target
+   *
+   * `target: "draft"` (default) edits the unpublished draft. `target: "live"` edits
+   * the published content directly — this records a history snapshot and purges the
+   * public edge cache, mirroring a publish.
+   *
+   * ### Retry semantics
+   *
+   * Calls are not idempotent — after a timeout, re-read the article (or dry-run)
+   * before retrying; with the default unique-match mode a duplicate retry fails
+   * safely unless `newText` still contains `oldText`.
+   *
+   * ### Version Availability
+   *
+   * This endpoint is only available in API version 2026-01-01.nova and newer.
+   *
+   * @example
+   * ```ts
+   * const editArticleBodyResponse =
+   *   await client.helpCenter.articles.editBody('1234567', {
+   *     newText: 'New Product Name',
+   *     oldText: 'Old Product Name',
+   *   });
+   * ```
+   */
+  editBody(
+    id: string,
+    params: ArticleEditBodyParams,
+    options?: RequestOptions,
+  ): APIPromise<EditArticleBodyResponse> {
+    const { 'Featurebase-Version': featurebaseVersion, ...body } = params;
+    return this._client.post(path`/v2/help_center/articles/${id}/edit_body`, {
+      body,
+      ...options,
+      headers: buildHeaders([
+        {
+          ...(featurebaseVersion?.toString() != null ?
+            { 'Featurebase-Version': featurebaseVersion?.toString() }
+          : undefined),
+        },
+        options?.headers,
+      ]),
+    });
+  }
+
   /**
    * Search help-center articles by structured filters and/or hybrid full-text
    * search, with sort and cursor pagination.
@@ -1007,6 +1090,172 @@ export interface ArticleTranslationInputNova {
   title?: string;
 }
 
+export interface EditArticleBodyBody {
+  /**
+   * Replacement text. Keep this to a fragment, not a whole document (max 10000
+   * chars). May be an empty string to delete the matched fragment. When the match
+   * came from tier 2 (raw markup), the full resulting body is re-run through the XSS
+   * sanitizer, so any dangerous markup in `newText` is stripped. Images inserted via
+   * edit_body are not uploaded to Featurebase storage — use articles.update with
+   * formatter 'raw' for image changes.
+   */
+  newText: string;
+
+  /**
+   * Exact fragment to find in the stored article body. Keep this to a fragment, not
+   * a whole document (max 10000 chars). Tier 1 matches only inside TEXT nodes
+   * (markup, tags, and attributes are never searched or altered) and is
+   * entity-aware, so `oldText: "A & B"` matches a stored `A &amp; B`. If tier 1
+   * finds nothing, tier 2 falls back to a literal substring match over the raw body
+   * string (markup included). Do NOT include `<img>` tags — their stored `src`
+   * differs from the API representation and will not match.
+   */
+  oldText: string;
+
+  /**
+   * Preview the edit without writing. Returns the match count, matching `mode`, and
+   * `previews` (changed spans with surrounding context) so an agent can verify the
+   * edit before committing. Recommended workflow: dry-run across a set of articles
+   * first, confirm the counts and previews, then re-issue each call with
+   * `dryRun: false`.
+   */
+  dryRun?: boolean;
+
+  /**
+   * Assert the exact number of matches. When set, the edit replaces all matches only
+   * if the count is exactly this value, otherwise it returns `400`. Takes precedence
+   * over `replaceAll`. Use this to make bulk edits safe: dry-run first to learn the
+   * count, then commit with the expected number.
+   */
+  expectedReplacements?: number;
+
+  /**
+   * Locale of the body to edit. Defaults to the help center's default locale.
+   */
+  locale?:
+    | 'bn'
+    | 'bs'
+    | 'pt-BR'
+    | 'bg'
+    | 'ca'
+    | 'hr'
+    | 'cs'
+    | 'da'
+    | 'nl'
+    | 'en'
+    | 'et'
+    | 'fi'
+    | 'fr'
+    | 'de'
+    | 'el'
+    | 'hi'
+    | 'hu'
+    | 'id'
+    | 'it'
+    | 'ja'
+    | 'ko'
+    | 'lv'
+    | 'lt'
+    | 'ms'
+    | 'mn'
+    | 'nb'
+    | 'pl'
+    | 'pt'
+    | 'ro'
+    | 'ru'
+    | 'sr'
+    | 'zh-CN'
+    | 'sk'
+    | 'sl'
+    | 'es'
+    | 'sw'
+    | 'sv'
+    | 'th'
+    | 'zh-TW'
+    | 'tr'
+    | 'uk'
+    | 'vi';
+
+  /**
+   * Replace every match. When omitted (or false) and `expectedReplacements` is not
+   * set, the edit requires exactly one match and returns `400` if `oldText` is
+   * ambiguous (found more than once). Provide more surrounding context in `oldText`
+   * to make a unique match, or set this to true.
+   */
+  replaceAll?: boolean;
+
+  /**
+   * Which body to edit: the unpublished `draft` (default) or the published `live`
+   * content. Editing `live` records a history snapshot and purges the public edge
+   * cache, mirroring a publish.
+   */
+  target?: 'draft' | 'live';
+}
+
+export interface EditArticleBodyPreview {
+  /**
+   * The same span and window after the edit.
+   */
+  after: string;
+
+  /**
+   * The changed span framed by up to 60 characters of surrounding context, before
+   * the edit.
+   */
+  before: string;
+}
+
+export interface EditArticleBodyResponse {
+  /**
+   * The edited article id
+   */
+  id: string;
+
+  /**
+   * Whether this was a preview (no write performed)
+   */
+  dryRun: boolean;
+
+  /**
+   * Locale that was edited
+   */
+  locale: string;
+
+  /**
+   * Number of matches found for `oldText`
+   */
+  matches: number;
+
+  /**
+   * Which matching tier applied. `text` = text-node-only, byte-stable (markup
+   * untouched). `html` = raw-markup fallback (result re-sanitized). Tier 1 (`text`)
+   * is always attempted first.
+   */
+  mode: 'text' | 'html';
+
+  /**
+   * Object type identifier
+   */
+  object: 'article.body_edit';
+
+  /**
+   * Up to 20 before/after windows, one per replaced match, for verification. Preview
+   * strings are raw untrusted text (tier-2 previews show pre-sanitization content) —
+   * never render them as HTML.
+   */
+  previews: Array<EditArticleBodyPreview>;
+
+  /**
+   * Number of matches actually replaced (0 when `dryRun` is true)
+   */
+  replaced: number;
+
+  /**
+   * Which body was edited
+   */
+  target: 'draft' | 'live';
+}
+
 export interface ArticleDeleteResponse {
   /**
    * Unique identifier of the deleted article
@@ -1514,12 +1763,16 @@ export interface ArticleCreateParams {
   description?: string;
 
   /**
-   * Body param: Content formatter. `default` accepts HTML/markdown as-is with
-   * minimal cleanup. `ai` runs the input through Featurebase AI to convert arbitrary
-   * markdown / HTML / docs from other tools into our custom block format (callouts,
-   * multi-code, accordions, columns).
+   * Body param: Content formatter. `raw` stores Featurebase-canonical HTML verbatim
+   * after XSS sanitization — formatting (alignment, colors, classes, blank-line
+   * spacers, accordions) is preserved byte-for-byte. Use this whenever you are
+   * editing an article whose body you previously read from this API. `default`
+   * applies lossy cleanup meant for foreign HTML/markdown; `ai` runs the input
+   * through Featurebase AI to convert arbitrary markdown / HTML / docs from other
+   * tools into our custom block format (callouts, multi-code, accordions, columns).
+   * Never use `default` or `ai` to re-save an existing article body.
    */
-  formatter?: 'default' | 'ai';
+  formatter?: 'default' | 'ai' | 'raw';
 
   /**
    * Body param: The ID of the help center to create the article in. If parentId is
@@ -1677,12 +1930,16 @@ export interface ArticleUpdateParams {
   description?: string;
 
   /**
-   * Body param: Content formatter. `default` accepts HTML/markdown as-is with
-   * minimal cleanup. `ai` runs the input through Featurebase AI to convert arbitrary
-   * markdown / HTML / docs from other tools into our custom block format (callouts,
-   * multi-code, accordions, columns).
+   * Body param: Content formatter. `raw` stores Featurebase-canonical HTML verbatim
+   * after XSS sanitization — formatting (alignment, colors, classes, blank-line
+   * spacers, accordions) is preserved byte-for-byte. Use this whenever you are
+   * editing an article whose body you previously read from this API. `default`
+   * applies lossy cleanup meant for foreign HTML/markdown; `ai` runs the input
+   * through Featurebase AI to convert arbitrary markdown / HTML / docs from other
+   * tools into our custom block format (callouts, multi-code, accordions, columns).
+   * Never use `default` or `ai` to re-save an existing article body.
    */
-  formatter?: 'default' | 'ai';
+  formatter?: 'default' | 'ai' | 'raw';
 
   /**
    * Body param: Icon object for the article
@@ -1815,6 +2072,115 @@ export interface ArticleDeleteParams {
   'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
 }
 
+export interface ArticleEditBodyParams {
+  /**
+   * Body param: Replacement text. Keep this to a fragment, not a whole document (max
+   * 10000 chars). May be an empty string to delete the matched fragment. When the
+   * match came from tier 2 (raw markup), the full resulting body is re-run through
+   * the XSS sanitizer, so any dangerous markup in `newText` is stripped. Images
+   * inserted via edit_body are not uploaded to Featurebase storage — use
+   * articles.update with formatter 'raw' for image changes.
+   */
+  newText: string;
+
+  /**
+   * Body param: Exact fragment to find in the stored article body. Keep this to a
+   * fragment, not a whole document (max 10000 chars). Tier 1 matches only inside
+   * TEXT nodes (markup, tags, and attributes are never searched or altered) and is
+   * entity-aware, so `oldText: "A & B"` matches a stored `A &amp; B`. If tier 1
+   * finds nothing, tier 2 falls back to a literal substring match over the raw body
+   * string (markup included). Do NOT include `<img>` tags — their stored `src`
+   * differs from the API representation and will not match.
+   */
+  oldText: string;
+
+  /**
+   * Body param: Preview the edit without writing. Returns the match count, matching
+   * `mode`, and `previews` (changed spans with surrounding context) so an agent can
+   * verify the edit before committing. Recommended workflow: dry-run across a set of
+   * articles first, confirm the counts and previews, then re-issue each call with
+   * `dryRun: false`.
+   */
+  dryRun?: boolean;
+
+  /**
+   * Body param: Assert the exact number of matches. When set, the edit replaces all
+   * matches only if the count is exactly this value, otherwise it returns `400`.
+   * Takes precedence over `replaceAll`. Use this to make bulk edits safe: dry-run
+   * first to learn the count, then commit with the expected number.
+   */
+  expectedReplacements?: number;
+
+  /**
+   * Body param: Locale of the body to edit. Defaults to the help center's default
+   * locale.
+   */
+  locale?:
+    | 'bn'
+    | 'bs'
+    | 'pt-BR'
+    | 'bg'
+    | 'ca'
+    | 'hr'
+    | 'cs'
+    | 'da'
+    | 'nl'
+    | 'en'
+    | 'et'
+    | 'fi'
+    | 'fr'
+    | 'de'
+    | 'el'
+    | 'hi'
+    | 'hu'
+    | 'id'
+    | 'it'
+    | 'ja'
+    | 'ko'
+    | 'lv'
+    | 'lt'
+    | 'ms'
+    | 'mn'
+    | 'nb'
+    | 'pl'
+    | 'pt'
+    | 'ro'
+    | 'ru'
+    | 'sr'
+    | 'zh-CN'
+    | 'sk'
+    | 'sl'
+    | 'es'
+    | 'sw'
+    | 'sv'
+    | 'th'
+    | 'zh-TW'
+    | 'tr'
+    | 'uk'
+    | 'vi';
+
+  /**
+   * Body param: Replace every match. When omitted (or false) and
+   * `expectedReplacements` is not set, the edit requires exactly one match and
+   * returns `400` if `oldText` is ambiguous (found more than once). Provide more
+   * surrounding context in `oldText` to make a unique match, or set this to true.
+   */
+  replaceAll?: boolean;
+
+  /**
+   * Body param: Which body to edit: the unpublished `draft` (default) or the
+   * published `live` content. Editing `live` records a history snapshot and purges
+   * the public edge cache, mirroring a publish.
+   */
+  target?: 'draft' | 'live';
+
+  /**
+   * Header param: API version for this request. Defaults to your organization's
+   * configured API version if not specified.
+   */
+  'Featurebase-Version'?: '2026-01-01.nova' | '2025-12-12.clover';
+}
+
 export interface ArticleSearchParams {
   /**
    * Body param: An opaque cursor for pagination. Use the `nextCursor` value from a
@@ -1866,6 +2232,9 @@ export declare namespace Articles {
     type ArticleIconInputNova as ArticleIconInputNova,
     type ArticleTranslation as ArticleTranslation,
     type ArticleTranslationInputNova as ArticleTranslationInputNova,
+    type EditArticleBodyBody as EditArticleBodyBody,
+    type EditArticleBodyPreview as EditArticleBodyPreview,
+    type EditArticleBodyResponse as EditArticleBodyResponse,
     type ArticleDeleteResponse as ArticleDeleteResponse,
     type ArticleSearchResponse as ArticleSearchResponse,
     type ArticlesCursorPage as ArticlesCursorPage,
@@ -1874,6 +2243,7 @@ export declare namespace Articles {
     type ArticleRetrieveParams as ArticleRetrieveParams,
     type ArticleUpdateParams as ArticleUpdateParams,
     type ArticleDeleteParams as ArticleDeleteParams,
+    type ArticleEditBodyParams as ArticleEditBodyParams,
     type ArticleSearchParams as ArticleSearchParams,
   };
 }

package/src/resources/help-center/help-center.ts

@@ -8,6 +8,7 @@ import {
   ArticleCreateParams,
   ArticleDeleteParams,
   ArticleDeleteResponse,
+  ArticleEditBodyParams,
   ArticleIcon,
   ArticleIconInputNova,
   ArticleListParams,
@@ -19,6 +20,9 @@ import {
   ArticleUpdateParams,
   Articles,
   ArticlesCursorPage,
+  EditArticleBodyBody,
+  EditArticleBodyPreview,
+  EditArticleBodyResponse,
 } from './articles';
 import * as CollectionsAPI from './collections';
 import {
@@ -105,6 +109,9 @@ export declare namespace HelpCenter {
     type ArticleIconInputNova as ArticleIconInputNova,
     type ArticleTranslation as ArticleTranslation,
     type ArticleTranslationInputNova as ArticleTranslationInputNova,
+    type EditArticleBodyBody as EditArticleBodyBody,
+    type EditArticleBodyPreview as EditArticleBodyPreview,
+    type EditArticleBodyResponse as EditArticleBodyResponse,
     type ArticleDeleteResponse as ArticleDeleteResponse,
     type ArticleSearchResponse as ArticleSearchResponse,
     type ArticlesCursorPage as ArticlesCursorPage,
@@ -113,6 +120,7 @@ export declare namespace HelpCenter {
     type ArticleRetrieveParams as ArticleRetrieveParams,
     type ArticleUpdateParams as ArticleUpdateParams,
     type ArticleDeleteParams as ArticleDeleteParams,
+    type ArticleEditBodyParams as ArticleEditBodyParams,
     type ArticleSearchParams as ArticleSearchParams,
   };
 

package/src/resources/help-center/index.ts

@@ -8,6 +8,9 @@ export {
   type ArticleIconInputNova,
   type ArticleTranslation,
   type ArticleTranslationInputNova,
+  type EditArticleBodyBody,
+  type EditArticleBodyPreview,
+  type EditArticleBodyResponse,
   type ArticleDeleteResponse,
   type ArticleSearchResponse,
   type ArticleListParams,
@@ -15,6 +18,7 @@ export {
   type ArticleRetrieveParams,
   type ArticleUpdateParams,
   type ArticleDeleteParams,
+  type ArticleEditBodyParams,
   type ArticleSearchParams,
   type ArticlesCursorPage,
 } from './articles';