@saplingai/sapling-js 1.0.53 → 1.0.55

package/sapling/client.js

@@ -26,6 +26,41 @@ const REPHRASE_TENSE_MAPPINGS = [
 ];
 // Languages statistics() scores readability for (plus 'auto').
 const STATISTICS_LANGS = ['en', 'de', 'es', 'fr', 'it', 'nl', 'pl', 'ru', 'ar'];
+// Buckets apiEndpointUsage() accepts (request_validator.INTERVAL_VALS).
+const REPORTING_INTERVALS = ['Daily', 'Weekly', 'Monthly'];
+
+// Shared by the reporting methods: the request body with the window offsets,
+// which the API documents as non-negative integers (days before today).
+// Omitted offsets are left out so each endpoint applies its own default.
+const reportingWindowBody = (apiKey, options, method) => {
+  const data = { key: apiKey };
+  for (const field of ['start_days_back', 'end_days_back']) {
+    if (options?.[field] !== undefined) {
+      if (!Number.isInteger(options[field]) || options[field] < 0) {
+        throw new TypeError(`${method}: ${field} must be a non-negative integer.`);
+      }
+      data[field] = options[field];
+    }
+  }
+  return data;
+};
+
+// Shared by chunkText() and chunkHtml(). The API reads both numbers with an
+// integer type check (a numeric string like "25" is a 400), and max_length is
+// required in practice: its default of 0 fails the positive-integer check.
+const chunkBody = (apiKey, maxLength, options, method) => {
+  if (!Number.isInteger(maxLength) || maxLength < 1) {
+    throw new TypeError(`${method}: maxLength must be a positive integer.`);
+  }
+  const data = { key: apiKey, max_length: maxLength };
+  if (options?.step_size !== undefined) {
+    if (!Number.isInteger(options.step_size) || options.step_size < 0) {
+      throw new TypeError(`${method}: step_size must be a non-negative integer.`);
+    }
+    data.step_size = options.step_size;
+  }
+  return data;
+};
 
 // Shared by styleguide() and saveStyleguideRuleset(). Shape/type checks only —
 // size limits (rule/description length) are server configuration and enforced
@@ -74,18 +109,138 @@ const validateStyleguideRules = (rules, method) => {
   }
 };
 
