@saplingai/sapling-js 1.0.54 → 1.0.55

package/README.md

@@ -144,12 +144,12 @@ numbered lines); show those results hedged rather than as a bare score. `sentenc
 same model and 0.5 threshold, and their `start`/`end` (like a segment's) 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. English, Spanish, Portuguese, French, German, Italian, Dutch and Japanese are
-supported: unpinned text detected as `es`, `pt`, `fr`, `de`, `it`, `nl` or `ja` is scored by a
-multilingual model and answers `version: 'ml20261009'` (that model has no Italian or Dutch training
-data yet, so it catches somewhat less AI-generated text in those two), while other languages are
-scored by the English model and are less reliable. Options: `sent_scores` (default true), `score_string` (HTML
-heatmap), `lang` (`'en'`, `'es'`, `'pt'`, `'fr'`, `'de'`, `'it'`, `'nl'` or `'ja'`, case-insensitive, region
+identified. English, Arabic, Chinese, Dutch, French, German, Italian, Japanese, Korean, Polish,
+Portuguese, Romanian, Russian, Spanish, Swedish and Turkish are supported: unpinned text detected as `ar`,
+`de`, `es`, `fr`, `it`, `ja`, `ko`, `nl`, `pl`, `pt`, `ro`, `ru`, `sv`, `tr` or `zh` is scored by a
+multilingual model (trained on all fifteen) and answers `version: 'ml20261104'`, while other
+languages are scored by the English model and are less reliable. Options: `sent_scores` (default true), `score_string` (HTML
+heatmap), `lang` (`'en'`, `'ar'`, `'de'`, `'es'`, `'fr'`, `'it'`, `'ja'`, `'ko'`, `'nl'`, `'pl'`, `'pt'`, `'ro'`, `'ru'`, `'sv'`, `'tr'` or `'zh'`, case-insensitive, region
 subtags such as `'pt-BR'` accepted: use that language's model instead of detecting it, which helps
 with short texts; omit it or pass `'auto'` to detect; other languages get a 400), `version` (pin
 a model; a pin always overrides the language routing and `lang`). `language` still reports the
@@ -171,7 +171,7 @@ still scored and billed. `fileAidetect()` and `urlAidetect()` take it too, namin
 the file or the final URL.
 
 ```javascript
-const { data } = await client.aidetect(reviewText, { lang: 'pt-BR' }); // version: 'ml20261009'
+const { data } = await client.aidetect(reviewText, { lang: 'pt-BR' }); // version: 'ml20261104'
 ```
 
 To score a document without extracting its text yourself, upload it with `fileAidetect()`. It
@@ -208,6 +208,27 @@ const { data } = await client.urlAidetect('https://example.com/blog/post', { sen
 //             characters: 5120, truncated: false } }
 ```
 
