@saplingai/sapling-js 1.0.39 → 1.0.52

package/sapling/client.js

@@ -1,6 +1,61 @@
 import axios from "axios";
 import { v4 as uuidv4 } from 'uuid';
 
+// Value types an extract() field may declare; 'string' is the default.
+const EXTRACT_FIELD_TYPES = ['string', 'number', 'integer', 'boolean', 'date', 'list'];
+// Registers translate() accepts; the API rejects anything else with a 400.
+const TRANSLATE_FORMALITIES = ['formal', 'informal'];
+const SUMMARIZE_LENGTHS = ['short', 'medium', 'long'];
+// Reading levels simplify() accepts; the API rejects anything else with a 400.
+const SIMPLIFY_READING_LEVELS = ['plain', 'elementary', 'middle_school', 'high_school'];
+
+// Shared by styleguide() and saveStyleguideRuleset(). Shape/type checks only —
+// size limits (rule/description length) are server configuration and enforced
+// there with a clear 400 (see classify()).
+const validateStyleguideRules = (rules, method) => {
+  const isValidRule = (rule) => {
+    if (typeof rule === 'string') {
+      return rule.trim().length > 0;
+    }
+    if (rule == null || typeof rule !== 'object' || Array.isArray(rule)) {
+      return false;
+    }
+    if (typeof rule.name !== 'string' || rule.name.trim().length === 0) {
+      return false;
+    }
+    if (rule.description !== undefined && typeof rule.description !== 'string') {
+      return false;
+    }
+    // Reject unknown keys so a typo like `{ name, descrption: '...' }` fails
+    // here rather than being forwarded to the API as a malformed rule (the
+    // classify()/extract() convention; the MCP object schema is `.strict()`).
+    const allowed = new Set(['name', 'description']);
+    if (Object.keys(rule).some((key) => !allowed.has(key))) {
+      return false;
+    }
+    return true;
+  };
+
+  if (
+    !Array.isArray(rules)
+    || rules.length < 1
+    || rules.length > 20
+    // Array.from() materializes holes in sparse arrays as `undefined` (which
+    // isValidRule rejects); a bare `.every()` would skip them and let a hole
+    // through to be serialized as `null`.
+    || !Array.from(rules).every(isValidRule)
+  ) {
+    throw new TypeError(`${method}: rules must be an array of 1 to 20 non-empty strings or `
+      + '{name, description?} objects (string name, optional string description).');
+  }
+
+  const names = rules.map(
+    (rule) => (typeof rule === 'string' ? rule : rule.name).trim().toLowerCase());
+  if (names.length !== new Set(names).size) {
+    throw new TypeError(`${method}: rule names must be unique (case-insensitive).`);
+  }
+};
+
 export class Client {
   constructor(apiKey, options = {}) {
     this.apiKey = apiKey;
@@ -13,7 +68,7 @@ export class Client {
   }
 
   axiosPromise(url, method, data) {
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
       axios({
         url,
         method,
@@ -22,7 +77,8 @@ export class Client {
       })
       .then(function (response) {
           resolve(response);
-      });
+      })
+      .catch(reject);
     });
   }
 
@@ -56,6 +112,11 @@ export class Client {
       data.advanced_edits = options.advancedEdits;
     }
 
