@saplingai/sapling-js 1.0.45 → 1.0.53

package/sapling/client.js

@@ -3,6 +3,76 @@ 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'];
+// rephrase() enums, mirroring the API's validators (utils/request_validator.py),
+// which reject anything else with a 400.
+const REPHRASE_MAPPINGS = [
+  'paraphrase', 'passive_to_active', 'active_to_passive', 'informal_to_formal',
+  'formal_to_informal', 'sentence_split', 'reword', 'generate_title', 'generate_acronym',
+  'generate_meta_description', 'summarize', 'expand', 'shorten', 'switch_tone', 'switch_tense',
+];
+const REPHRASE_TONE_MAPPINGS = [
+  'straightforward', 'confident', 'friendly', 'empathetic', 'professional', 'casual',
+  'diplomatic', 'persuasive',
+];
+const REPHRASE_TENSE_MAPPINGS = [
+  'simple past', 'past perfect', 'past continuous', 'past perfect continuous',
+  'simple present', 'present perfect', 'present continuous', 'present perfect continuous',
+  'simple future', 'future perfect', 'future continuous', 'future perfect continuous',
+];
+// Languages statistics() scores readability for (plus 'auto').
+const STATISTICS_LANGS = ['en', 'de', 'es', 'fr', 'it', 'nl', 'pl', 'ru', 'ar'];
+
+// 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 = {}) {
@@ -60,6 +130,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;
@@ -180,6 +255,286 @@ export class Client {
     return this.axiosPromise(url, 'post', data);
   }
 