+// Shared by extract() and fileExtract(). Shape/type checks only — size limits
+// (field name/description length) are server configuration and enforced there
+// with a clear 400.
+const validateExtractFields = (fields, method) => {
+  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(`${method}: 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(`${method}: field names must be unique (case-insensitive).`);
+  }
+};
+
+// Multipart body for the document-upload endpoints (/api/v1/file-aidetect,
+// /api/v1/file-extract, /api/v1/file-summarize): the document in a `file` part and the options as a
+// `jsonParams` form field. `file` is a Blob/File (browser, or Node 18+), or a
+// Buffer/Uint8Array/ArrayBuffer read from disk. The API picks the format by
+// file extension, so a name is required: a File's own name, or
+// `options.filename`. Which extensions are accepted is server configuration
+// (a clear 400 lists them), so it is not mirrored here.
+const buildUploadForm = (file, filename, jsonParams, method) => {
+  // Global FormData/Blob arrived in Node 18; fail with a clear message rather
+  // than a ReferenceError on older runtimes without a polyfill.
+  if (typeof FormData === 'undefined' || typeof Blob === 'undefined') {
+    throw new Error(`${method}: document upload needs global FormData and Blob `
+      + '(Node 18+ or a browser).');
+  }
+  let blob;
+  if (file instanceof Blob) {
+    blob = file;
+  } else if (file instanceof ArrayBuffer || ArrayBuffer.isView(file)) {
+    blob = new Blob([file]);
+  } else {
+    throw new TypeError(`${method}: file must be a Blob, File, Buffer, Uint8Array or ArrayBuffer.`);
+  }
+  const name = filename !== undefined ? filename : file.name;
+  if (typeof name !== 'string' || name.trim().length === 0) {
+    throw new TypeError(`${method}: a filename is required (pass options.filename, e.g. `
+      + "'report.pdf'); the API chooses the document format by its extension.");
+  }
+  const form = new FormData();
+  form.append('file', blob, name);
+  form.append('jsonParams', JSON.stringify(jsonParams));
+  return form;
+};
+
+// Shared by pdfToText() and docxToText(): the key (and the client-level
+// return_usage flag, which axiosPromise only injects into plain-object bodies)
+// ride the jsonParams part.
+const fileToTextForm = (client, file, options, method) => {
+  const params = { key: client.apiKey };
+  if (client.returnUsage) {
+    params.return_usage = true;
+  }
+  return buildUploadForm(file, options?.filename, params, method);
+};
+
 export class Client {
   constructor(apiKey, options = {}) {
     this.apiKey = apiKey;
     this.timeout = options.timeout || 120000;
-    this.hostname = options.hostname || 'https://api.sapling.ai';
-    this.pathname = options.pathname || '/api/v1/';
+    this.hostname = (options.hostname || 'https://api.sapling.ai').replace(/\/+$/, '');
+    const path = (options.pathname || '/api/v1/').replace(/^\/+|\/+$/g, '');
+    this.pathname = path ? `/${path}/` : '/';
     this.urlEndpoint = `${this.hostname}${this.pathname}`;
     this.defaultSessionId = uuidv4();
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a
+    // bad type rather than silently treated as "omitted", matching the
+    // per-method option handling.
+    if (options.returnUsage !== undefined) {
+      if (typeof options.returnUsage !== 'boolean') {
+        throw new TypeError('Client: returnUsage must be a boolean.');
+      }
+      this.returnUsage = options.returnUsage;
+    } else {
+      this.returnUsage = false;
+    }
     axios.defaults.timeout = this.timeout;
   }
 
   axiosPromise(url, method, data) {
+    // Client-wide opt-in usage reporting: `return_usage` is accepted by every
+    // API-key endpoint (attached centrally server-side), so it is injected
+    // centrally here rather than wired into each method. Only `true` is sent —
+    // false is the server default and is omitted, and a `return_usage` a
+    // future method sets itself wins over the client-level flag. The
+    // `[object Object]` guard restricts the shallow copy to plain objects so a
+    // future non-plain body (Buffer, FormData, URLSearchParams, ...) is left
+    // untouched rather than spread into a stripped-down copy.
+    if (this.returnUsage && Object.prototype.toString.call(data) === '[object Object]' && !('return_usage' in data)) {
+      data = { ...data, return_usage: true };
+    }
     return new Promise((resolve, reject) => {
       axios({
         url,
@@ -204,8 +359,10 @@ export class Client {
       data.variety = options.variety;
     }
 
+    // The API reads this option as camelCase `userData` (and echoes it back
+    // as `user_data`); a snake_case key is silently ignored.
     if (options.userData != null) {
-      data.user_data = options.userData;
+      data.userData = options.userData;
     }
 
     if (userDetails) {
@@ -218,6 +375,18 @@ export class Client {
   }
 
 
+  /**
+   * Autocomplete: predict how a partially written sentence continues.
+   *
+   * Returns `output` (the continuation), `query` (the part of the sent query
+   * it continues: only the text after the last run of three spaces) and
+   * `hash`. A 200 with `[]` means no completion is available. The query is
+   * capped at 200 characters, and the API key needs autocomplete enabled.
+   *
+   * @param {string} query - The end of what the user has typed.
+   * @param {string} [sessionId] - Defaults to the client's session id.
+   * @returns {Promise<AxiosResponse>}
+   */
   complete(query, sessionId) {
     const url = `${this.urlEndpoint}complete`;
     sessionId = sessionId || this.defaultSessionId;
@@ -230,6 +399,18 @@ export class Client {
   }
 
 
+  /**
+   * Record that the user accepted a completion from complete().
+   *
+   * Pass the `hash`, `query` and `output` that complete() returned, unchanged:
+   * the API recomputes the hash and answers 400 when they don't match.
+   *
+   * @param {string} completeUUID - The `hash` from complete().
+   * @param {string} query - The `query` from complete().
+   * @param {string} completion - The `output` from complete().
+   * @param {string} [sessionId] - Defaults to the client's session id.
+   * @returns {Promise<AxiosResponse>}
+   */
   acceptComplete(completeUUID, query, completion, sessionId) {
     const url = `${this.urlEndpoint}complete/${completeUUID}/accept`;
     sessionId = sessionId || this.defaultSessionId;
@@ -245,6 +426,17 @@ export class Client {
     return this.axiosPromise(url, 'post', data);
   }
 
+  /**
+   * Tone classification: overall and per-sentence emotional tone.
+   *
+   * Returns `overall` (up to 3 [probability, tone name, emoji] triples, most
+   * likely first, probabilities summing to 1), `results` (one list of triples
+   * per sentence) and `sents` (the sentences). A text the API cannot split
+   * into sentences gets a 200 with `[]`.
+   *
+   * @param {string} text - The text to analyze, at most 8000 characters.
+   * @returns {Promise<AxiosResponse>}
+   */
   tone(text) {
     const url = `${this.urlEndpoint}tone`;
 
@@ -466,7 +658,9 @@ export class Client {
   dictionaryEntries() {
     const url = `${this.urlEndpoint}dictionary`;
     // Not axiosPromise: this is a GET and the key rides the query string,
-    // like styleguideRulesets().
+    // like styleguideRulesets(). The client-level return_usage opt-in is
+    // deliberately not forwarded: the response is a bare JSON array, which
+    // the API cannot attach `usage` to.
     return axios({
       url,
       method: 'get',
@@ -526,7 +720,217 @@ export class Client {
     }
     const url = `${this.urlEndpoint}dictionary/${encodeURIComponent(entryId)}`;
     // The key rides the query string, like deleteStyleguideRuleset(): some
-    // HTTP stacks drop DELETE bodies.
+    // HTTP stacks drop DELETE bodies. return_usage is deliberately not
+    // forwarded: the 204 has no body to attach `usage` to.
+    return axios({
+      url,
+      method: 'delete',
+      params: { key: this.apiKey },
+      timeout: this.timeout,
+    });
+  }
+
+  /**
+   * List the custom mappings of this API key's account: rules that make the
+   * grammar check suggest a fixed replacement wherever `entry` matches
+   * (brand names, preferred terms, banned phrasings).
+   *
+   * Returns `custom_mappings`: `{id, entry, mapping, description,
+   * case_sensitive, created_at, updated_at}` entries sorted by entry
+   * (timestamps are RFC 1123 strings).
+   *
+   * @returns {Promise<AxiosResponse>}
+   */
+  customMappings() {
+    const url = `${this.urlEndpoint}custom_mapping`;
+    // Not axiosPromise (that injects into the POST body): this is a GET, so
+    // the key and the client-level return_usage opt-in ride the query
+    // string, like styleguideRulesets(). The response is a JSON object, so
+    // the API can attach `usage` to it.
+    const params = { key: this.apiKey };
+    if (this.returnUsage) {
+      params.return_usage = true;
+    }
+    return axios({
+      url,
+      method: 'get',
+      params,
+      timeout: this.timeout,
+    });
+  }
+
+  /**
+   * Add a custom mapping to this API key's account: wherever `entry`
+   * matches, the grammar check suggests `mapping` instead.
+   *
+   * `entry` supports two pattern forms: `^` / `$` anchor a match to the
+   * start / end of a sentence (e.g. `^the` to enforce capitalization), and
+   * `#` matches a number (e.g. `Gate #`); a `#` in `mapping` substitutes the
+   * matched number back in.
+   *
+   * Returns the created `{id, entry, mapping, description, case_sensitive,
+   * created_at, updated_at}` entry. The API answers 400 for a duplicate
+   * entry ("Entry already exists."), an entry equal to its mapping, an entry
+   * with more than two digits, and a case-insensitive rule whose entry and
+   * mapping differ only in case (e.g. iphone -> iPhone; mark it case
+   * sensitive).
+   *
+   * @param {string} entry - The text to match (surrounding whitespace is
+   *   stripped server-side).
+   * @param {string} mapping - The replacement to suggest.
+   * @param {Object} [options]
+   * @param {string} [options.description] - Shown to the end user with the
+   *   suggestion. A mapping with a description cannot be ignored.
+   * @param {boolean} [options.case_sensitive] - Whether matching is case
+   *   sensitive. Defaults to true; when false, lower and title case both
+   *   match.
+   * @returns {Promise<AxiosResponse>}
+   */
+  addCustomMapping(entry, mapping, options = {}) {
+    const url = `${this.urlEndpoint}custom_mapping`;
+
+    if (typeof entry !== 'string' || entry.trim().length === 0) {
+      throw new TypeError('addCustomMapping: entry must be a non-empty string.');
+    }
+    if (typeof mapping !== 'string') {
+      throw new TypeError('addCustomMapping: mapping must be a string.');
+    }
+
+    let data = {
+      entry,
+      mapping,
+      key: this.apiKey,
+    }
+
+    if (options?.description !== undefined) {
+      if (typeof options.description !== 'string') {
+        throw new TypeError('addCustomMapping: description must be a string.');
+      }
+      data.description = options.description;
+    }
+    if (options?.case_sensitive !== undefined) {
+      if (typeof options.case_sensitive !== 'boolean') {
+        throw new TypeError('addCustomMapping: case_sensitive must be a boolean.');
+      }
+      data.case_sensitive = options.case_sensitive;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Delete a custom mapping by the `id` customMappings() or
+   * addCustomMapping() returned. Answers 204 with no body; an id that is not
+   * this account's gets a 400 (not a 404).
+   *
+   * @param {string} mappingId - The mapping's id (a UUID).
+   * @returns {Promise<AxiosResponse>}
+   */
+  deleteCustomMapping(mappingId) {
+    if (typeof mappingId !== 'string' || mappingId.trim().length === 0) {
+      throw new TypeError('deleteCustomMapping: mappingId must be a non-empty string.');
+    }
+    const url = `${this.urlEndpoint}custom_mapping/${encodeURIComponent(mappingId)}`;
+    // Key in the query string, like deleteDictionaryEntry(): some HTTP
+    // stacks drop DELETE bodies, and the 204 has no body to attach `usage`
+    // to, so return_usage is not forwarded.
+    return axios({
+      url,
+      method: 'delete',
+      params: { key: this.apiKey },
+      timeout: this.timeout,
+    });
+  }
+
+  /**
+   * List the custom filters of this API key's account: rules that suppress
+   * grammar-check suggestions rewriting `input` to `output`.
+   *
+   * Returns `custom_filters`: `{id, input, output, case_sensitive,
+   * created_at, updated_at}` entries sorted by input. An empty `input` or
+   * `output` is a wildcard.
+   *
+   * @returns {Promise<AxiosResponse>}
+   */
+  customFilters() {
+    const url = `${this.urlEndpoint}custom_filter`;
+    // GET: key and return_usage ride the query string, like customMappings().
+    const params = { key: this.apiKey };
+    if (this.returnUsage) {
+      params.return_usage = true;
+    }
+    return axios({
+      url,
+      method: 'get',
+      params,
+      timeout: this.timeout,
+    });
+  }
+
+  /**
+   * Add a custom filter to this API key's account, so the grammar check
+   * stops suggesting edits that rewrite `input` to `output`. Pass an empty
+   * string for either side as a wildcard: `('Patient', '')` suppresses every
+   * edit of "Patient"; `('', 'The patient')` every edit that produces "The
+   * patient".
+   *
+   * Returns the created `{id, input, output, case_sensitive, created_at,
+   * updated_at}` filter. The API answers 400 when both sides are blank
+   * after trimming, when they are equal, for a duplicate filter ("Filter
+   * already exists."), an input with more than two digits, and a
+   * case-insensitive filter whose sides differ only in case.
+   *
+   * @param {string} input - The original text of the edits to suppress, or
+   *   '' for any (surrounding whitespace is stripped server-side).
+   * @param {string} output - The replacement text of the edits to suppress,
+   *   or '' for any.
+   * @param {Object} [options]
+   * @param {boolean} [options.case_sensitive] - Whether matching is case
+   *   sensitive. Defaults to true.
+   * @returns {Promise<AxiosResponse>}
+   */
+  addCustomFilter(input, output, options = {}) {
+    const url = `${this.urlEndpoint}custom_filter`;
+
+    if (typeof input !== 'string' || typeof output !== 'string') {
+      throw new TypeError('addCustomFilter: input and output must be strings.');
+    }
+    if (input.trim().length === 0 && output.trim().length === 0) {
+      throw new TypeError('addCustomFilter: input and output cannot both be blank.');
+    }
+
+    // The API's field names are `inp` / `out`; the response says
+    // `input` / `output`.
+    let data = {
+      inp: input,
+      out: output,
+      key: this.apiKey,
+    }
+
+    if (options?.case_sensitive !== undefined) {
+      if (typeof options.case_sensitive !== 'boolean') {
+        throw new TypeError('addCustomFilter: case_sensitive must be a boolean.');
+      }
+      data.case_sensitive = options.case_sensitive;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Delete a custom filter by the `id` customFilters() or addCustomFilter()
+   * returned. Answers 204 with no body; an id that is malformed or not this
+   * account's gets a 400 (not a 404).
+   *
+   * @param {string} filterId - The filter's id (a UUID).
+   * @returns {Promise<AxiosResponse>}
+   */
+  deleteCustomFilter(filterId) {
+    if (typeof filterId !== 'string' || filterId.trim().length === 0) {
+      throw new TypeError('deleteCustomFilter: filterId must be a non-empty string.');
+    }
+    const url = `${this.urlEndpoint}custom_filter/${encodeURIComponent(filterId)}`;
+    // Key in the query string and no return_usage, like deleteCustomMapping().
     return axios({
       url,
       method: 'delete',
@@ -590,53 +994,7 @@ export class Client {
       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).');
-    }
+    validateExtractFields(fields, 'extract');
 
     let data = {
       ...(isBatch ? { texts: text } : { text }),
@@ -657,6 +1015,48 @@ export class Client {
     return this.axiosPromise(url, 'post', data);
   }
 
+  /**
+   * Extract caller-named fields from an uploaded document
+   * (POST /api/v1/file-extract): the same extraction as extract(), with the text
+   * read server-side from a .pdf, .docx, .pptx, .odt, .txt, .md, .html or .htm
+   * file of up to 30MB.
+   *
+   * Only the first 10,000 characters of the document's text are read; the
+   * response's `document` block (`file_type`, `characters`, `characters_used`,
+   * `truncated`) says how much was used, and `characters_used` is what is billed.
+   *
+   * @param {Blob|File|Buffer|Uint8Array|ArrayBuffer} file - The document.
+   * @param {Array<string|object>} fields - Same as extract().
+   * @param {object} [options]
+   * @param {string} [options.filename] - Required unless `file` is a File: the
+   *   format is chosen by its extension (e.g. 'invoice.pdf').
+   * @param {string} [options.context] - Same as extract().
+   */
+  fileExtract(file, fields, options = {}) {
+    const url = `${this.urlEndpoint}file-extract`;
+
+    validateExtractFields(fields, 'fileExtract');
+
+    let params = {
+      key: this.apiKey,
+      fields,
+    };
+    if (options?.context !== undefined) {
+      if (typeof options.context !== 'string') {
+        throw new TypeError('fileExtract: context must be a string.');
+      }
+      params.context = options.context;
+    }
+    // axiosPromise only injects return_usage into plain-object bodies, so the
+    // client-level flag rides the jsonParams part here.
+    if (this.returnUsage) {
+      params.return_usage = true;
+    }
+
+    const form = buildUploadForm(file, options?.filename, params, 'fileExtract');
+    return this.axiosPromise(url, 'post', form);
+  }
+
   /**
    * Translate text into a target language with an LLM.
    *
@@ -806,6 +1206,44 @@ export class Client {
     return this.axiosPromise(url, 'post', data);
   }
 
+  /**
+   * Summarize an uploaded document (POST /api/v1/file-summarize): the same
+   * summary as summarize(), with the text read server-side from a .pdf, .docx,
+   * .pptx, .odt, .txt, .md, .html or .htm file of up to 30MB.
+   *
+   * Only the first 20,000 characters of the document's text are read; the
+   * response's `document` block (`file_type`, `characters`, `characters_used`,
+   * `truncated`) says how much was used, and `characters_used` is what is billed.
+   *
+   * @param {Blob|File|Buffer|Uint8Array|ArrayBuffer} file - The document.
+   * @param {object} [options]
+   * @param {string} [options.filename] - Required unless `file` is a File: the
+   *   format is chosen by its extension (e.g. 'report.pdf').
+   * @param {string} [options.length] - Same as summarize().
+   */
+  fileSummarize(file, options = {}) {
+    const url = `${this.urlEndpoint}file-summarize`;
+
+    let params = {
+      key: this.apiKey,
+    };
+    if (options?.length !== undefined) {
+      if (!SUMMARIZE_LENGTHS.includes(options.length)) {
+        throw new TypeError('fileSummarize: length must be one of '
+          + `${SUMMARIZE_LENGTHS.join(', ')}.`);
+      }
+      params.length = options.length;
+    }
+    // axiosPromise only injects return_usage into plain-object bodies, so the
+    // client-level flag rides the jsonParams part here.
+    if (this.returnUsage) {
+      params.return_usage = true;
+    }
+
+    const form = buildUploadForm(file, options?.filename, params, 'fileSummarize');
+    return this.axiosPromise(url, 'post', form);
+  }
+
   langdetect(text, options = {}) {
     const url = `${this.urlEndpoint}langdetect`;
 
@@ -1176,9 +1614,122 @@ export class Client {
       }
       data.version = options.version;
     }
+    // The supported codes are server config (the language routes), so only
+    // the type is checked here; an unsupported code gets the API's 400.
+    if (options.lang !== undefined) {
+      if (typeof options.lang !== 'string') {
+        throw new TypeError('aidetect: lang must be a string.');
+      }
+      data.lang = options.lang;
+    }
+    if (options.zero_retention !== undefined) {
+      if (typeof options.zero_retention !== 'boolean') {
+        throw new TypeError('aidetect: zero_retention must be a boolean.');
+      }
+      data.zero_retention = options.zero_retention;
+    }
+    // Single text only, and not with zero_retention or a public key: the
+    // API 400s those before scoring, so only the type is checked here.
+    if (options.create_report !== undefined) {
+      if (typeof options.create_report !== 'boolean') {
+        throw new TypeError('aidetect: create_report must be a boolean.');
+      }
+      data.create_report = options.create_report;
+    }
 
     return this.axiosPromise(url, 'post', data);
   }
+  /**
+   * Score an uploaded document for AI-generated text (POST /api/v1/file-aidetect).
+   *
+   * The API reads the text of a .pdf, .docx, .pptx, .odt, .txt, .md, .html or
+   * .htm file of up to 30MB and scores its first 200,000 characters like
+   * aidetect() with sentence scores and score_string enabled. The language is
+   * detected and routed automatically (no lang/version option). Billed like
+   * aidetect().
+   *
+   * @param {Blob|File|Buffer|Uint8Array|ArrayBuffer} file - The document.
+   * @param {object} [options]
+   * @param {string} [options.filename] - Required unless `file` is a File: the
+   *   format is chosen by its extension (e.g. 'essay.docx').
+   * @param {boolean} [options.zero_retention] - As for aidetect(): keep no
+   *   copy of the extracted text.
+   * @param {boolean} [options.create_report] - As for aidetect(): save the
+   *   result as a shareable report named after the file and return `report`.
+   */
+  fileAidetect(file, options = {}) {
+    const url = `${this.urlEndpoint}file-aidetect`;
+
+    let params = { key: this.apiKey };
+    if (this.returnUsage) {
+      params.return_usage = true;
+    }
+    if (options?.zero_retention !== undefined) {
+      if (typeof options.zero_retention !== 'boolean') {
+        throw new TypeError('fileAidetect: zero_retention must be a boolean.');
+      }
+      params.zero_retention = options.zero_retention;
+    }
+    if (options?.create_report !== undefined) {
+      if (typeof options.create_report !== 'boolean') {
+        throw new TypeError('fileAidetect: create_report must be a boolean.');
+      }
+      params.create_report = options.create_report;
+    }
+
+    const form = buildUploadForm(file, options?.filename, params, 'fileAidetect');
+    return this.axiosPromise(url, 'post', form);
+  }
+
+  /**
+   * Score a public web page for AI-generated text (POST /api/v1/url-aidetect).
+   *
+   * The API fetches the URL and scores the page's main readable text
+   * (navigation, headers, footers, forms and hidden elements dropped; the
+   * largest <article>, else <main>, preferred) like aidetect(). A linked
+   * .pdf, .docx, .pptx, .odt, .txt or .md document is read like
+   * fileAidetect(). The response adds `source` ({url, title, content_type,
+   * characters, truncated}). Billed like aidetect() on the characters scored.
+   *
+   * @param {string} url - http(s) URL; a bare host/path gets https://.
+   * @param {object} [options] - sent_scores, score_string, version, lang,
+   *   zero_retention, create_report: as for aidetect() (a report is named
+   *   after the final URL).
+   */
+  urlAidetect(url, options = {}) {
+    const endpoint = `${this.urlEndpoint}url-aidetect`;
+
+    // Scheme, length and address checks are the server's (it 400s with a
+    // clear message); only the type is checked here.
+    if (typeof url !== 'string' || url.trim().length === 0) {
+      throw new TypeError('urlAidetect: url must be a non-empty string.');
+    }
+
+    let data = {
+      url,
+      key: this.apiKey,
+    }
+
+    for (const name of ['sent_scores', 'score_string', 'zero_retention', 'create_report']) {
+      if (options?.[name] !== undefined) {
+        if (typeof options[name] !== 'boolean') {
+          throw new TypeError(`urlAidetect: ${name} must be a boolean.`);
+        }
+        data[name] = options[name];
+      }
+    }
+    for (const name of ['version', 'lang']) {
+      if (options?.[name] !== undefined) {
+        if (typeof options[name] !== 'string') {
+          throw new TypeError(`urlAidetect: ${name} must be a string.`);
+        }
+        data[name] = options[name];
+      }
+    }
+
+    return this.axiosPromise(endpoint, 'post', data);
+  }
+
 
   /**
    * Check a text for compliance with style rules you supply (house style,
@@ -1267,11 +1818,17 @@ export class Client {
    */
   styleguideRulesets() {
     const url = `${this.urlEndpoint}styleguide/rulesets`;
-    // Not axiosPromise: this is a GET and the key rides the query string.
+    // Not axiosPromise (that injects into the POST body): this is a GET, so
+    // the key — and the client-level return_usage opt-in — ride the query
+    // string, keeping usage reporting consistent with the sibling POST/DELETE.
+    const params = { key: this.apiKey };
+    if (this.returnUsage) {
+      params.return_usage = true;
+    }
     return axios({
       url,
       method: 'get',
-      params: { key: this.apiKey },
+      params,
       timeout: this.timeout,
     });
   }
@@ -1321,11 +1878,17 @@ export class Client {
       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.
+    // and the API accepts the query form for exactly that reason. The
+    // client-level return_usage opt-in rides it too (axiosPromise only
+    // injects into POST bodies), keeping usage reporting consistent.
+    const params = { key: this.apiKey, name };
+    if (this.returnUsage) {
+      params.return_usage = true;
+    }
     return axios({
       url,
       method: 'delete',
-      params: { key: this.apiKey, name },
+      params,
       timeout: this.timeout,
     });
   }
@@ -1538,6 +2101,157 @@ export class Client {
     return this.axiosPromise(url, 'post', data);
   }
 
+  /**
+   * Measure how closely a resume overlaps with a job description
+   * (POST /api/v1/jd-match): the share of the posting's keywords the resume
+   * uses, the passages the two share word for word, and a low / moderate / high
+   * level. Deterministic and unbilled; both texts count against the rate limit.
+   *
+   * `score` is a heuristic over those two signals, not a probability, and says
+   * nothing about who wrote the resume. High overlap can simply mean a good fit,
+   * so pair it with aidetect() and don't use it alone to decide an application.
+   *
+   * @param {string} text - The resume. The API caps it at 50,000 characters and
+   *   compares it as sent, so `copied_spans` offsets index this exact string, in
+   *   Unicode code points.
+   * @param {string} jobDescription - The posting (sent as the API's
+   *   `job_description`). The API caps it at 20,000 characters and answers 400
+   *   when it has fewer than 5 distinct keywords.
+   * @returns {Promise<AxiosResponse>}
+   */
+  jdMatch(text, jobDescription) {
+    // Length, empty-text and keyword-count checks stay on the server, which
+    // answers each with a clear 400.
+    if (typeof text !== 'string') {
+      throw new TypeError('jdMatch: text must be a string.');
+    }
+    if (typeof jobDescription !== 'string') {
+      throw new TypeError('jdMatch: jobDescription must be a string.');
+    }
+    const data = { key: this.apiKey, text, job_description: jobDescription };
+    return this.axiosPromise(`${this.urlEndpoint}jd-match`, 'post', data);
+  }
+
+  /**
+   * Split text into chunks of at most `maxLength` characters, e.g. to fit an
+   * endpoint's length limit or an LLM context window. Each split prefers, in
+   * order, a page break, a paragraph break, a line break, a tab, ending
+   * punctuation (`.`, `?`, `!`) and then any whitespace, and falls back to a
+   * hard cut at `maxLength`. Chunks don't overlap and keep their delimiters,
+   * so joining them gives back the original text. Unbilled.
+   *
+   * Returns `chunks`, an array of strings in document order.
+   *
+   * @param {string} text - The text to chunk.
+   * @param {number} maxLength - Maximum chunk length in characters (a
+   *   positive integer; sent as the API's `max_length`).
+   * @param {Object} [options]
+   * @param {number} [options.step_size] - Window, in characters, searched
+   *   backwards from each `maxLength` cut for a split point. Larger windows
+   *   find preferred split points more often but vary chunk sizes more.
+   *   Defaults to 10% of the text length.
+   * @returns {Promise<AxiosResponse>}
+   */
+  chunkText(text, maxLength, options = {}) {
+    if (typeof text !== 'string') {
+      throw new TypeError('chunkText: text must be a string.');
+    }
+    const data = chunkBody(this.apiKey, maxLength, options, 'chunkText');
+    data.text = text;
+    return this.axiosPromise(`${this.urlEndpoint}ingest/chunk_text`, 'post', data);
+  }
+
+  /**
+   * Extract the text of an HTML document and split it like chunkText(). Tags
+   * are discarded, so the chunks are plain text. Unbilled.
+   *
+   * @param {string} html - The HTML to extract text from and chunk.
+   * @param {number} maxLength - Maximum chunk length in characters.
+   * @param {Object} [options]
+   * @param {number} [options.step_size] - See chunkText().
+   * @returns {Promise<AxiosResponse>}
+   */
+  chunkHtml(html, maxLength, options = {}) {
+    if (typeof html !== 'string') {
+      throw new TypeError('chunkHtml: html must be a string.');
+    }
+    const data = chunkBody(this.apiKey, maxLength, options, 'chunkHtml');
+    data.html = html;
+    return this.axiosPromise(`${this.urlEndpoint}ingest/chunk_html`, 'post', data);
+  }
+
+  /**
+   * Extract the plain text of an uploaded PDF (POST /api/v1/ingest/pdf_to_text).
+   * Resolves to `{text}`. The API requires a `.pdf` filename; a password-protected,
+   * empty or malformed file gets a 400 whose body is `{error}` (not `{msg}`).
+   * Unbilled.
+   *
+   * @param {Blob|File|Buffer|Uint8Array|ArrayBuffer} file - The PDF.
+   * @param {object} [options]
+   * @param {string} [options.filename] - Required unless `file` is a File,
+   *   e.g. 'report.pdf'.
+   * @returns {Promise<AxiosResponse>}
+   */
+  pdfToText(file, options = {}) {
+    const form = fileToTextForm(this, file, options, 'pdfToText');
+    return this.axiosPromise(`${this.urlEndpoint}ingest/pdf_to_text`, 'post', form);
+  }
+
+  /**
+   * Extract the plain text of an uploaded Word document
+   * (POST /api/v1/ingest/docx_to_text). Resolves to `{text}`, with blocks
+   * (paragraphs, tables) separated by blank lines. The API requires a `.docx`
+   * filename; a corrupt or macro-enabled file gets a 400 whose body is
+   * `{error}` (not `{msg}`). Unbilled.
+   *
+   * @param {Blob|File|Buffer|Uint8Array|ArrayBuffer} file - The DOCX.
+   * @param {object} [options]
+   * @param {string} [options.filename] - Required unless `file` is a File,
+   *   e.g. 'notes.docx'.
+   * @returns {Promise<AxiosResponse>}
+   */
+  docxToText(file, options = {}) {
+    const form = fileToTextForm(this, file, options, 'docxToText');
+    return this.axiosPromise(`${this.urlEndpoint}ingest/docx_to_text`, 'post', form);
+  }
+
+  /**
+   * Release and build identifiers of the deployment answering the request:
+   * `version` (for example `'2026.6'`) and `build`, which is `'unknown'` when the
+   * image carries no build number. Unbilled, and needs no API key and sends
+   * none, so it can check which release a hostname is serving.
+   *
+   * @returns {Promise<AxiosResponse>}
+   */
+  version() {
+    const url = `${this.urlEndpoint}version`;
+    // Not axiosPromise, and no key: the route is public, so neither the API key
+    // nor the client-level return_usage opt-in has any reason to leave the client.
+    return axios({
+      url,
+      method: 'get',
+      timeout: this.timeout,
+    });
+  }
+
+  /**
+   * Whether the API process is up: answers 200 with `{ msg: 'alive' }`. Like
+   * version(), it's unbilled, needs no API key and sends none. It doesn't
+   * check the services behind the API, so it can succeed during an outage of
+   * one of them.
+   *
+   * @returns {Promise<AxiosResponse>}
+   */
+  liveness() {
+    const url = `${this.urlEndpoint}liveness`;
+    // Not axiosPromise, and no key: see version().
+    return axios({
+      url,
+      method: 'get',
+      timeout: this.timeout,
+    });
+  }
+
   /**
    * Check whether an account-wide block (expired key/subscription,
    * depleted credits, billing limit, trial daily allowance, monthly quota)
@@ -1565,7 +2279,10 @@ export class Client {
   accountStatus() {
     const url = `${this.urlEndpoint}account/status`;
     // Not axiosPromise: this is a GET and the key rides the query string,
-    // like styleguideRulesets().
+    // like styleguideRulesets(). The client-level return_usage opt-in is
+    // deliberately not forwarded: the status check is unbilled and the
+    // response already has its own month-to-date `usage` object, which the
+    // API leaves unchanged.
     return axios({
       url,
       method: 'get',
@@ -1573,4 +2290,174 @@ export class Client {
       timeout: this.timeout,
     });
   }
+
+  /**
+   * Usage and cost report for the account that owns this API key (or, for a
+   * team-scoped key, the team): characters and list-price cost over a window,
+   * broken down by key, endpoint, day and month. Keys are identified by
+   * masked ids (`****<last4>-<hash8>`), never raw. Unbilled.
+   *
+   * Returns `start_date`, `end_date`, `total_characters`, `total_cost_usd`,
+   * `currency`, `by_api_key`, `by_endpoint`, `daily_usage`, `monthly_usage`,
+   * `last_updated` and, for keys that are not team-scoped,
+   * `credit_balance_data` (the same object as accountStatus()'s `credits`).
+   * The API answers 400 when start_days_back < end_days_back and 403 for a
+   * window over a year; the window is clamped to the account's age.
+   *
+   * @param {Object} [options]
+   * @param {number} [options.start_days_back] - Days before today the window
+   *   starts. Defaults to the first of the current month.
+   * @param {number} [options.end_days_back] - Days before today the window
+   *   ends (inclusive). Defaults to 0, today.
+   * @returns {Promise<AxiosResponse>}
+   */
+  apiUsage(options = {}) {
+    const url = `${this.urlEndpoint}reporting/api_usage`;
+    const data = reportingWindowBody(this.apiKey, options, 'apiUsage');
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Characters per endpoint over a window, bucketed by day, week or month.
+   * `data` maps an endpoint name (e.g. `EDIT`) to `{<days back>: characters}`,
+   * where each key is the bucket's start as days before today (a string, as
+   * in all JSON object keys). `last_updated` is an ISO timestamp or null.
+   * Unbilled.
+   *
+   * @param {Object} [options]
+   * @param {number} [options.start_days_back] - Days before today the window
+   *   starts. Defaults to 6.
+   * @param {number} [options.end_days_back] - Days before today the window
+   *   ends. Defaults to 0.
+   * @param {'Daily'|'Weekly'|'Monthly'} [options.interval] - Bucket size.
+   *   Defaults to 'Daily'.
+   * @returns {Promise<AxiosResponse>}
+   */
+  apiEndpointUsage(options = {}) {
+    const url = `${this.urlEndpoint}reporting/api_endpoint_usage`;
+    const data = reportingWindowBody(this.apiKey, options, 'apiEndpointUsage');
+    if (options?.interval !== undefined) {
+      if (!REPORTING_INTERVALS.includes(options.interval)) {
+        throw new TypeError(
+          `apiEndpointUsage: interval must be one of ${REPORTING_INTERVALS.join(', ')}.`);
+      }
+      data.interval = options.interval;
+    }
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Monthly quota and characters used over a window. Returns `quota` (the
+   * monthly character limit, -1 for none), `usage` (characters in the
+   * window), `accepts`/`ignores` (suggestions accepted or ignored through
+   * acceptEdit()/rejectEdit() since the first of the current month, whatever
+   * the window) and `last_updated` (Unix epoch seconds). Unbilled.
+   *
+   * The API reads a start_days_back of 0 as 1 (its default), so the shortest
+   * window it reports is yesterday and today.
+   *
+   * @param {Object} [options]
+   * @param {number} [options.start_days_back] - Days before today the window
+   *   starts. Defaults to 1.
+   * @param {number} [options.end_days_back] - Days before today the window
+   *   ends. Defaults to 0.
+   * @returns {Promise<AxiosResponse>}
+   */
+  apiQuotaUsage(options = {}) {
+    const url = `${this.urlEndpoint}reporting/api_quota_usage`;
+    const data = reportingWindowBody(this.apiKey, options, 'apiQuotaUsage');
+    // Not axiosPromise: the client-level return_usage opt-in is deliberately
+    // not forwarded, like accountStatus(). The response's own `usage` is an
+    // integer, which the API leaves unchanged, so the flag would do nothing.
+    return axios({
+      url,
+      method: 'post',
+      data,
+      timeout: this.timeout,
+    });
+  }
+
+  /**
+   * Suggestion activity and active users over a window: `edits_shown`,
+   * `edits_accepted`, `edits_ignored` and `active_users` ({logged_in,
+   * anonymous}). Accepts and ignores are only counted when your integration
+   * reports them with acceptEdit()/rejectEdit(). Unbilled.
+   *
+   * @param {Object} [options]
+   * @param {number} [options.start_days_back] - Days before today the window
+   *   starts. Defaults to 6.
+   * @param {number} [options.end_days_back] - Days before today the window
+   *   ends. Defaults to 0.
+   * @returns {Promise<AxiosResponse>}
+   */
+  apiUserActivity(options = {}) {
+    const url = `${this.urlEndpoint}reporting/api_user_activity`;
+    const data = reportingWindowBody(this.apiKey, options, 'apiUserActivity');
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Inclusive-language check: finds non-inclusive or biased wording
+   * (gendered defaults, ableist idioms, ageist framing, outdated terms for
+   * groups, classist or appearance-based language). Each issue carries the
+   * verbatim passage, start/end offsets into the exact text submitted (null
+   * when the passage can't be located), a category, a severity
+   * (low / medium / high), a short note and a neutral replacement; the
+   * response's `inclusive` is true when nothing was flagged. Wording is
+   * flagged, not topics: text that discusses or quotes a term to critique
+   * it is not an issue.
+   *
+   * @param {string|string[]} text - The text to check, 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 categories 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.categories] - Categories to check (gender,
+   *   race_ethnicity, disability, age, lgbtq, religion, socioeconomic,
+   *   appearance). Default: all of them.
+   */
+  inclusive(text, options = {}) {
+    const url = `${this.urlEndpoint}inclusive`;
+
+    // Shape/type checks only; the set of valid categories is server
+    // configuration and enforced there with a clear 400 (see ner()).
+    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('inclusive: texts must be an array of 1 to 10 non-empty strings.');
+      }
+    } else if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('inclusive: text must be a non-empty string.');
+    }
+
+    let data = {
+      ...(isBatch ? { texts: text } : { text }),
+      key: this.apiKey,
+    }
+
+    // `!== undefined` so an explicit `null` is rejected rather than treated
+    // as omitted; an empty list is rejected too (the API and MCP schema both
+    // require at least one category), matching ner()'s types.
+    if (options?.categories !== undefined) {
+      if (!Array.isArray(options.categories) || options.categories.length === 0
+        || !Array.from(options.categories).every((category) => typeof category === 'string' && category.trim().length > 0)) {
+        throw new TypeError('inclusive: categories must be a non-empty array of non-empty strings.');
+      }
+      data.categories = options.categories;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
 }