+    // Omitted unless set; an explicit null is forwarded so the API rejects it.
+    if (options.includeErrorCategories !== undefined) {
+      data.include_error_categories = options.includeErrorCategories;
+    }
+
     if (userDetails) {
       const { userId, anonUser } = userDetails;
       data.user_id = userId;
@@ -176,11 +237,304 @@ export class Client {
     return this.axiosPromise(url, 'post', data);
   }
 
+  /**
+   * Structured data extraction: pull caller-named fields out of unstructured text.
+   *
+   * `classify()` answers "what kind of text is this"; `extract()` answers "what's in it".
+   * Pass 1–20 fields — plain names, or `{name, type, description, required}` objects to
+   * declare the value type and sharpen ambiguous fields. Returns `data` (a
+   * `{field name: value}` map with every requested field present and `null` where the text
+   * didn't state it), `fields` (one entry per requested field, in request order, each with
+   * the verbatim `evidence` span the value came from) and `missing` (the names the text
+   * didn't yield).
+   *
+   * Values are coerced to the declared type server-side and must be grounded in a quote
+   * from the text, so this is extraction, not inference: a value that isn't stated is
+   * reported missing rather than guessed. Finding nothing is a normal 200.
+   *
+   * @param {string|string[]} text - The document to extract from, plain text or HTML (the
+   *   API caps it at 10,000 characters). Pass an array of 1–10 strings to extract from a
+   *   batch in one request (sent as the API's `texts` parameter; combined length capped at
+   *   10,000 chars) — the response is then `{results: [...]}` with one
+   *   single-response-shaped entry per input, in order.
+   * @param {Array<string|{name: string, type?: string, description?: string, required?: boolean}>} fields -
+   *   The fields to pull out (1–20): field names, or objects. `type` is one of 'string'
+   *   (default), 'number', 'integer', 'boolean', 'date' (returned as YYYY-MM-DD) or 'list'.
+   *   Names must be unique case-insensitively; the API caps names at 50 characters and
+   *   descriptions at 200.
+   * @param {Object} [options]
+   * @param {string} [options.context] - Optional guidance (the API caps it at 500
+   *   characters): what the document is and how to read ambiguous fields, e.g.
+   *   'A vendor invoice'.
+   * @returns {Promise<AxiosResponse>}
+   */
+  extract(text, fields, options = {}) {
+    const url = `${this.urlEndpoint}extract`;
+
+    // Shape/type checks only. Size limits (text length, field name/description/
+    // context length) are server configuration and enforced there with a clear
+    // 400 — mirroring them here would drift the day they change (and JS
+    // `length` counts UTF-16 units, not the characters the API counts).
+    // An array of texts is the batch form (sent as `texts`, one result per
+    // item); the 1–10 item bound is structural like the field count below.
+    const isBatch = Array.isArray(text);
+    if (isBatch) {
+      // for...of (not text.every) so holes in a sparse array are visited as
+      // undefined and rejected, rather than skipped.
+      let ok = text.length >= 1 && text.length <= 10;
+      for (const item of text) {
+        ok = ok && typeof item === 'string' && item.trim().length > 0;
+      }
+      if (!ok) {
+        throw new TypeError('extract: texts must be an array of 1 to 10 non-empty strings.');
+      }
+    } else if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('extract: text must be a non-empty string.');
+    }
+
+    const isValidField = (field) => {
+      if (typeof field === 'string') {
+        return field.trim().length > 0;
+      }
+      if (field == null || typeof field !== 'object' || Array.isArray(field)) {
+        return false;
+      }
+      if (typeof field.name !== 'string' || field.name.trim().length === 0) {
+        return false;
+      }
+      if (field.type !== undefined && !EXTRACT_FIELD_TYPES.includes(field.type)) {
+        return false;
+      }
+      if (field.description !== undefined && typeof field.description !== 'string') {
+        return false;
+      }
+      if (field.required !== undefined && typeof field.required !== 'boolean') {
+        return false;
+      }
+      // Reject unknown keys so a typo like `{ name, typ: 'number' }` fails here
+      // rather than being forwarded to the API as a malformed field (the MCP
+      // schema is `.strict()` for the same reason).
+      const allowed = new Set(['name', 'type', 'description', 'required']);
+      if (Object.keys(field).some((key) => !allowed.has(key))) {
+        return false;
+      }
+      return true;
+    };
+
+    if (
+      !Array.isArray(fields)
+      || fields.length < 1
+      || fields.length > 20
+      // Array.from() materializes holes in sparse arrays as `undefined` (which
+      // isValidField rejects); a bare `.every()` would skip them and let a hole
+      // through to be serialized as `null`.
+      || !Array.from(fields).every(isValidField)
+    ) {
+      throw new TypeError('extract: fields must be an array of 1 to 20 non-empty strings or '
+        + '{name, type?, description?, required?} objects (string name, type one of '
+        + `${EXTRACT_FIELD_TYPES.join(', ')}, optional string description, optional boolean required).`);
+    }
+
+    const names = fields.map((field) => (typeof field === 'string' ? field : field.name).toLowerCase());
+    if (names.length !== new Set(names).size) {
+      throw new TypeError('extract: field names must be unique (case-insensitive).');
+    }
+
+    let data = {
+      ...(isBatch ? { texts: text } : { text }),
+      fields,
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a bad
+    // type rather than silently treated as "omitted", matching how a null
+    // `description` is rejected above.
+    if (options?.context !== undefined) {
+      if (typeof options.context !== 'string') {
+        throw new TypeError('extract: context must be a string.');
+      }
+      data.context = options.context;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Translate text into a target language with an LLM.
+   *
+   * Line breaks, markup and placeholders are preserved in place, and the response
+   * reports the language the text was actually written in (detected — never assumed
+   * from the hint): `translation`, `source_lang`/`source_lang_name` (`'und'`/`null`
+   * when undetermined) and the normalized `target_lang`/`target_lang_name`.
+   *
+   * @param {string|string[]} text - The text to translate (the API caps it at
+   *   5,000 characters). Markup and whitespace are preserved, not stripped.
+   *   Pass an array of 1-10 strings to translate a batch in one request (sent
+   *   as the API's `texts` parameter; combined length up to 5,000 characters,
+   *   same target/source/formality applied to every item). A batch response is
+   *   `{results: [...]}` with one single-response-shaped entry per input, in
+   *   order.
+   * @param {string} targetLang - Language to translate into: an ISO 639 code
+   *   ('fr', 'zh-TW') or an English language name ('French'). Region variants
+   *   zh-CN/zh-TW/zh-HK, pt-BR/pt-PT, en-GB/en-US, fr-CA and es-419 are supported
+   *   as targets.
+   * @param {Object} [options]
+   * @param {string} [options.source_lang] - Optional hint for the source language,
+   *   same forms as targetLang. The text itself wins if they disagree.
+   * @param {string} [options.formality] - Optional register: 'formal'
+   *   (vous/Sie/usted) or 'informal' (tu/du/tú). Omit for the model default.
+   * @returns {Promise<AxiosResponse>}
+   */
+  translate(text, targetLang, options = {}) {
+    const url = `${this.urlEndpoint}translate`;
+
+    // Shape/type checks only; the language vocabulary and length caps are
+    // server configuration enforced there with a clear 400 (mirroring the
+    // 176-language table here would drift the day it changes).
+    // An array of texts is the batch form (SAP-398, sent as `texts`, one
+    // result per item); the 1–10 item bound is structural like safety's.
+    const isBatch = Array.isArray(text);
+    if (isBatch) {
+      // for...of (not text.every) so holes in a sparse array are visited as
+      // undefined and rejected, rather than skipped.
+      let ok = text.length >= 1 && text.length <= 10;
+      if (ok) {
+        for (const item of text) {
+          if (typeof item !== 'string' || item.trim().length === 0) {
+            ok = false;
+            break;
+          }
+        }
+      }
+      if (!ok) {
+        throw new TypeError('translate: texts must be an array of 1 to 10 non-empty strings.');
+      }
+    } else if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('translate: text must be a non-empty string.');
+    }
+    if (typeof targetLang !== 'string' || targetLang.trim().length === 0) {
+      throw new TypeError('translate: targetLang must be a non-empty string (an ISO 639 '
+        + 'code like "fr" or an English language name like "French").');
+    }
+
+    let data = {
+      ...(isBatch ? { texts: text } : { text }),
+      target_lang: targetLang,
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a
+    // bad type rather than silently treated as "omitted" (same as extract's
+    // context handling).
+    if (options?.source_lang !== undefined) {
+      if (typeof options.source_lang !== 'string' || options.source_lang.trim().length === 0) {
+        throw new TypeError('translate: source_lang must be a non-empty string.');
+      }
+      data.source_lang = options.source_lang;
+    }
+    if (options?.formality !== undefined) {
+      if (!TRANSLATE_FORMALITIES.includes(options.formality)) {
+        throw new TypeError('translate: formality must be one of '
+          + `${TRANSLATE_FORMALITIES.join(', ')}.`);
+      }
+      data.formality = options.formality;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Summarize a document, webpage or email thread into a prose summary plus
+   * key points.
+   *
+   * Returns `summary` (the prose summary), `key_points` (an array of strings),
+   * `length` (the option the summary was generated with) and `result`
+   * (mirrors `summary` — the endpoint's original response key, kept for
+   * backward compatibility).
+   *
+   * @param {string|string[]} text - The document to summarize, plain text or
+   *   HTML (tags are stripped; the API caps it at 20,000 characters). Pass an
+   *   array of 1-10 strings to summarize a batch in one request (sent as the
+   *   API's `texts` parameter; combined length up to 20,000 characters, same
+   *   length option applied to every item). A batch response is
+   *   `{results: [...]}` with one single-response-shaped entry per input, in
+   *   order.
+   * @param {Object} [options]
+   * @param {string} [options.length] - Optional summary length: 'short',
+   *   'medium' (the default) or 'long'.
+   * @returns {Promise<AxiosResponse>}
+   */
+  summarize(text, options = {}) {
+    const url = `${this.urlEndpoint}summarize`;
+
+    // An array of texts is the batch form (SAP-399, sent as `texts`, one
+    // result per item); the 1–10 item bound is structural like translate's.
+    const isBatch = Array.isArray(text);
+    if (isBatch) {
+      // for...of (not text.every) so holes in a sparse array are visited as
+      // undefined and rejected, rather than skipped.
+      let ok = text.length >= 1 && text.length <= 10;
+      if (ok) {
+        for (const item of text) {
+          if (typeof item !== 'string' || item.trim().length === 0) {
+            ok = false;
+            break;
+          }
+        }
+      }
+      if (!ok) {
+        throw new TypeError('summarize: texts must be an array of 1 to 10 non-empty strings.');
+      }
+    } else if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('summarize: text must be a non-empty string.');
+    }
+
+    let data = {
+      ...(isBatch ? { texts: text } : { text }),
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a
+    // bad type rather than silently treated as "omitted" (same as translate's
+    // formality handling).
+    if (options?.length !== undefined) {
+      if (!SUMMARIZE_LENGTHS.includes(options.length)) {
+        throw new TypeError('summarize: length must be one of '
+          + `${SUMMARIZE_LENGTHS.join(', ')}.`);
+      }
+      data.length = options.length;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
   langdetect(text, options = {}) {
     const url = `${this.urlEndpoint}langdetect`;
 
+    // An array of texts is the batch form (SAP-397, sent as `texts`, one
+    // result per item); the 1–10 item bound is structural like classify's.
+    // The single (string) form is passed through unvalidated, as it always
+    // has been — the server answers a clear 400.
+    const isBatch = Array.isArray(text);
+    if (isBatch) {
+      // for...of (not text.every) so holes in a sparse array are visited as
+      // undefined and rejected, rather than skipped.
+      let ok = text.length >= 1 && text.length <= 10;
+      if (ok) {
+        for (const item of text) {
+          if (typeof item !== 'string' || item.trim().length === 0) {
+            ok = false;
+            break;
+          }
+        }
+      }
+      if (!ok) {
+        throw new TypeError('langdetect: texts must be an array of 1 to 10 non-empty strings.');
+      }
+    }
+
     let data = {
-      text,
+      ...(isBatch ? { texts: text } : { text }),
       key: this.apiKey,
     }
 
@@ -194,11 +548,318 @@ export class Client {
     return this.axiosPromise(url, 'post', data);
   }
 
+  /**
+   * Zero-shot text classification: assign one (or several) of your own labels to a text.
+   *
+   * No training data needed — pass 2–20 candidate labels (plain names, or
+   * `{name, description}` objects; a short description per label sharpens borderline
+   * decisions). Returns `label` (best match, always one of your labels), `labels`
+   * (single-label: `[label]`; multi-label: every label with `score >= threshold`, possibly
+   * empty), `scores` (one `{label, score}` per input label, descending), a one-sentence
+   * `rationale` and the echoed `multi_label` mode.
+   *
+   * @param {string|string[]} text - Text to classify, plain text or HTML (the API caps it
+   *   at 10,000 chars). Pass an array of 1–10 strings to classify a batch in one request
+   *   (sent as the API's `texts` parameter; combined length capped at 10,000 chars) — the
+   *   response is then `{results: [...]}` with one single-response-shaped entry per input,
+   *   in order.
+   * @param {Array<string|{name: string, description?: string}>} labels - Candidate labels
+   *   (2–20). Names unique case-insensitively; the API caps names at 50 and descriptions at 200 chars.
+   * @param {Object} [options]
+   * @param {boolean} [options.multiLabel] - true: zero, one or several labels may apply
+   *   (independent 0–1 scores). Defaults to false: exactly one label (scores sum to ~1).
+   * @param {number} [options.threshold] - Multi-label cut-off on the per-label score (0–1,
+   *   default 0.5). Ignored in single-label mode.
+   * @param {string} [options.context] - Optional guidance (max 500 chars): what the texts
+   *   are and how to decide borderline cases, e.g. 'Support tickets for a SaaS billing product'.
+   * @returns {Promise<AxiosResponse>}
+   */
+  classify(text, labels, options = {}) {
+    const url = `${this.urlEndpoint}classify`;
+
+    // Shape/type checks only. Size limits (text length, label/description/
+    // context length) are server configuration and enforced there with a
+    // clear 400 — mirroring them here would drift the day they change (and
+    // JS `length` counts UTF-16 units, not the characters the API counts).
+    // An array of texts is the batch form (sent as `texts`, one result per
+    // item); the 1–10 item bound is structural like the label count below.
+    const isBatch = Array.isArray(text);
+    if (isBatch) {
+      // for...of (not text.every) so holes in a sparse array are visited as
+      // undefined and rejected, rather than skipped.
+      let ok = text.length >= 1 && text.length <= 10;
+      for (const item of text) {
+        ok = ok && typeof item === 'string' && item.trim().length > 0;
+      }
+      if (!ok) {
+        throw new TypeError('classify: texts must be an array of 1 to 10 non-empty strings.');
+      }
+    } else if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('classify: text must be a non-empty string.');
+    }
+
+    const isValidLabel = (label) => {
+      if (typeof label === 'string') {
+        return label.trim().length > 0;
+      }
+      if (label == null || typeof label !== 'object' || Array.isArray(label)) {
+        return false;
+      }
+      if (typeof label.name !== 'string' || label.name.trim().length === 0) {
+        return false;
+      }
+      if (label.description !== undefined && typeof label.description !== 'string') {
+        return false;
+      }
+      // Reject unknown keys so a typo like `{ name, descrption: '...' }` fails
+      // here rather than being forwarded to the API as a malformed label (the
+      // MCP object schema is `.strict()` and `extract()` does the same).
+      const allowed = new Set(['name', 'description']);
+      if (Object.keys(label).some((key) => !allowed.has(key))) {
+        return false;
+      }
+      return true;
+    };
+
+    if (
+      !Array.isArray(labels)
+      || labels.length < 2
+      || labels.length > 20
+      // Array.from() materializes holes in sparse arrays as `undefined` (which
+      // isValidLabel rejects); a bare `.every()` would skip them and let a hole
+      // through to be serialized as `null`.
+      || !Array.from(labels).every(isValidLabel)
+    ) {
+      throw new TypeError('classify: labels must be an array of 2 to 20 non-empty strings or '
+        + '{name, description?} objects (string name, optional string description).');
+    }
+
+    const names = labels.map((label) => (typeof label === 'string' ? label : label.name).toLowerCase());
+    if (names.length !== new Set(names).size) {
+      throw new TypeError('classify: label names must be unique (case-insensitive).');
+    }
+
+    let data = {
+      ...(isBatch ? { texts: text } : { text }),
+      labels,
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a bad
+    // type rather than silently treated as "omitted", matching how a null
+    // `description` is rejected above.
+    if (options?.multiLabel !== undefined) {
+      if (typeof options.multiLabel !== 'boolean') {
+        throw new TypeError('classify: multiLabel must be a boolean.');
+      }
+      data.multi_label = options.multiLabel;
+    }
+    if (options?.threshold !== undefined) {
+      if (typeof options.threshold !== 'number' || !Number.isFinite(options.threshold)
+        || options.threshold < 0 || options.threshold > 1) {
+        throw new TypeError('classify: threshold must be a finite number between 0 and 1.');
+      }
+      data.threshold = options.threshold;
+    }
+    if (options?.context !== undefined) {
+      if (typeof options.context !== 'string') {
+        throw new TypeError('classify: context must be a string.');
+      }
+      data.context = options.context;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * SEO analysis and metadata generation for a page or article body (plain text or HTML).
+   *
+   * Always returns deterministic `stats` (word/sentence/paragraph counts, reading time,
+   * Flesch readability), `keywords` (count/density/in_first_100_words for each target
+   * keyword) and `top_terms` (most frequent unigrams/bigrams). By default also returns
+   * LLM-generated `suggestions` (titles, meta_descriptions, slug — null when no ASCII slug
+   * can be derived — and keywords) — pass
+   * `suggestions: false` for the free stats-only mode.
+   *
+   * @param {string} text - Page/article body, plain text or HTML (max 20,000 chars).
+   * @param {Object} [options]
+   * @param {string[]} [options.keywords] - Target keyword phrases, most important first
+   *   (max 10, each 1–100 chars). Measured in the text and steered into the suggestions.
+   * @param {boolean} [options.suggestions] - Generate LLM suggestions. Defaults to true;
+   *   false returns stats/keywords/top_terms only (unbilled).
+   * @param {string} [options.lang] - ISO 639-1 language code of the text (region subtag
+   *   allowed, e.g. 'pt-BR'; or 'auto'). Defaults to 'en'. Only selects the readability
+   *   formulas: supported for en/de/es/fr/it/nl/pl/ru, otherwise flesch_reading_ease /
+   *   flesch_kincaid_grade are null.
+   * @returns {Promise<AxiosResponse>}
+   */
+  seo(text, options = {}) {
+    const url = `${this.urlEndpoint}seo`;
+
+    // Shape/type checks only. Size limits (text length, keyword count/length)
+    // are server configuration and enforced there with a clear 400 — mirroring
+    // them here would drift the day they change (and JS `length` counts UTF-16
+    // units, not the characters the API counts).
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('seo: text must be a non-empty string.');
+    }
+
+    let data = {
+      text,
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a bad
+    // type rather than silently treated as "omitted", matching classify().
+    if (options?.keywords !== undefined) {
+      if (!Array.isArray(options.keywords)
+        || !Array.from(options.keywords).every((k) => typeof k === 'string' && k.trim().length > 0)) {
+        throw new TypeError('seo: keywords must be an array of non-empty strings.');
+      }
+      data.keywords = options.keywords;
+    }
+    if (options?.suggestions !== undefined) {
+      if (typeof options.suggestions !== 'boolean') {
+        throw new TypeError('seo: suggestions must be a boolean.');
+      }
+      data.suggestions = options.suggestions;
+    }
+    if (options?.lang !== undefined) {
+      if (typeof options.lang !== 'string') {
+        throw new TypeError('seo: lang must be a string.');
+      }
+      data.lang = options.lang;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  quality(text, options = {}) {
+    const url = `${this.urlEndpoint}quality`;
+
+    // Shape/type checks only; size limits are server configuration (see seo()).
+    // An array of texts is the batch form (SAP-400, sent as `texts`, one
+    // result per item); the 1–10 item bound is structural like classify's.
+    const isBatch = Array.isArray(text);
+    if (isBatch) {
+      // for...of (not text.every) so holes in a sparse array are visited as
+      // undefined and rejected, rather than skipped.
+      let ok = text.length >= 1 && text.length <= 10;
+      if (ok) {
+        for (const item of text) {
+          if (typeof item !== 'string' || item.trim().length === 0) {
+            ok = false;
+            break;
+          }
+        }
+      }
+      if (!ok) {
+        throw new TypeError('quality: texts must be an array of 1 to 10 non-empty strings.');
+      }
+    } else if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('quality: text must be a non-empty string.');
+    }
+
+    let data = {
+      ...(isBatch ? { texts: text } : { text }),
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a bad
+    // type rather than silently treated as "omitted", matching classify()/seo().
+    if (options?.sentence_scores !== undefined) {
+      if (typeof options.sentence_scores !== 'boolean') {
+        throw new TypeError('quality: sentence_scores must be a boolean.');
+      }
+      data.sentence_scores = options.sentence_scores;
+    }
+    if (options?.rubric !== undefined) {
+      if (typeof options.rubric !== 'boolean') {
+        throw new TypeError('quality: rubric must be a boolean.');
+      }
+      data.rubric = options.rubric;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  safety(text, options = {}) {
+    const url = `${this.urlEndpoint}safety`;
+
+    // Shape/type checks only; size limits are server configuration (see seo()).
+    // An array of texts is the batch form (SAP-397, sent as `texts`, one
+    // result per item); the 1–10 item bound is structural like classify's.
+    const isBatch = Array.isArray(text);
+    if (isBatch) {
+      // for...of (not text.every) so holes in a sparse array are visited as
+      // undefined and rejected, rather than skipped.
+      let ok = text.length >= 1 && text.length <= 10;
+      if (ok) {
+        for (const item of text) {
+          if (typeof item !== 'string' || item.trim().length === 0) {
+            ok = false;
+            break;
+          }
+        }
+      }
+      if (!ok) {
+        throw new TypeError('safety: texts must be an array of 1 to 10 non-empty strings.');
+      }
+    } else if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('safety: text must be a non-empty string.');
+    }
+
+    let data = {
+      ...(isBatch ? { texts: text } : { text }),
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a bad
+    // type rather than silently treated as "omitted", matching classify().
+    if (options?.threshold !== undefined) {
+      if (typeof options.threshold !== 'number' || !Number.isFinite(options.threshold)
+        || options.threshold < 0 || options.threshold > 1) {
+        throw new TypeError('safety: threshold must be a finite number between 0 and 1.');
+      }
+      data.threshold = options.threshold;
+    }
+    if (options?.spans !== undefined) {
+      if (typeof options.spans !== 'boolean') {
+        throw new TypeError('safety: spans must be a boolean.');
+      }
+      data.spans = options.spans;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
   aidetect(text, options = {}) {
     const url = `${this.urlEndpoint}aidetect`;
 
+    // An array of texts is the batch form (SAP-403, sent as `texts`, one
+    // result per item); the 1–10 item bound is structural like classify's.
+    // The single form keeps its historical no-validation behavior (the
+    // server 400s clearly on a bad `text`).
+    const isBatch = Array.isArray(text);
+    if (isBatch) {
+      // for...of (not text.every) so holes in a sparse array are visited as
+      // undefined and rejected, rather than skipped.
+      let ok = text.length >= 1 && text.length <= 10;
+      if (ok) {
+        for (const item of text) {
+          if (typeof item !== 'string' || item.trim().length === 0) {
+            ok = false;
+            break;
+          }
+        }
+      }
+      if (!ok) {
+        throw new TypeError('aidetect: texts must be an array of 1 to 10 non-empty strings.');
+      }
+    }
+
     let data = {
-      text,
+      ...(isBatch ? { texts: text } : { text }),
       key: this.apiKey,
     }
 
@@ -208,4 +869,398 @@ export class Client {
 
     return this.axiosPromise(url, 'post', data);
   }
+
+  /**
+   * Check a text for compliance with style rules you supply (house style,
+   * brand voice, editorial guidelines). Only the listed rules are enforced.
+   *
+   * Returns `violations` (one `{rule, text, start, end, note, suggestion}`
+   * entry per violation, most important first — `start`/`end` index the
+   * submitted text and are null when the passage cannot be located), `rules`
+   * (the checked rule names) and `compliant` (true when no violations were
+   * found). The text is checked exactly as submitted — markup is NOT
+   * stripped, so offsets always index the string you sent.
+   *
+   * @param {string|string[]} text - The text to check (the API caps it at
+   *   10,000 characters), or an array of 1–10 texts for the batch form (sent
+   *   as the API's `texts` parameter; combined length up to 10,000
+   *   characters, same rules applied to every item). A batch response is
+   *   `{results: [...]}` with one single-response-shaped entry per input, in
+   *   order, each item's violation offsets indexing that item's own text.
+   * @param {Array<string|{name: string, description?: string}>|string} rules
+   *   - 1 to 20 style rules: a rule name (max 80 chars) or a
+   *   `{name, description}` object whose optional description (max 400
+   *   chars) carries the nuance the model follows. Names must be unique
+   *   case-insensitively. OR a string: the name of a saved ruleset (see
+   *   saveStyleguideRuleset()) to check against, matched case-insensitively
+   *   within the API key's account.
+   * @returns {Promise<AxiosResponse>}
+   */
+  styleguide(text, rules) {
+    const url = `${this.urlEndpoint}styleguide`;
+
+    // Shape/type checks only. Size limits (text/rule/description length) are
+    // server configuration and enforced there with a clear 400 (see
+    // classify()).
+    // An array of texts is the batch form (SAP-412, sent as `texts`, one
+    // result per item); the 1–10 item bound is structural like classify's.
+    const isBatch = Array.isArray(text);
+    if (isBatch) {
+      // for...of (not text.every) so holes in a sparse array are visited as
+      // undefined and rejected, rather than skipped.
+      let ok = text.length >= 1 && text.length <= 10;
+      if (ok) {
+        for (const item of text) {
+          if (typeof item !== 'string' || item.trim().length === 0) {
+            ok = false;
+            break;
+          }
+        }
+      }
+      if (!ok) {
+        throw new TypeError('styleguide: texts must be an array of 1 to 10 non-empty strings.');
+      }
+    } else if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('styleguide: text must be a non-empty string.');
+    }
+
+    // A string names a saved ruleset (see saveStyleguideRuleset()) and is
+    // sent as the API's `ruleset` parameter in place of inline `rules`.
+    const isSavedRuleset = typeof rules === 'string';
+    if (isSavedRuleset) {
+      if (rules.trim().length === 0) {
+        throw new TypeError('styleguide: ruleset name must be a non-empty string.');
+      }
+    } else {
+      validateStyleguideRules(rules, 'styleguide');
+    }
+
+    let data = {
+      ...(isBatch ? { texts: text } : { text }),
+      ...(isSavedRuleset ? { ruleset: rules } : { rules }),
+      key: this.apiKey,
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * List the saved style-guide rulesets of this API key's account (its team,
+   * for team-scoped keys — a team's rulesets are shared by every caller of
+   * its keys). Requires a per-account API key.
+   *
+   * Returns `rulesets`: `{name, rules, created_at, updated_at}` entries whose
+   * `rules` are the normalized `{name, description}` objects the check
+   * endpoint applies.
+   *
+   * @returns {Promise<AxiosResponse>}
+   */
+  styleguideRulesets() {
+    const url = `${this.urlEndpoint}styleguide/rulesets`;
+    // Not axiosPromise: this is a GET and the key rides the query string.
+    return axios({
+      url,
+      method: 'get',
+      params: { key: this.apiKey },
+      timeout: this.timeout,
+    });
+  }
+
+  /**
+   * Create — or replace, when the name already exists (matched
+   * case-insensitively) — a saved style-guide ruleset, so later
+   * `styleguide(text, name)` calls check against it by name. Owned by the
+   * API key's account (its team, for team-scoped keys). Requires a
+   * per-account API key.
+   *
+   * Returns `ruleset` (the saved `{name, rules, created_at, updated_at}`)
+   * and `created` (false when an existing ruleset was replaced).
+   *
+   * @param {string} name - The ruleset name (the API caps it at 100
+   *   characters; surrounding/duplicate whitespace is normalized).
+   * @param {Array<string|{name: string, description?: string}>} rules - The
+   *   rules to save; same shape and bounds as styleguide()'s inline rules.
+   * @returns {Promise<AxiosResponse>}
+   */
+  saveStyleguideRuleset(name, rules) {
+    const url = `${this.urlEndpoint}styleguide/rulesets`;
+    if (typeof name !== 'string' || name.trim().length === 0) {
+      throw new TypeError('saveStyleguideRuleset: name must be a non-empty string.');
+    }
+    validateStyleguideRules(rules, 'saveStyleguideRuleset');
+
+    let data = {
+      name,
+      rules,
+      key: this.apiKey,
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Delete a saved style-guide ruleset by name (matched case-insensitively;
+   * 404 when no such ruleset exists). Requires a per-account API key.
+   *
+   * @param {string} name - The ruleset name to delete.
+   * @returns {Promise<AxiosResponse>}
+   */
+  deleteStyleguideRuleset(name) {
+    const url = `${this.urlEndpoint}styleguide/rulesets`;
+    if (typeof name !== 'string' || name.trim().length === 0) {
+      throw new TypeError('deleteStyleguideRuleset: name must be a non-empty string.');
+    }
+    // The name rides the query string: some HTTP stacks drop DELETE bodies,
+    // and the API accepts the query form for exactly that reason.
+    return axios({
+      url,
+      method: 'delete',
+      params: { key: this.apiKey, name },
+      timeout: this.timeout,
+    });
+  }
+
+  /**
+   * Rewrite a text in plain language at a target reading level, keeping all
+   * of its content, structure and language — nothing is summarized or
+   * dropped.
+   *
+   * Returns `simplified` (the rewrite, structure preserved), the applied
+   * `reading_level`, the `lang` the readability scores were computed for
+   * (detected when not supplied) and, when that language supports scoring, a
+   * `readability` block: `{before: {grade, ease}, after: {grade, ease}}`
+   * Flesch-Kincaid scores, so the improvement is verifiable.
+   *
+   * @param {string|string[]} text - The text to simplify (the API caps it at
+   *   5,000 characters), or an array of 1–10 texts for the batch form (sent
+   *   as the API's `texts` parameter; combined length up to 5,000
+   *   characters, same options applied to every item). A batch response is
+   *   `{results: [...]}` with one single-response-shaped entry per input, in
+   *   order; with `lang` omitted, each item's language (and readability
+   *   scores) is detected on its own. Sent to the model as submitted —
+   *   markup and line structure are preserved, not stripped.
+   * @param {Object} [options]
+   * @param {string} [options.reading_level] - Target audience: 'plain'
+   *   (plain-language style for a general audience, the API default),
+   *   'elementary' (~US grade 3-5), 'middle_school' (~grade 6-8) or
+   *   'high_school' (~grade 9-10).
+   * @param {string[]} [options.preserve_terms] - Up to 20 terms (each up to
+   *   100 characters) the rewrite must keep exactly as written — product
+   *   names, defined legal terms. A rewrite that drops one is refused
+   *   server-side rather than returned.
+   * @param {string} [options.lang] - ISO 639-1 code used to pick the
+   *   readability formula for the before/after scores. Omit for
+   *   auto-detection (falls back to 'en'). The rewrite itself always stays
+   *   in the text's own language.
+   * @returns {Promise<AxiosResponse>}
+   */
+  simplify(text, options = {}) {
+    const url = `${this.urlEndpoint}simplify`;
+
+    // Shape/type checks only. Size limits (text/term length) are server
+    // configuration and enforced there with a clear 400 (see classify()).
+    // An array of texts is the batch form (SAP-412, sent as `texts`, one
+    // result per item); the 1–10 item bound is structural like classify's.
+    const isBatch = Array.isArray(text);
+    if (isBatch) {
+      // for...of (not text.every) so holes in a sparse array are visited as
+      // undefined and rejected, rather than skipped.
+      let ok = text.length >= 1 && text.length <= 10;
+      if (ok) {
+        for (const item of text) {
+          if (typeof item !== 'string' || item.trim().length === 0) {
+            ok = false;
+            break;
+          }
+        }
+      }
+      if (!ok) {
+        throw new TypeError('simplify: texts must be an array of 1 to 10 non-empty strings.');
+      }
+    } else if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('simplify: text must be a non-empty string.');
+    }
+
+    let data = {
+      ...(isBatch ? { texts: text } : { text }),
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a
+    // bad type rather than silently treated as "omitted" (same as translate's
+    // option handling).
+    if (options?.reading_level !== undefined) {
+      if (!SIMPLIFY_READING_LEVELS.includes(options.reading_level)) {
+        throw new TypeError('simplify: reading_level must be one of '
+          + `${SIMPLIFY_READING_LEVELS.join(', ')}.`);
+      }
+      data.reading_level = options.reading_level;
+    }
+    if (options?.preserve_terms !== undefined) {
+      const terms = options.preserve_terms;
+      // An empty list is a valid no-op (callers may build it dynamically); it
+      // is simply omitted from the payload below rather than rejected.
+      // for...of (not terms.every) so holes in a sparse array are visited as
+      // undefined and rejected, rather than skipped.
+      let ok = Array.isArray(terms) && terms.length <= 20;
+      if (ok) {
+        for (const term of terms) {
+          if (typeof term !== 'string' || term.trim().length === 0) {
+            ok = false;
+            break;
+          }
+        }
+      }
+      if (!ok) {
+        throw new TypeError('simplify: preserve_terms must be an array of up to 20 '
+          + 'non-empty strings.');
+      }
+      if (terms.length > 0) {
+        data.preserve_terms = terms;
+      }
+    }
+    if (options?.lang !== undefined) {
+      if (typeof options.lang !== 'string' || options.lang.trim().length === 0) {
+        throw new TypeError('simplify: lang must be a non-empty string.');
+      }
+      data.lang = options.lang;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  pii(text, options = {}) {
+    const url = `${this.urlEndpoint}pii`;
+
+    // Shape/type checks only; the set of valid PII types is server configuration
+    // and enforced there with a clear 400 (see seo()).
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('pii: text must be a non-empty string.');
+    }
+
+    let data = {
+      text,
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a bad
+    // type rather than silently treated as "omitted", matching classify()/seo().
+    if (options?.types !== undefined) {
+      if (!Array.isArray(options.types)
+        || !Array.from(options.types).every((type) => typeof type === 'string' && type.trim().length > 0)) {
+        throw new TypeError('pii: types must be an array of non-empty strings.');
+      }
+      data.types = options.types;
+    }
+    if (options?.redact !== undefined) {
+      if (typeof options.redact !== 'boolean') {
+        throw new TypeError('pii: redact must be a boolean.');
+      }
+      data.redact = options.redact;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Named-entity recognition: people, organizations, locations, dates, times,
+   * money amounts, percentages, quantities, products, and events, each with
+   * character offsets into the exact text submitted (nothing is stripped or
+   * normalized, so spans apply directly to your copy of the document).
+   * Complements pii(): that finds checksum-validated identifiers, this finds
+   * names and real-world references.
+   *
+   * @param {string|string[]} text - The text to analyze, or an array of 1–10
+   *   texts for the batch form (sent as the API's `texts` parameter; combined
+   *   length up to 10,000 characters, same types applied to every item). A
+   *   batch response is `{results: [...]}` with one single-response-shaped
+   *   entry per input, in order, each item's spans indexing that item's own
+   *   text.
+   * @param {Object} [options]
+   * @param {string[]} [options.types] - Entity types to recognize (subset of
+   *   the API's supported types). Default: all of them.
+   */
+  ner(text, options = {}) {
+    const url = `${this.urlEndpoint}ner`;
+
+    // Shape/type checks only; the set of valid entity types is server
+    // configuration and enforced there with a clear 400 (see pii()).
+    // An array of texts is the batch form (SAP-395 series, sent as `texts`,
+    // one result per item); the 1–10 item bound is structural like classify's.
+    const isBatch = Array.isArray(text);
+    if (isBatch) {
+      // for...of (not text.every) so holes in a sparse array are visited as
+      // undefined and rejected, rather than skipped.
+      let ok = text.length >= 1 && text.length <= 10;
+      if (ok) {
+        for (const item of text) {
+          if (typeof item !== 'string' || item.trim().length === 0) {
+            ok = false;
+            break;
+          }
+        }
+      }
+      if (!ok) {
+        throw new TypeError('ner: texts must be an array of 1 to 10 non-empty strings.');
+      }
+    } else if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('ner: text must be a non-empty string.');
+    }
+
+    let data = {
+      ...(isBatch ? { texts: text } : { text }),
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a bad
+    // type rather than silently treated as "omitted", matching pii().
+    // Reject an empty list too: the MCP schema requires at least one type
+    // (min(1)), so an empty array is typed-valid input that would otherwise
+    // become an avoidable API error.
+    if (options?.types !== undefined) {
+      if (!Array.isArray(options.types) || options.types.length === 0
+        || !Array.from(options.types).every((type) => typeof type === 'string' && type.trim().length > 0)) {
+        throw new TypeError('ner: types must be a non-empty array of non-empty strings.');
+      }
+      data.types = options.types;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Check whether an account-wide block (expired key/subscription,
+   * depleted credits, billing limit, trial daily allowance, monthly quota)
+   * stops this API key from making billable calls, and if so why and for
+   * how long. Works while the key is blocked, which is when it is most
+   * useful: call it after an unexpected 402 or monthly-quota 429 instead of
+   * parsing the error text. It does not reflect a single endpoint's
+   * short-term rate limit (each endpoint has its own bucket), so a
+   * "Capacity used." 429 elsewhere can coexist with api_access: true — use
+   * that 429's retry_after / X-RateLimit-* headers instead. Unbilled, but each call draws a fixed 2,000
+   * characters from its own rate-limit bucket, so don't poll it per request.
+   * Requires a per-account API key; the public demo key and MCP OAuth
+   * access tokens get a 403.
+   *
+   * Always returns `api_access`, `blocked_reason` (null, or one of
+   * key_expired, subscription_expired, credits_depleted,
+   * monthly_billing_limit, trial_daily_limit, monthly_quota_exhausted),
+   * `message` and `usage` ({monthly_quota_chars}); `retry_after` (seconds)
+   * only when blocked. Keys that are not team-scoped also get
+   * `usage.month_start`/`usage.chars_this_month`, `subscription`, `credits`
+   * and, for free-trial accounts, `trial`.
+   *
+   * @returns {Promise<AxiosResponse>}
+   */
+  accountStatus() {
+    const url = `${this.urlEndpoint}account/status`;
+    // Not axiosPromise: this is a GET and the key rides the query string,
+    // like styleguideRulesets().
+    return axios({
+      url,
+      method: 'get',
+      params: { key: this.apiKey },
+      timeout: this.timeout,
+    });
+  }
 }