+### Resume and job description overlap
+
+`jdMatch()` measures how closely a resume overlaps with the job description it was submitted for:
+
+```javascript
+const { data } = await client.jdMatch(resumeText, jobDescriptionText);
+// { score: 0.786, level: 'high', keyword_coverage: 0.571,
+//   matched_keywords: [{ term: 'python', job_description_count: 1, resume_count: 1 }, ...],
+//   missing_keywords: [{ term: 'terraform', job_description_count: 1 }, ...],
+//   copied_fraction: 0.312, has_copied_span: true, copied_spans_total: 1,
+//   copied_spans: [{ start: 136, end: 207, text: '...', words: 10 }],
+//   resume_words: 32, job_description_words: 43, version: '...' }
+```
+
+`score` (0–1) is a heuristic over keyword coverage and passages of 6+ words shared verbatim, not a
+probability. It says nothing about who wrote the resume, and high overlap can simply mean a good fit,
+so pair it with `aidetect()` and don't use it alone to decide an application. It's unbilled and
+tuned for English. The API caps the resume at 50,000 characters and the posting at 20,000, and a
+posting with fewer than 5 distinct keywords gets a 400. Span offsets index the resume in Unicode code
+points.
+
 ### Rephrase, tone, sentiment and readability statistics
 
 ```javascript
@@ -463,6 +484,37 @@ All three upload methods take a `File`/`Blob` (in the browser, or Node 18+) or t
 the format. File problems come back as 400 `{ error: '...' }` and an oversized upload as 413.
 Uploads are limited to 60 per minute per account across all three methods.
 
+## Chunking
+
+`chunkText()` splits long text into chunks of at most `maxLength` characters, e.g. to keep each
+piece under another endpoint's length limit. Each split prefers a page break, then a paragraph
+break, a line break, a tab, ending punctuation and any whitespace, before falling back to a hard
+cut. Chunks don't overlap, so joining them gives back the original text. `chunkHtml()` does the
+same for HTML after stripping the tags. Both are unbilled.
+
+```javascript
+const { data } = await client.chunkText('Here is one paragraph.\n\nHere is another.', 25);
+// { chunks: ['Here is one paragraph.\n\n', 'Here is another.'] }
+```
+
+`maxLength` must be a positive integer. The optional `step_size` sets how far back from each cut
+to look for a split point; it defaults to 10% of the text length. See
+[Chunking](https://sapling.ai/docs/api/chunk/).
+
+`pdfToText()` and `docxToText()` return the plain text of an uploaded PDF or Word document, for
+example to chunk it before sending it to another endpoint. Pass a `File`/`Blob`, or the file's
+bytes with `filename`, which must end in `.pdf` or `.docx`. Both are unbilled.
+
+```javascript
+import { readFile } from 'node:fs/promises';
+
+const { data } = await client.pdfToText(await readFile('report.pdf'), { filename: 'report.pdf' });
+const { data: chunks } = await client.chunkText(data.text, 4000);
+```
+
+On a file the API can't read (password-protected, empty or corrupt), the 400 body is `{ error }`
+rather than `{ msg }`. See [File Uploads](https://sapling.ai/docs/api/files/).
+
 ## Translation
 
 Translate text into a target language, named by ISO 639 code (`'fr'`, `'zh-TW'`) or English
@@ -606,3 +658,20 @@ console.log(data.total_characters, data.total_cost_usd, data.by_endpoint);
 
 A window over a year gets a `403`. Unlike `accountStatus()`, these need a key that isn't
 blocked. See [API Reporting](https://sapling.ai/docs/api/api-reporting/).
+
+## Health checks
+
+`version()` and `liveness()` are unbilled and need no API key. The client doesn't send its key
+on these calls.
+
+```javascript
+const { data } = await client.version();
+console.log(data.version, data.build); // 2026.6 v4626
+
+await client.liveness(); // { msg: 'alive' }
+```
+
+`version()` reports which release a hostname is serving, which is useful on-prem. `build` is
+`'unknown'` when the image carries no build number. `liveness()` only says the API process is up,
+so it can succeed while a service behind the API is down. To check that a key works, use
+`accountStatus()`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saplingai/sapling-js",
-  "version": "1.0.54",
+  "version": "1.0.55",
   "description": "JavaScript client for the Sapling.ai API (grammar checking, AI content detection, rephrasing and more) plus the browser SDK.",
   "type": "module",
   "main": "./sapling/client.js",

package/sapling/client.d.ts

@@ -23,6 +23,7 @@ export type AdvancedEditOptions = {
 export type ConstructorOptions = {
    timeout?: number,
    hostname?: string,
+   /** API path override. Leading and trailing slashes are optional. */
    pathname?: string,
    /**
     * When true, every request carries the API's `return_usage: true` flag and
@@ -148,11 +149,11 @@ export type AIDetectOptions = {
    sent_scores?: boolean,
    /** Include `score_string`, an HTML heatmap of the scored text. */
    score_string?: boolean,
-   /** Pin a detector model version (e.g. `'20251027'`, or `'ml20261009'` for the multilingual
-    *  model); omitted = current default, with text detected as `es`/`pt`/`fr`/`de`/`it`/`nl`/`ja`
+   /** Pin a detector model version (e.g. `'20260820'`, or `'ml20261104'` for the current multilingual
+    *  model; the previous multilingual models `'ml20261009'`, `'ml20261031'`, `'ml20261102'` and `'ml20261103'` stay pinnable); omitted = current default, with text detected as `ar`/`de`/`es`/`fr`/`it`/`ja`/`ko`/`nl`/`pl`/`pt`/`ro`/`ru`/`sv`/`tr`/`zh`
     *  routed to the multilingual model. A pin always wins over that routing and over `lang`. */
    version?: string,
-   /** Language of the text: `'en'`, `'es'`, `'pt'`, `'fr'`, `'de'`, `'it'`, `'nl'` or `'ja'`
+   /** Language of the text: `'en'`, `'ar'`, `'de'`, `'es'`, `'fr'`, `'it'`, `'ja'`, `'ko'`, `'nl'`, `'pl'`, `'pt'`, `'ro'`, `'ru'`, `'sv'`, `'tr'` or `'zh'`
     *  (case-insensitive; region subtags such as `'pt-BR'` are accepted). Picks that language's
     *  model instead of relying on detection, which helps with short texts; omit it (or pass
     *  `'auto'`) to detect.
@@ -228,8 +229,8 @@ export type AIDetectResponse = {
    text: string;
    tokens: string[];
    token_probs: number[];
-   /** The pinned `version` when one was requested; `'ml20261009'` when unpinned text was
-    *  detected as (or `lang` named) `es`/`pt`/`fr`/`de`/`it`/`nl`/`ja` and scored by the
+   /** The pinned `version` when one was requested; `'ml20261104'` when unpinned text was
+    *  detected as (or `lang` named) `ar`/`de`/`es`/`fr`/`it`/`ja`/`ko`/`nl`/`pl`/`pt`/`ro`/`ru`/`sv`/`tr`/`zh` and scored by the
     *  multilingual model; otherwise an opaque identifier of the default model — log it, don't
     *  parse it. */
    version: string;
@@ -239,8 +240,8 @@ export type AIDetectResponse = {
    score_string?: string;
    /** Advisory detected language; omitted unless detection is high-confidence. Always the
     *  detected language, even when `lang` was sent, so a mismatch is visible.
-    *  English plus `es`, `pt`, `fr`, `de`, `it`, `nl` and `ja` (routed to the multilingual
-    *  model) are supported; other languages are scored by the English model and are less
+    *  English plus `ar`, `de`, `es`, `fr`, `it`, `ja`, `ko`, `nl`, `pl`, `pt`, `ro`, `ru`, `sv`,
+    *  `tr` and `zh` (routed to the multilingual model) are supported; other languages are scored by the English model and are less
     *  reliable. */
    language?: AIDetectLanguage;
 }
@@ -341,6 +342,61 @@ export type DeleteStyleguideRulesetResponse = {
    deleted: string;
 }
 
+export type ChunkOptions = {
+   step_size?: number;
+}
+
+export type ChunkResponse = {
+   chunks: string[];
+}
+
+export type JdMatchLevel = 'low' | 'moderate' | 'high';
+
+export type JdMatchMatchedKeyword = {
+   term: string;
+   job_description_count: number;
+   resume_count: number;
+}
+
+export type JdMatchMissingKeyword = {
+   term: string;
+   job_description_count: number;
+}
+
+export type JdMatchCopiedSpan = {
+   /** Offsets into the submitted resume (`end` exclusive), in Unicode code points —
+    *  slice with `Array.from(text)` if it may contain emoji. */
+   start: number;
+   end: number;
+   text: string;
+   words: number;
+}
+
+/** jdMatch(): a text overlap report. It says nothing about who wrote the resume. */
+export type JdMatchResponse = {
+   /** 0–1. A heuristic over keyword coverage and copying, not a probability. */
+   score: number;
+   level: JdMatchLevel;
+   keyword_coverage: number;
+   matched_keywords: JdMatchMatchedKeyword[];
+   missing_keywords: JdMatchMissingKeyword[];
+   /** Share of the resume's words inside a copied span. */
+   copied_fraction: number;
+   /** Whether the resume shares any run of 6+ words verbatim with the posting. */
+   has_copied_span: boolean;
+   /** At most 50, in document order; `copied_spans_total` has the full count. */
+   copied_spans: JdMatchCopiedSpan[];
+   copied_spans_total: number;
+   resume_words: number;
+   job_description_words: number;
+   version: string;
+}
+
+/** pdfToText()/docxToText(): the document's plain text. */
+export type FileToTextResponse = {
+   text: string;
+}
+
 export type AccountBlockedReason =
    | 'key_expired'
    | 'subscription_expired'
@@ -353,6 +409,9 @@ export type AccountCreditSummary = {
    enabled: boolean;
    currency: string;
    alert_threshold_percent: number;
+   // Prepaid-only account: API access needs a positive credit balance. Sent
+   // whether or not `enabled` is true (optional for older on-prem servers).
+   credits_only?: boolean;
    // Present only when `enabled` is true.
    balance_credits?: number;
    purchased_credits?: number;
@@ -1058,6 +1117,17 @@ export type UserDetails = {
    anonUser?: boolean,
 }
 
+export type VersionResponse = {
+  /** Release version, for example `'2026.6'`. */
+  version: string;
+  /** Build identifier; `'unknown'` when the image carries no build number. */
+  build: string;
+};
+
+export type LivenessResponse = {
+  msg: 'alive';
+};
+
 export declare class Client {
    constructor(apiKey: string, options?: ConstructorOptions);
 
@@ -1142,6 +1212,17 @@ export declare class Client {
    classify(texts: string[], labels: ClassifyLabel[], options?: ClassifyOptions): Promise<AxiosResponse<WithUsage<ClassifyBatchResponse>>>;
    classify(text: string | string[], labels: ClassifyLabel[], options?: ClassifyOptions): Promise<AxiosResponse<WithUsage<ClassifyResponse | ClassifyBatchResponse>>>;
    seo(text: string, options?: SeoOptions): Promise<AxiosResponse<WithUsage<SeoResponse>>>;
+   jdMatch(text: string, jobDescription: string): Promise<AxiosResponse<WithUsage<JdMatchResponse>>>;
+   chunkText(text: string, maxLength: number, options?: ChunkOptions): Promise<AxiosResponse<WithUsage<ChunkResponse>>>;
+   chunkHtml(html: string, maxLength: number, options?: ChunkOptions): Promise<AxiosResponse<WithUsage<ChunkResponse>>>;
+   /** `file` must be named `*.pdf` (a File's own name, or options.filename). */
+   pdfToText(file: UploadFile, options?: FileUploadOptions): Promise<AxiosResponse<WithUsage<FileToTextResponse>>>;
+   /** `file` must be named `*.docx` (a File's own name, or options.filename). */
+   docxToText(file: UploadFile, options?: FileUploadOptions): Promise<AxiosResponse<WithUsage<FileToTextResponse>>>;
+   /** Not WithUsage<>: public and unbilled, and sends neither the API key nor return_usage. */
+   version(): Promise<AxiosResponse<VersionResponse>>;
+   /** Not WithUsage<>: public and unbilled, and sends neither the API key nor return_usage. */
+   liveness(): Promise<AxiosResponse<LivenessResponse>>;
    accountStatus(): Promise<AxiosResponse<AccountStatusResponse>>;
    apiUsage(options?: ReportingWindowOptions): Promise<AxiosResponse<WithUsage<ApiUsageResponse>>>;
    apiEndpointUsage(options?: ApiEndpointUsageOptions): Promise<AxiosResponse<WithUsage<ApiEndpointUsageResponse>>>;

package/sapling/client.js

@@ -45,6 +45,23 @@ const reportingWindowBody = (apiKey, options, method) => {
   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
 // there with a clear 400 (see classify()).
@@ -178,12 +195,24 @@ const buildUploadForm = (file, filename, jsonParams, method) => {
   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
@@ -2072,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)