@saplingai/sapling-js 1.0.52 → 1.0.53

package/README.md

@@ -102,6 +102,79 @@ client
   })
 ```
 
+### AI content detection
+
+```javascript
+const { data } = await client.aidetect(documentText);
+// { score: 0.05, ai_fraction: 0.51, text: '...', version: '...',
+//   sentence_scores: [{ sentence: '...', score: 0.97, start: 0, end: 112 }, ...],
+//   tokens: [...], token_probs: [...] }
+```
+
+`score` (0–1) rates the whole text, so a document that is only partly AI-written can score low;
+`ai_fraction` is the share of the text in sentences scoring ≥ 0.5 (null when nothing could be
+scored), which flags those documents. `sentence_scores` use the same model and 0.5 threshold, and
+`start`/`end` index `text` in Unicode code points (`end` exclusive) — slice with
+`Array.from(text).slice(start, end).join('')` if the text may contain emoji. A response may also
+carry an advisory `language` (`{ code, name, confidence }`) when the text is confidently
+identified; the detector is trained on English. Options: `sent_scores` (default true),
+`score_string` (HTML heatmap), `version` (pin a model). Pass an array of 1–10 texts for the batch
+form, which answers `{ results: [...] }` in input order.
+
+### Rephrase, sentiment and readability statistics
+
+```javascript
+const { data: rephrased } = await client.rephrase('hey, can u send it over', {
+  mapping: 'informal_to_formal', // default 'paraphrase'
+  num_results: 3,                // 1–8, default 5
+});
+// { results: [{ hash: '...', original: '...', replacement: 'Could you please send it over?',
+//               rephrase_type: 'informal_to_formal', model_version: '...' }, ...] }
+
+const { data: sentiment } = await client.sentiment('Love the new release. The install was painful.');
+// { overall: [[0.71, 'POSITIVE'], [0.29, 'NEGATIVE']],
+//   results: [[[0.99, 'POSITIVE']], [[0.95, 'NEGATIVE'], ...]],
+//   sents: ['Love the new release.', 'The install was painful.'] }
+
+const { data: stats } = await client.statistics(documentText, { lang: 'en' });
+// { chars: 1234, words: 210, sentences: 12, reading_time_sec: 47.55, reading_time_min: 1,
+//   readability: 8.2, readability_scores: { flesch_reading_ease: 64.1, gunning_fog: 10.3, ... } }
+```
+
+`rephrase()` mappings: `paraphrase`, `reword`, `expand`, `shorten`, `summarize`,
+`passive_to_active`, `active_to_passive`, `informal_to_formal`, `formal_to_informal`,
+`sentence_split`, `generate_title`, `generate_acronym`, `generate_meta_description`,
+`switch_tone` (with `tone_mapping`) and `switch_tense` (with `tense_mapping`). Sentiment labels
+are `POSITIVE`, `NEUTRAL` and `NEGATIVE`, as `[probability, label]` pairs, most likely first;
+a text with no sentences (markup or punctuation only) gets a 204 with an empty body (`data === ''`),
+and one the API cannot split into sentences gets a 200 with `[]`.
+`statistics()` is unbilled; `lang` is one of `en`, `de`, `es`, `fr`, `it`, `nl`, `pl`, `ru`, `ar`
+or `auto` and picks the readability formulas (`readability_scores` is empty for `auto`).
+
+### Similar terms, profanity and the custom dictionary
+
+```javascript
+const { data: similar } = await client.similarTerms('pet');
+// { neighbors: [[0.81, 'dog'], [0.78, 'cat'], [0.75, 'puppy']],
+//   synonyms: ['darling', 'favorite', 'favourite', ...] }
+
+const { data: profanity } = await client.profanity('This is so damn stupid.');
+// { toks: ['This', 'is', 'so', 'damn', 'stupid.'], labels: [0, 0, 0, 1, 1] }
+
+// Words the grammar and spelling checks should accept (product names, jargon).
+const { data: entry } = await client.addDictionaryEntry('Sapling', { case_sensitive: true });
+// { id: '...', entry: 'Sapling', case_sensitive: true, created_at: '...', updated_at: '...' }
+const { data: entries } = await client.dictionaryEntries(); // a bare array, sorted by entry
+await client.deleteDictionaryEntry(entry.id);               // 204, empty body
+```
+
+`similarTerms()` returns up to five `[similarity, term]` neighbors (similarity 0–1, most similar
+first) plus WordNet `synonyms` (multi-word ones use underscores); only the first 100 characters of
+the query are used. `profanity()` splits the text on whitespace and labels each token 1 (profane)
+or 0. Both are unbilled. `addDictionaryEntry()` answers 400 for a duplicate entry or one with more
+than two digits; `deleteDictionaryEntry()` answers 400 (not 404) for an id that is not this
+account's.
+
 ### Style-guide rulesets
 
 Check text against style rules inline, or save a named ruleset once (owned by

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saplingai/sapling-js",
-  "version": "1.0.52",
+  "version": "1.0.53",
   "description": "JavaScript library for using the Sapling.ai API.",
   "type": "module",
   "main": "./sapling/client.js",

package/sapling/client.d.ts

@@ -38,7 +38,54 @@ export type EditOptions = {
 }
 
 export type AIDetectOptions = {
+   /** Include `sentence_scores` (server default true). */
    sent_scores?: boolean,
+   /** Include `score_string`, an HTML heatmap of the scored text. */
+   score_string?: boolean,
+   /** Pin a detector model version (e.g. `'20251027'`); omitted = current default. */
+   version?: string,
+}
+
+export type AIDetectSentenceScore = {
+   sentence: string;
+   /** Same model, 0–1 scale and 0.5 threshold as the overall `score`. */
+   score: number;
+   /** Offsets into the response `text` (`end` exclusive), counted in Unicode
+    *  code points — slice with `Array.from(text)` if it may contain emoji. */
+   start: number;
+   end: number;
+}
+
+export type AIDetectLanguage = {
+   code: string;
+   /** English display name; null for codes without one. */
+   name: string | null;
+   confidence: number;
+}
+
+export type AIDetectResponse = {
+   /** 0 (likely human-written) to 1 (likely AI-generated). */
+   score: number;
+   /** Share of the text in sentences scoring >= 0.5 (flags partially
+    *  AI-written documents); null when nothing could be scored. */
+   ai_fraction: number | null;
+   text: string;
+   tokens: string[];
+   token_probs: number[];
+   /** The pinned `version` when one was requested, otherwise an opaque
+    *  identifier of the default model — log it, don't parse it. */
+   version: string;
+   /** Present unless `sent_scores: false`. */
+   sentence_scores?: AIDetectSentenceScore[];
+   /** Present when `score_string: true`. */
+   score_string?: string;
+   /** Advisory detected language; omitted unless detection is high-confidence.
+    *  The detector is trained on English. */
+   language?: AIDetectLanguage;
+}
+
+export type AIDetectBatchResponse = {
+   results: AIDetectResponse[];
 }
 
 export type StyleguideRule = string | { name: string; description?: string };
@@ -274,7 +321,12 @@ export type QualityBatchResponse = {
    results: QualityResponse[];
 }
 
-export type PIIType = 'email' | 'phone' | 'ssn' | 'credit_card' | 'ip_address' | 'iban' | 'us_bank_routing';
+export type PIIDeterministicType = 'email' | 'phone' | 'ssn' | 'credit_card' | 'ip_address' | 'iban' | 'us_bank_routing';
+// Opt-in, LLM-backed named-entity PII types: detected only when listed in
+// `types` explicitly (a request without them stays deterministic-only), and
+// the text is then capped at 10,000 characters rather than 20,000.
+export type PIINerType = 'person' | 'organization' | 'location';
+export type PIIType = PIIDeterministicType | PIINerType;
 
 export type PIIOptions = {
    types?: PIIType[],
@@ -422,6 +474,105 @@ export type SummarizeBatchResponse = {
    results: SummarizeResponse[];
 }
 
+export type RephraseMapping =
+   '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';
+
+export type RephraseToneMapping =
+   'straightforward' | 'confident' | 'friendly' | 'empathetic' | 'professional' | 'casual' |
+   'diplomatic' | 'persuasive';
+
+export type RephraseTenseMapping =
+   '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';
+
+export type RephraseOptions = {
+   /** Defaults to 'paraphrase'. */
+   mapping?: RephraseMapping,
+   /** Only used with mapping 'switch_tone'. Defaults to 'straightforward'. */
+   tone_mapping?: RephraseToneMapping,
+   /** Only used with mapping 'switch_tense'. Defaults to 'simple past'. */
+   tense_mapping?: RephraseTenseMapping,
+   /** Number of alternatives, 1-8 (default 5). Honored by paraphrase, informal_to_formal,
+    *  formal_to_informal, generate_title and generate_acronym. */
+   num_results?: number,
+   session_id?: string,
+}
+
+export type RephraseResult = {
+   hash: string,
+   original: string,
+   replacement: string,
+   rephrase_type: RephraseMapping,
+   model_version: string,
+}
+
+export type RephraseResponse = {
+   results: RephraseResult[],
+}
+
+export type SentimentLabel = 'POSITIVE' | 'NEUTRAL' | 'NEGATIVE';
+
+/** [probability, label] pairs, most likely first. */
+export type SentimentScores = Array<[number, SentimentLabel]>;
+
+export type SentimentResponse = {
+   overall: SentimentScores,
+   /** One entry per sentence, aligned with `sents`. */
+   results: SentimentScores[],
+   sents: string[],
+}
+
+export type StatisticsLang = 'en' | 'de' | 'es' | 'fr' | 'it' | 'nl' | 'pl' | 'ru' | 'ar' | 'auto';
+
+export type StatisticsOptions = {
+   /** Defaults to 'en'. */
+   lang?: StatisticsLang,
+}
+
+export type StatisticsResponse = {
+   chars: number,
+   words: number,
+   sentences: number,
+   reading_time_sec: number,
+   reading_time_min: number,
+   /** Flesch-Kincaid grade level; -3.4 when the text cannot be scored. */
+   readability: number,
+   /** Formula name -> score. The formulas present depend on `lang`; empty for 'auto'.
+    *  `text_standard` is a string (e.g. "8th and 9th grade"). */
+   readability_scores: Record<string, number | string>,
+}
+
+export type SimilarTermsResponse = {
+   /** Up to 5 [similarity, term] pairs (similarity 0-1), most similar first. */
+   neighbors: Array<[number, string]>,
+   /** WordNet lemma names; multi-word ones use underscores (e.g. "domestic_dog"). */
+   synonyms: string[],
+}
+
+export type ProfanityResponse = {
+   /** The text split on whitespace (punctuation stays attached). */
+   toks: string[],
+   /** Aligned with `toks`: 1 for profanity, 0 otherwise. */
+   labels: Array<0 | 1>,
+}
+
+export type DictionaryEntry = {
+   id: string,
+   entry: string,
+   case_sensitive: boolean,
+   /** RFC 1123 timestamp, e.g. "Wed, 07 Oct 2020 21:15:47 GMT". */
+   created_at: string,
+   updated_at: string,
+}
+
+export type AddDictionaryEntryOptions = {
+   /** Defaults to true. */
+   case_sensitive?: boolean,
+}
+
 export type UserDetails = {
    userId?: string,
    anonUser?: boolean,
@@ -439,6 +590,18 @@ export declare class Client {
    complete(query: string, sessionId?: string): Promise<AxiosResponse>;
    acceptComplete(completeUUID: string, query: string, completion: string, sessionId?: string): Promise<AxiosResponse>;
    tone(text: string): Promise<AxiosResponse>;
+   rephrase(text: string, options?: RephraseOptions): Promise<AxiosResponse<RephraseResponse>>;
+   /** A text with no sentences (e.g. markup or punctuation only) gets a 204 with an empty
+    *  body, so `data` is `''` then; a text the API cannot split into sentences gets a 200
+    *  with `[]`. Check `Array.isArray(data) || !data` before reading fields. */
+   sentiment(text: string): Promise<AxiosResponse<SentimentResponse | '' | never[]>>;
+   statistics(text: string, options?: StatisticsOptions): Promise<AxiosResponse<StatisticsResponse>>;
+   similarTerms(query: string): Promise<AxiosResponse<SimilarTermsResponse>>;
+   profanity(text: string): Promise<AxiosResponse<ProfanityResponse>>;
+   dictionaryEntries(): Promise<AxiosResponse<DictionaryEntry[]>>;
+   addDictionaryEntry(entry: string, options?: AddDictionaryEntryOptions): Promise<AxiosResponse<DictionaryEntry>>;
+   /** Answers 204 with an empty body. */
+   deleteDictionaryEntry(entryId: string): Promise<AxiosResponse<''>>;
    extract(text: string, fields: ExtractField[], options?: ExtractOptions): Promise<AxiosResponse<ExtractResponse>>;
    extract(texts: string[], fields: ExtractField[], options?: ExtractOptions): Promise<AxiosResponse<ExtractBatchResponse>>;
    extract(text: string | string[], fields: ExtractField[], options?: ExtractOptions): Promise<AxiosResponse<ExtractResponse | ExtractBatchResponse>>;
@@ -449,7 +612,9 @@ export declare class Client {
    summarize(texts: string[], options?: SummarizeOptions): Promise<AxiosResponse<SummarizeBatchResponse>>;
    summarize(text: string | string[], options?: SummarizeOptions): Promise<AxiosResponse<SummarizeResponse | SummarizeBatchResponse>>;
 
-   aidetect(text: string | string[], options?: AIDetectOptions): Promise<AxiosResponse>;
+   aidetect(text: string, options?: AIDetectOptions): Promise<AxiosResponse<AIDetectResponse>>;
+   aidetect(texts: string[], options?: AIDetectOptions): Promise<AxiosResponse<AIDetectBatchResponse>>;
+   aidetect(text: string | string[], options?: AIDetectOptions): Promise<AxiosResponse<AIDetectResponse | AIDetectBatchResponse>>;
    styleguide(text: string, rules: StyleguideRule[] | string): Promise<AxiosResponse<StyleguideResponse>>;
    styleguide(texts: string[], rules: StyleguideRule[] | string): Promise<AxiosResponse<StyleguideBatchResponse>>;
    styleguide(text: string | string[], rules: StyleguideRule[] | string): Promise<AxiosResponse<StyleguideResponse | StyleguideBatchResponse>>;

package/sapling/client.js

@@ -8,6 +8,24 @@ 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
@@ -237,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.
    *
@@ -866,6 +1164,18 @@ export class Client {
     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);
   }