+  /**
+   * Rephrase / paraphrase: generate alternative phrasings of a text.
+   *
+   * Returns `results`: one `{hash, original, replacement, rephrase_type,
+   * model_version}` entry per alternative. HTML is stripped server-side.
+   *
+   * @param {string} text - The text to rephrase (the API caps its length).
+   * @param {Object} [options]
+   * @param {string} [options.mapping] - Transformation to apply (see
+   *   REPHRASE_MAPPINGS). Defaults to 'paraphrase'.
+   * @param {string} [options.tone_mapping] - Target tone; only used with
+   *   mapping 'switch_tone'. Defaults to 'straightforward'.
+   * @param {string} [options.tense_mapping] - Target tense; only used with
+   *   mapping 'switch_tense'. Defaults to 'simple past'.
+   * @param {number} [options.num_results] - Number of alternatives, 1–8
+   *   (default 5). Honored by the paraphrase, informal_to_formal,
+   *   formal_to_informal, generate_title and generate_acronym mappings; other
+   *   mappings return their default number of results.
+   * @param {string} [options.session_id] - Optional session identifier used to
+   *   group feedback events.
+   * @returns {Promise<AxiosResponse>}
+   */
+  rephrase(text, options = {}) {
+    const url = `${this.urlEndpoint}rephrase`;
+
+    // Shape/type/enum checks only; the length cap is server configuration and
+    // enforced there with a clear 400 (see seo()). The enums and the 1–8
+    // num_results bound mirror the API's validators, which reject anything else.
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('rephrase: 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?.mapping !== undefined) {
+      if (!REPHRASE_MAPPINGS.includes(options.mapping)) {
+        throw new TypeError(`rephrase: mapping must be one of ${REPHRASE_MAPPINGS.join(', ')}.`);
+      }
+      data.mapping = options.mapping;
+    }
+    if (options?.tone_mapping !== undefined) {
+      if (!REPHRASE_TONE_MAPPINGS.includes(options.tone_mapping)) {
+        throw new TypeError(
+          `rephrase: tone_mapping must be one of ${REPHRASE_TONE_MAPPINGS.join(', ')}.`);
+      }
+      data.tone_mapping = options.tone_mapping;
+    }
+    if (options?.tense_mapping !== undefined) {
+      if (!REPHRASE_TENSE_MAPPINGS.includes(options.tense_mapping)) {
+        throw new TypeError(
+          `rephrase: tense_mapping must be one of ${REPHRASE_TENSE_MAPPINGS.join(', ')}.`);
+      }
+      data.tense_mapping = options.tense_mapping;
+    }
+    if (options?.num_results !== undefined) {
+      if (!Number.isInteger(options.num_results)
+        || options.num_results < 1 || options.num_results > 8) {
+        throw new TypeError('rephrase: num_results must be an integer from 1 to 8.');
+      }
+      data.num_results = options.num_results;
+    }
+    if (options?.session_id !== undefined) {
+      if (typeof options.session_id !== 'string') {
+        throw new TypeError('rephrase: session_id must be a string.');
+      }
+      data.session_id = options.session_id;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Sentiment analysis: positive / neutral / negative, overall and per sentence.
+   *
+   * Returns `sents` (the sentences found), `overall` (a list of
+   * `[probability, label]` pairs, most likely first) and `results` (one such
+   * list per sentence, aligned with `sents`). Labels are 'POSITIVE',
+   * 'NEUTRAL' or 'NEGATIVE'. A text with no sentences gets a 204 with no body
+   * (axios gives `data === ''`), and a text the API cannot split into
+   * sentences gets a 200 with `[]`.
+   *
+   * @param {string} text - The text to analyze, plain text or HTML (tags are
+   *   stripped server-side; the API caps its length).
+   * @returns {Promise<AxiosResponse>}
+   */
+  sentiment(text) {
+    const url = `${this.urlEndpoint}sentiment`;
+
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('sentiment: text must be a non-empty string.');
+    }
+
+    let data = {
+      text,
+      key: this.apiKey,
+    }
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Readability statistics: character / word / sentence counts, reading time
+   * and readability grades.
+   *
+   * Returns `chars`, `words`, `sentences`, `reading_time_sec`,
+   * `reading_time_min`, `readability` (a Flesch-Kincaid grade level, -3.4 when
+   * it cannot be scored) and `readability_scores` (a map of formula name to
+   * score; which formulas appear depends on `lang`, and it is empty for
+   * 'auto'). Unbilled.
+   *
+   * @param {string} text - The text to measure, plain text or HTML (tags are
+   *   stripped server-side; the API caps it at 100,000 characters).
+   * @param {Object} [options]
+   * @param {string} [options.lang] - Language of the text: one of
+   *   STATISTICS_LANGS ('en', 'de', 'es', 'fr', 'it', 'nl', 'pl', 'ru', 'ar')
+   *   or 'auto'. Defaults to 'en'.
+   * @returns {Promise<AxiosResponse>}
+   */
+  statistics(text, options = {}) {
+    const url = `${this.urlEndpoint}statistics`;
+
+    // An empty text is a valid request (all-zero counts), so only the type is
+    // checked here.
+    if (typeof text !== 'string') {
+      throw new TypeError('statistics: text must be a string.');
+    }
+
+    let data = {
+      text,
+      key: this.apiKey,
+    }
+
+    if (options?.lang !== undefined) {
+      if (options.lang !== 'auto' && !STATISTICS_LANGS.includes(options.lang)) {
+        throw new TypeError(
+          `statistics: lang must be 'auto' or one of ${STATISTICS_LANGS.join(', ')}.`);
+      }
+      data.lang = options.lang;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Similar terms: thesaurus synonyms plus semantically similar terms for a
+   * word or short phrase.
+   *
+   * Returns `neighbors` (up to 5 `[similarity, term]` pairs from embedding
+   * similarity, similarity 0–1, most similar first; only alphabetic terms)
+   * and `synonyms` (WordNet lemma names — multi-word ones use underscores,
+   * e.g. 'domestic_dog'). Unbilled.
+   *
+   * @param {string} query - The word or phrase to look up (the API uses only
+   *   its first 100 characters).
+   * @returns {Promise<AxiosResponse>}
+   */
+  similarTerms(query) {
+    const url = `${this.urlEndpoint}thesaurus`;
+
+    // The API answers a blank query with a 400.
+    if (typeof query !== 'string' || query.trim().length === 0) {
+      throw new TypeError('similarTerms: query must be a non-empty string.');
+    }
+
+    let data = {
+      query,
+      key: this.apiKey,
+    }
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Profanity filter: label each whitespace-separated token of a text.
+   *
+   * Returns `toks` (the text split on whitespace; punctuation stays attached,
+   * e.g. 'stupid.') and `labels` (aligned with `toks`: 1 for profanity, 0
+   * otherwise). The text is not HTML-stripped. Unbilled.
+   *
+   * @param {string} text - The text to check.
+   * @returns {Promise<AxiosResponse>}
+   */
+  profanity(text) {
+    const url = `${this.urlEndpoint}profanity`;
+
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('profanity: text must be a non-empty string.');
+    }
+
+    let data = {
+      text,
+      key: this.apiKey,
+    }
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * List the custom dictionary of this API key's account: words the grammar
+   * and spelling checks accept as correct.
+   *
+   * Returns a bare array of `{id, entry, case_sensitive, created_at,
+   * updated_at}` entries, sorted by entry (timestamps are RFC 1123 strings).
+   *
+   * @returns {Promise<AxiosResponse>}
+   */
+  dictionaryEntries() {
+    const url = `${this.urlEndpoint}dictionary`;
+    // 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,
+    });
+  }
+
+  /**
+   * Add a word to this API key's account dictionary so the grammar and
+   * spelling checks stop flagging it (product names, jargon...).
+   *
+   * Returns the created `{id, entry, case_sensitive, created_at, updated_at}`
+   * entry. The API answers 400 for a duplicate entry ("Entry already
+   * exists.") and for an entry with more than two digits.
+   *
+   * @param {string} entry - The word to add (surrounding whitespace is
+   *   stripped server-side).
+   * @param {Object} [options]
+   * @param {boolean} [options.case_sensitive] - Whether matching is case
+   *   sensitive. Defaults to true.
+   * @returns {Promise<AxiosResponse>}
+   */
+  addDictionaryEntry(entry, options = {}) {
+    const url = `${this.urlEndpoint}dictionary`;
+
+    if (typeof entry !== 'string' || entry.trim().length === 0) {
+      throw new TypeError('addDictionaryEntry: entry must be a non-empty string.');
+    }
+
+    let data = {
+      entry,
+      key: this.apiKey,
+    }
+
+    if (options?.case_sensitive !== undefined) {
+      if (typeof options.case_sensitive !== 'boolean') {
+        throw new TypeError('addDictionaryEntry: case_sensitive must be a boolean.');
+      }
+      data.case_sensitive = options.case_sensitive;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Delete a custom dictionary entry by the `id` dictionaryEntries() or
+   * addDictionaryEntry() returned. Answers 204 with no body; an id that is
+   * malformed or not this account's gets a 400 (not a 404).
+   *
+   * @param {string} entryId - The entry's id (a UUID).
+   * @returns {Promise<AxiosResponse>}
+   */
+  deleteDictionaryEntry(entryId) {
+    if (typeof entryId !== 'string' || entryId.trim().length === 0) {
+      throw new TypeError('deleteDictionaryEntry: entryId must be a non-empty string.');
+    }
+    const url = `${this.urlEndpoint}dictionary/${encodeURIComponent(entryId)}`;
+    // The key rides the query string, like deleteStyleguideRuleset(): some
+    // HTTP stacks drop DELETE bodies.
+    return axios({
+      url,
+      method: 'delete',
+      params: { key: this.apiKey },
+      timeout: this.timeout,
+    });
+  }
+
   /**
    * Structured data extraction: pull caller-named fields out of unstructured text.
    *
@@ -195,8 +550,11 @@ export class Client {
    * 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} text - The document to extract from, plain text or HTML (the API caps
-   *   it at 10,000 characters).
+   * @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'.
@@ -215,7 +573,20 @@ export class Client {
     // 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).
-    if (typeof text !== 'string' || text.trim().length === 0) {
+    // 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.');
     }
 
@@ -268,7 +639,7 @@ export class Client {
     }
 
     let data = {
-      text,
+      ...(isBatch ? { texts: text } : { text }),
       fields,
       key: this.apiKey,
     }
@@ -286,11 +657,182 @@ export class Client {
     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,
     }
 
@@ -314,7 +856,11 @@ export class Client {
    * empty), `scores` (one `{label, score}` per input label, descending), a one-sentence
    * `rationale` and the echoed `multi_label` mode.
    *
-   * @param {string} text - Text to classify, plain text or HTML (the API caps it at 10,000 chars).
+   * @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]
@@ -333,7 +879,20 @@ export class Client {
     // 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).
-    if (typeof text !== 'string' || text.trim().length === 0) {
+    // 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.');
     }
 
@@ -379,7 +938,7 @@ export class Client {
     }
 
     let data = {
-      text,
+      ...(isBatch ? { texts: text } : { text }),
       labels,
       key: this.apiKey,
     }
@@ -477,12 +1036,30 @@ export class Client {
     const url = `${this.urlEndpoint}quality`;
 
     // Shape/type checks only; size limits are server configuration (see seo()).
-    if (typeof text !== 'string' || text.trim().length === 0) {
+    // 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 = {
-      text,
+      ...(isBatch ? { texts: text } : { text }),
       key: this.apiKey,
     }
 
@@ -508,12 +1085,30 @@ export class Client {
     const url = `${this.urlEndpoint}safety`;
 
     // Shape/type checks only; size limits are server configuration (see seo()).
-    if (typeof text !== 'string' || text.trim().length === 0) {
+    // 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 = {
-      text,
+      ...(isBatch ? { texts: text } : { text }),
       key: this.apiKey,
     }
 
@@ -526,6 +1121,12 @@ export class Client {
       }
       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);
   }
@@ -533,14 +1134,307 @@ export class Client {
   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,
     }
 
     if (options.sent_scores != null) {
       data.sent_scores = options.sent_scores;
     }
+    if (options.score_string !== undefined) {
+      if (typeof options.score_string !== 'boolean') {
+        throw new TypeError('aidetect: score_string must be a boolean.');
+      }
+      data.score_string = options.score_string;
+    }
+    if (options.version !== undefined) {
+      if (typeof options.version !== 'string') {
+        throw new TypeError('aidetect: version must be a string.');
+      }
+      data.version = options.version;
+    }
+
+    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);
   }
@@ -577,4 +1471,106 @@ export class Client {
 
     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,
+    });
+  }
 }