@saplingai/sapling-js 1.0.52 → 1.0.54

package/README.md

@@ -2,13 +2,13 @@
 
 Node.js client for the [Sapling.ai API](https://sapling.ai/api).
 
-Try out a [grammar check demo](https://sapling.ai/grammar-check).
+Try out a [grammar check demo](https://sapling.ai/grammar-check) or an [AI detection demo](https://sapling.ai/ai-content-detector). The [SDK demo](https://sapling.ai/sdk-textarea-demo) shows both running live in a textarea through the browser SDK bundled with this package.
 Compare against grammar checking tools and APIs like Grammarly (Grammerly), LanguageTool, ProWritingAid and Ginger.
 
 ## Functionality
 
-Sapling is an AI messaging assistant.
-The API currently offers spelling and grammar checking endpoints.
+Sapling is an AI writing assistant.
+The API offers spelling and grammar checking, AI content detection, rephrasing, tone detection and more; the bundled browser SDK adds in-page grammar suggestions, autocomplete and AI detection to textareas and contenteditables.
 
 Benefits include:
 - **60% more grammar corrections**: Compared to [other systems](https://sapling.ai/comparison/api) at similar accuracy using state-of-the-art generative AI models.
@@ -84,6 +84,24 @@ skips error classification (faster and lighter), and each edit comes back withou
 client.edits('I have a apple!', undefined, { includeErrorCategories: false, autoApply: true })
 ```
 
+`edits()` and `spellcheck()` responses are typed (`EditsResponse`, `SpellcheckResponse`).
+If a model stage can't process some sentences in time, the response still returns
+everything that did complete and adds a `degraded` object. Those sentences may be
+missing some or all of their edits, and the object gives counts only (not which
+sentences), so retry the whole request after a short backoff if you need a
+complete result:
+
+```javascript
+const { data } = await client.edits(text);
+if (data.degraded) {
+  // { sentences_degraded: 1, sentences_total: 12, reason: 'model_timeout' }
+  // reason: model_timeout | model_unavailable | model_error
+}
+```
+
+If no sentence could be checked, the request rejects with a `503` and a
+`Retry-After` header instead (see [Error handling](#error-handling)).
+
 ### Text classification
 
 Zero-shot classification with your own labels (plain names or `{ name, description }` objects, 2–20):
@@ -102,6 +120,219 @@ client
   })
 ```
 
+### AI content detection
+
+```javascript
+const { data } = await client.aidetect(documentText);
+// { score: 0.05, ai_fraction: 0.51, verdict: 'mixed',
+//   segments: [{ start: 0, end: 240, score: 0.96 }],
+//   low_confidence: false, low_confidence_reasons: [], 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. `verdict` sums both up as `'human'`, `'mixed'` or `'ai'`
+(`'ai'` needs `score` ≥ 0.5 and `ai_fraction` ≥ 0.8; `'mixed'` is anything else with `score` ≥ 0.5
+or `ai_fraction` ≥ 0.2; with a null `ai_fraction` it is `'ai'` or `'human'` by `score` alone), and
+is omitted when the text couldn't be scored. `segments` lists each run
+of consecutive sentences scoring ≥ 0.5 as `{ start, end, score }`, even with `sent_scores: false`.
+`low_confidence` is true for inputs with a higher false-positive rate, named in
+`low_confidence_reasons`: `'short_text'` (under 500 characters) and `'list_format'` (mostly bullet or
+numbered lines); show those results hedged rather than as a bare score. `sentence_scores` use the
+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
+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
+detected language when `lang` is set, so a mismatch is visible. Pass an array of 1–10 texts for the
+batch form, which answers `{ results: [...] }` in input order; `lang` applies to every item.
+
+Pass `zero_retention: true` to keep no copy of the text. The request is still scored and billed,
+but its result is not written to the shared result cache and usage is logged without the text (a
+hash of it is kept so a repeat isn't billed twice). Teams with data retention disabled get this on
+every request. `fileAidetect()` and `urlAidetect()` take the same option.
+
+Pass `create_report: true` (single text only, not a batch) to also save the result as a shareable
+report: the response adds `report` (`{ id, url, shared_at, expires_at }`), a public link to the
+text and its scores that you can revoke from your AI detector history and that expires 90 days
+after creation. It needs your private API key, and can't be combined with `zero_retention`
+(both get a 400). When no report can be made (for example, history or text retention is turned
+off, or the history is full), `report` is `null` and `report_skip_reason` says why; the request is
+still scored and billed. `fileAidetect()` and `urlAidetect()` take it too, naming the report after
+the file or the final URL.
+
+```javascript
+const { data } = await client.aidetect(reviewText, { lang: 'pt-BR' }); // version: 'ml20261009'
+```
+
+To score a document without extracting its text yourself, upload it with `fileAidetect()`. It
+accepts `.pdf`, `.docx`, `.pptx`, `.odt`, `.txt`, `.md`, `.html` or `.htm` files up to 30MB, and the
+format is chosen by file extension. The first 200,000 characters of the document's text are scored
+like `aidetect()`, with `sentence_scores` and `score_string` always included. The language is
+detected and routed automatically; there is no `lang` or `version` option, but `zero_retention`
+works as on `aidetect()`. Billing is the same as `aidetect()`.
+
+```javascript
+import { readFileSync } from 'node:fs';
+
+const { data } = await client.fileAidetect(readFileSync('essay.pdf'), { filename: 'essay.pdf' });
+// In the browser, pass the File from an <input type="file"> (its own name is used):
+// await client.fileAidetect(input.files[0]);
+```
+
+To score a web page, pass its URL to `urlAidetect()`. The API fetches the page and scores its main
+readable text: navigation, headers, footers, forms and hidden elements are dropped, and the largest
+`<article>` (else `<main>`) is preferred, so a scraped page's boilerplate isn't scored or billed. A
+URL that serves a `.pdf`, `.docx`, `.pptx`, `.odt`, `.txt` or `.md` document is read like
+`fileAidetect()`. Options and billing are the same as `aidetect()`, and the response adds `source`:
+the final URL after redirects, the page title, its content type, the `characters` scored, and
+`truncated` (HTML past 2MB, documents past 15MB and text past 200,000 characters are not scored).
+Only public http(s) URLs on ports 80/443/8080/8443 are fetched, at most 30 per minute per account. A
+page that is fetched but can't be scored (a non-2xx status, unsupported type, no readable text)
+answers 422, and one that can't be fetched (timeout, connection failure, or a site that blocks
+automated requests) answers 502.
+
+```javascript
+const { data } = await client.urlAidetect('https://example.com/blog/post', { sent_scores: false });
+// { score: 0.93, ai_fraction: 0.88, text: '...', version: '...', ...,
+//   source: { url: 'https://example.com/blog/post', title: '...', content_type: 'text/html',
+//             characters: 5120, truncated: false } }
+```
+
+### Rephrase, tone, 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: tone } = await client.tone('Really stoked about this! Will it be ready by next week?');
+// { overall: [[0.92, 'curious', '🤓'], [0.05, 'excited', '😀'], [0.01, 'confused', '😕']],
+//   results: [[[0.99, 'excited', '😀'], ...], [[0.55, 'confused', '😕'], ...]],
+//   sents: ['Really stoked about this!', 'Will it be ready by next week?'] }
+
+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`). Tones come as
+`[probability, tone name, emoji]` triples: `overall` holds up to three for the whole text, most
+likely first, with probabilities summing to 1, and `results` holds one list per sentence. A text
+the API cannot split into sentences gets a 200 with `[]`, and the text is capped at 8000
+characters. 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`).
+
+### Autocomplete
+
+```javascript
+const { data: completion } = await client.complete('Thanks for getting back to me so');
+if (!Array.isArray(completion)) {
+  // { output: ' quickly.', query: 'Thanks for getting back to me so', hash: '...' }
+  // When the user takes the suggestion:
+  await client.acceptComplete(completion.hash, completion.query, completion.output);
+}
+```
+
+`complete()` needs an API key with autocomplete enabled and a query of at most 200 characters.
+It answers `[]` when it has no completion. `query` in the response is the part of the sent
+query the prediction continues: the API keeps only the text after the last run of three
+spaces. Pass `hash`, `query` and `output` to `acceptComplete()` unchanged, because the API
+checks them against the hash and answers 400 when they don't match.
+
+### Language detection
+
+```javascript
+const { data: detected } = await client.langdetect('Bonjour tout le monde, comment allez-vous ?');
+// { lang: 'fr', conf: 0.99, name: 'French', reliable: true, script: 'Latn',
+//   candidates: [{ lang: 'fr', conf: 0.99, name: 'French' }, ...] }
+
+const { data: short } = await client.langdetect('Hola');
+// { lang: 'es', conf: 0.95, name: 'Spanish', reliable: false, script: 'Latn', ... }
+```
+
+Act on `lang` only when `reliable` is true. It is true only when the confidence is high and the
+text has enough letters, so short inputs like `"OK"` or `"Hola"` are never reliable however high
+`conf` is. `script` is the text's dominant writing system as an ISO 15924 code: `Latn`, `Cyrl`,
+`Arab`, `Deva`, `Hang`, `Hani` for Chinese, and `Jpan` once the text contains any kana. It is `Zzzz`
+for a script outside the map, and `null` when the text has no letters. Options are `top_k` (1–10
+candidates, default 3) and `segments: true`, which adds a per-sentence `segments` breakdown (`start`,
+`end`, `text` plus the same fields) for mixed-language text. Pass an array of 1–10 texts for the
+batch form, `{ results: [...] }`. Language detection is unbilled.
+
+### 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.
+
+### Custom mappings and custom filters
+
+```javascript
+// Always suggest `mapping` wherever `entry` matches (brand names, house style).
+const { data: mapping } = await client.addCustomMapping('sapling', 'Sapling', {
+  description: 'Our product name is capitalized.', // shown with the suggestion; it then can't be ignored
+});
+// { id: '...', entry: 'sapling', mapping: 'Sapling', description: '...', case_sensitive: true, ... }
+const { data: { custom_mappings } } = await client.customMappings(); // sorted by entry
+await client.deleteCustomMapping(mapping.id);                         // 204, empty body
+
+// Stop suggesting edits that rewrite `input` to `output`; '' on either side is a wildcard.
+const { data: filter } = await client.addCustomFilter('Patient', 'The patient');
+// { id: '...', input: 'Patient', output: 'The patient', case_sensitive: true, ... }
+const { data: { custom_filters } } = await client.customFilters();   // sorted by input
+await client.deleteCustomFilter(filter.id);                           // 204, empty body
+```
+
+In a mapping's `entry`, `^` and `$` anchor the match to the start and end of a sentence, and `#`
+matches a number (a `#` in `mapping` puts it back). `case_sensitive` defaults to true. The API
+answers 400 for a duplicate, an entry equal to its mapping (or a filter whose two sides are equal),
+more than two digits in the entry or input, and a case-insensitive rule whose two sides differ only
+in case (`iphone` → `iPhone` must be case sensitive). A filter needs at least one non-blank side.
+Deleting an id that is not this account's answers 400, not 404. All six calls are unbilled.
+
 ### Style-guide rulesets
 
 Check text against style rules inline, or save a named ruleset once (owned by
@@ -191,6 +422,47 @@ as `YYYY-MM-DD`, or `'list'`), and every value must be grounded in a quote from
 extraction, not inference, so a value that isn't stated is reported in `missing` rather than
 guessed.
 
+### Extracting from documents
+
+`fileExtract()` runs the same extraction over an uploaded document. It takes the same file types
+and 30MB limit as `fileAidetect()`, and the same `fields` and `context` as `extract()`. Only the
+first 10,000 characters of the document's text are read. The response adds a `document` block that
+says how much text was used; `characters_used` is what is billed.
+
+```javascript
+const { data } = await client.fileExtract(
+  readFileSync('invoice.pdf'),
+  ['invoice_number', { name: 'total', type: 'number' }, { name: 'due_date', type: 'date' }],
+  { filename: 'invoice.pdf', context: 'A vendor invoice' },
+);
+// { data: { invoice_number: 'INV-1042', total: 1299.0, due_date: '2026-03-05' }, fields: [...],
+//   missing: [],
+//   document: { file_type: 'pdf', characters: 2310, characters_used: 2310, truncated: false } }
+```
+
+When `truncated` is true, fields that appear only after the first 10,000 characters are reported
+in `missing`. To read a later section, extract its text yourself and pass it to `extract()`.
+
+## Document Summarization
+
+`fileSummarize()` summarizes an uploaded document: the same `summary`, `key_points` and `length`
+as the API's `/summarize` endpoint, for the same file types and 30MB limit as `fileAidetect()`.
+`length` is `'short'`, `'medium'` (the default) or `'long'`. Only the first 20,000 characters of the
+document's text are read, and the `document` block says how much was used; `characters_used` is
+what is billed.
+
+```javascript
+const { data } = await client.fileSummarize(readFileSync('report.pdf'),
+  { filename: 'report.pdf', length: 'short' });
+// { summary: 'Revenue rose 12% ...', key_points: ['...', '...'], length: 'short', result: '...',
+//   document: { file_type: 'pdf', characters: 48210, characters_used: 19996, truncated: true } }
+```
+
+All three upload methods take a `File`/`Blob` (in the browser, or Node 18+) or the file's bytes
+(`Buffer`, `Uint8Array`, `ArrayBuffer`). Bytes need `options.filename`, because the extension picks
+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.
+
 ## Translation
 
 Translate text into a target language, named by ISO 639 code (`'fr'`, `'zh-TW'`) or English
@@ -213,12 +485,58 @@ Region variants `zh-CN`/`zh-TW`/`zh-HK`, `pt-BR`/`pt-PT`, `en-GB`/`en-US`, `fr-C
 text actually is, and `formality` (`'formal'`/`'informal'`) picks the register where the
 target language distinguishes them.
 
+## Inclusive Language
+
+Flag non-inclusive or biased wording (gendered defaults, ableist idioms, ageist framing,
+outdated terms for groups) with offsets, a category, a severity and a neutral replacement:
+
+```javascript
+client
+  .inclusive('The chairman said the plan was crazy.', { categories: ['gender', 'disability'] })
+  .then(function (response) {
+    console.log(response.data);
+    // { issues: [
+    //     { category: 'gender', severity: 'low', text: 'The chairman', start: 0, end: 12,
+    //       note: 'Gendered job title...', suggestion: 'The chair' },
+    //     { category: 'disability', severity: 'low', text: 'crazy', start: 31, end: 36,
+    //       note: 'Ableist idiom...', suggestion: 'unworkable' } ],
+    //   categories: ['gender', 'disability'], inclusive: false }
+  })
+```
+
+Categories: `gender`, `race_ethnicity`, `disability`, `age`, `lgbtq`, `religion`,
+`socioeconomic`, `appearance` (default: all). Pass an array of up to 10 texts for the batch
+form (`{ results: [...] }`).
+
 ## Further Documentation
 
 - Full Sapling HTTP API and SDK [documentation](https://sapling.ai/docs).
 - Create a key by following [these instructions](https://sapling.ai/docs/api/api-access).
 - JavaScript, HTML, and Python [starter code](https://github.com/saplingai/sapling-samples).
 
+## Usage reporting
+
+Construct the client with `returnUsage: true` and every successful response additionally
+reports the usage the request submitted for metering, as a top-level `usage` field:
+
+```javascript
+const client = new Client(apiKey, { returnUsage: true });
+const response = await client.classify('I was charged twice.', ['billing', 'other']);
+console.log(response.data.usage);
+// { characters: 20 }
+```
+
+`characters` is the count submitted for billing (one count per **distinct** item of a batch
+request; `0` for unbilled requests). It is captured before the billing pipeline's dedup
+window applies, so it is an upper bound on the final charge. Batch responses carry `usage`
+on the `{ results: [...] }` wrapper, not on the per-item results.
+`accountStatus()` and `apiQuotaUsage()` are unaffected: both are unbilled and their responses
+already have their own `usage` field, which the option leaves untouched.
+Responses that are not a JSON object cannot carry the field, so `dictionaryEntries()` (a bare
+array), `deleteDictionaryEntry()`, `deleteCustomMapping()` and `deleteCustomFilter()` (`204`,
+empty body), `sentiment()`'s `204` / `[]` edge cases and the `[]` answers of `tone()` and
+`complete()` never report it.
+
 ## Error handling
 
 Every client method returns the axios promise, so API errors (a `400` for
@@ -238,7 +556,9 @@ API error bodies are JSON objects with a human-readable `msg`, for example
 `{ msg: 'Invalid API key.' }`. The one exception is the 4MB `413`, which uses
 `message`/`result` keys. When a `402` or `429` body has a numeric `retry_after`,
 the request can succeed after waiting that many seconds. Without it, retrying
-unchanged won't help. See
+unchanged won't help. A `503` means the service is temporarily saturated: wait
+for its `Retry-After` header (`error.response.headers['retry-after']`, in
+seconds), then retry. See
 [Rate Limits & Errors](https://sapling.ai/docs/rate_limits/).
 
 To find out why a key is blocked, and for how long, call `accountStatus()`. It
@@ -264,3 +584,25 @@ account's `subscription`, prepaid `credits`, `usage.chars_this_month` and, on a
 free trial, `trial`. See [Account Status](https://sapling.ai/docs/api/account-status/).
 Each call counts as 2,000 characters against the endpoint's own rate-limit
 bucket, so call it when something fails rather than before every request.
+
+## Usage and quota reports
+
+Four unbilled methods report this key's usage over a window of days, set with
+`start_days_back` / `end_days_back` (non-negative integers, days before today):
+
+```javascript
+const { data } = await client.apiUsage({ start_days_back: 30 });
+console.log(data.total_characters, data.total_cost_usd, data.by_endpoint);
+```
+
+- `apiUsage()`: characters and list-price cost by masked key id, endpoint, day and month.
+  The window defaults to the current month. A team-scoped key covers the whole team; other
+  keys also get `credit_balance_data`.
+- `apiEndpointUsage({ interval })`: characters per endpoint, bucketed `'Daily'`
+  (default), `'Weekly'` or `'Monthly'`.
+- `apiQuotaUsage()`: the monthly `quota` (`-1` for none) and the window's `usage`.
+- `apiUserActivity()`: edits shown, accepted and ignored, plus active users. Accepts and
+  ignores are only counted if you report them with `acceptEdit()` / `rejectEdit()`.
+
+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/).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@saplingai/sapling-js",
-  "version": "1.0.52",
-  "description": "JavaScript library for using the Sapling.ai API.",
+  "version": "1.0.54",
+  "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",
   "types": "./sapling/client.d.ts",