@saplingai/sapling-js 1.0.52 → 1.0.54

package/sapling/client.d.ts

@@ -24,10 +24,42 @@ export type ConstructorOptions = {
    timeout?: number,
    hostname?: string,
    pathname?: string,
+   /**
+    * When true, every request carries the API's `return_usage: true` flag and
+    * every successful JSON-object response additionally reports the usage the
+    * request submitted for metering as a top-level `usage` field (see
+    * `ApiUsage`). Defaults to false.
+    */
+   returnUsage?: boolean,
 }
 
+/**
+ * Usage a request submitted for metering, reported when the client is
+ * constructed with `returnUsage: true`. `characters` is the count the request
+ * 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.
+ */
+export type ApiUsage = {
+   characters: number;
+}
+
+/**
+ * A top-level API response with the optional `usage` report attached
+ * (present only on successful responses when the client was constructed with
+ * `returnUsage: true`). Batch responses carry it on the wrapper object, not
+ * on the per-item results.
+ */
+export type WithUsage<T> = T & { usage?: ApiUsage };
+
+/** English varieties the API accepts for `variety`. `string & {}` keeps the
+ *  literals as autocomplete hints while still accepting any string. */
+export type EnglishVariety = 'us-variety' | 'gb-variety' | 'au-variety' | 'ca-variety'
+   | 's-variety' | 't-variety' | 'null-variety' | (string & {});
+
 export type EditOptions = {
-   variety?: string,
+   /** English variety to enforce. The API rejects other values with a 400. */
+   variety?: EnglishVariety,
    autoApply?: boolean,
    lang?: string,
    medical?: boolean,
@@ -37,8 +69,235 @@ export type EditOptions = {
    includeErrorCategories?: boolean,
 }
 
+/** One suggested edit. `start`/`end` are offsets into `sentence`; add
+ *  `sentence_start` to get offsets into the submitted text. */
+export type SpellcheckEdit = {
+   /** Opaque edit id; pass to acceptEdit()/rejectEdit(). */
+   id: string,
+   /** The unedited sentence containing the edit. */
+   sentence: string,
+   sentence_start: number,
+   start: number,
+   end: number,
+   replacement: string,
+}
+
+export type Edit = SpellcheckEdit & {
+   /** Error type (see the API's Error Categories page). Omitted when
+    *  `includeErrorCategories` is false. */
+   error_type?: string,
+   general_error_type?: string,
+   /** Explanation for some edits; advanced edits carry their own (may be null). */
+   description?: string | null,
+}
+
+/** Why some sentences are missing model edits. */
+export type DegradedReason = 'model_timeout' | 'model_unavailable' | 'model_error';
+
+/**
+ * Present only on a partial result: a model stage could not process some
+ * sentences in time, so those sentences may be missing some or all of their
+ * edits. Counts only: the response does not say which sentences, so retry the
+ * whole request after a short backoff for a complete result. A total failure
+ * is an HTTP 503 with `Retry-After` instead.
+ */
+export type Degraded = {
+   sentences_degraded: number,
+   sentences_total: number,
+   reason: DegradedReason,
+}
+
+/** A sentence the API skipped without checking. */
+export type IgnoredSentence = {
+   sentence: string,
+   reason: 'SENTENCE_EXCEEDS_MAX_LENGTH' | 'UNRECOGNIZED_CHARACTER_SET' | 'INVALID_TOKENS_FOUND',
+}
+
+export type EditsResponse = {
+   /** Sorted by position in the text. */
+   edits: Edit[],
+   /** The detected language; only when `lang: 'auto'` was sent. */
+   lang?: string,
+   /** The text with every edit applied; only when `autoApply: true`. Advanced edits
+    *  are never applied. */
+   applied_text?: string,
+   /** Set with `applied_text` when the text contains HTML tags, which auto-apply
+    *  does not account for. */
+   warning?: string,
+   'ignored-sentences'?: IgnoredSentence[],
+   degraded?: Degraded,
+}
+
+export type SpellcheckResponse = {
+   edits: SpellcheckEdit[],
+   /** The detected language; only when `lang: 'auto'` was sent. */
+   lang?: string,
+   /** Misspelled word -> ranked candidate corrections; only with `multipleEdits: true`
+    *  (empty when the neural spellchecker served the request). */
+   candidates?: Record<string, string[]>,
+   /** Echo of the `userData` option, when sent. */
+   user_data?: unknown,
+   /** Only when `autoApply: true`. */
+   applied_text?: string,
+   warning?: string,
+   degraded?: Degraded,
+}
+
 export type AIDetectOptions = {
+   /** Include `sentence_scores` (server default true). */
    sent_scores?: boolean,
+   /** Include `score_string`, an HTML heatmap of the scored text. */
+   score_string?: boolean,
+   /** Pin a detector model version (e.g. `'20251027'`, or `'ml20261009'` for the multilingual
+    *  model); omitted = current default, with text detected as `es`/`pt`/`fr`/`de`/`it`/`nl`/`ja`
+    *  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'`
+    *  (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.
+    *  Other languages are rejected with a 400. Applies to every item of a batch. */
+   lang?: string,
+   /** Keep no copy of the text: the result is still scored and billed (repeats within the
+    *  deduplication window are still not billed twice), but it is not written to the shared
+    *  result cache and usage is logged without the text. Default false; always on for teams with
+    *  data retention disabled. Applies to every item of a batch. */
+   zero_retention?: boolean,
+   /** Also save the result as a shareable report and return its link in `report`. A single
+    *  text only (not a batch). The report is saved to your AI detector history, where you can
+    *  revoke the link; anyone with the link can view the text and its scores until it is
+    *  revoked or expires 90 days after creation. Requires your private API key (OAuth access
+    *  tokens and public API keys get a 400, as does combining it with `zero_retention`). When
+    *  no report can be made, `report` is null and `report_skip_reason` says why; the request
+    *  is still scored and billed. */
+   create_report?: boolean,
+}
+
+/** aidetect() batch options: `create_report` is single-text only. */
+export type AIDetectBatchOptions = Omit<AIDetectOptions, 'create_report'>;
+
+export type AIDetectSentenceScore = {
+   sentence: string;
+   /** Same model, 0–1 scale and 0.5 threshold as the overall `score`. */
+   score: number;
+   /** Offsets into the response `text` (`end` exclusive), counted in Unicode
+    *  code points — slice with `Array.from(text)` if it may contain emoji. */
+   start: number;
+   end: number;
+}
+
+export type AIDetectLanguage = {
+   code: string;
+   /** English display name; null for codes without one. */
+   name: string | null;
+   confidence: number;
+}
+
+/** A run of consecutive sentences scoring >= 0.5. */
+export type AIDetectSegment = {
+   /** Offsets into the response `text` (`end` exclusive), in Unicode code points like
+    *  `AIDetectSentenceScore`. */
+   start: number;
+   end: number;
+   /** Mean score of the run's sentences, weighted by their length. */
+   score: number;
+}
+
+/** `short_text`: under 500 characters. `list_format`: mostly bullet or numbered lines. */
+export type AIDetectLowConfidenceReason = 'short_text' | 'list_format';
+
+export type AIDetectResponse = {
+   /** 0 (likely human-written) to 1 (likely AI-generated). */
+   score: number;
+   /** Share of the text in sentences scoring >= 0.5 (flags partially
+    *  AI-written documents); null when nothing could be scored. */
+   ai_fraction: number | null;
+   /** Plain-language summary of `score` and `ai_fraction`: `'ai'` when `ai_fraction` >= 0.8
+    *  and `score` >= 0.5; otherwise `'mixed'` when `ai_fraction` >= 0.2 or `score` >= 0.5;
+    *  otherwise `'human'` (with a null `ai_fraction`, `'ai'` or `'human'` by `score` alone).
+    *  Omitted when the text could not be scored. */
+   verdict?: 'human' | 'mixed' | 'ai';
+   /** The AI-scored passages, in text order; empty when no sentence scores >= 0.5. Also sent
+    *  with `sent_scores: false`; omitted when sentence offsets are unavailable. */
+   segments?: AIDetectSegment[];
+   /** True when the input is of a kind with a higher false-positive rate (see
+    *  `low_confidence_reasons`), so hedge the result rather than show a bare score. */
+   low_confidence: boolean;
+   /** Empty when `low_confidence` is false. */
+   low_confidence_reasons: AIDetectLowConfidenceReason[];
+   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
+    *  multilingual model; otherwise an opaque identifier of the default model — log it, don't
+    *  parse it. */
+   version: string;
+   /** Present unless `sent_scores: false`. */
+   sentence_scores?: AIDetectSentenceScore[];
+   /** Present when `score_string: true`. */
+   score_string?: string;
+   /** Advisory detected language; omitted unless detection is high-confidence. 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
+    *  reliable. */
+   language?: AIDetectLanguage;
+}
+
+/** The public report link minted by `create_report: true`. */
+export type AIDetectReport = {
+   /** AI detector history entry id (the report is listed in your dashboard history). */
+   id: string;
+   /** Public report link. */
+   url: string;
+   /** ISO 8601 timestamp. */
+   shared_at: string;
+   /** ISO 8601 timestamp: when the link stops resolving unless revoked or deleted sooner. */
+   expires_at: string;
+}
+
+/** Why `report` is null: `nonpersist` (team keeps no data), `disabled` (AI detector history
+ *  off), `text_not_retained` (history keeps no text), `unconfirmed_email`, `quota` (history
+ *  full), `unscorable`, `error`. */
+export type AIDetectReportSkipReason = 'nonpersist' | 'disabled' | 'text_not_retained'
+   | 'unconfirmed_email' | 'quota' | 'unscorable' | 'error';
+
+/** Added to single-text responses only when `create_report: true` was sent. */
+export type AIDetectReportFields = {
+   /** null when no report was made (see `report_skip_reason`). */
+   report?: AIDetectReport | null;
+   /** Present only when `report` is null. */
+   report_skip_reason?: AIDetectReportSkipReason;
+}
+
+/** fileAidetect() always scores with sentence scores and score_string enabled. */
+export type FileAIDetectResponse = AIDetectResponse
+   & Required<Pick<AIDetectResponse, 'sentence_scores' | 'score_string'>>
+   & AIDetectReportFields;
+
+export type URLAIDetectSource = {
+   /** Final URL after redirects. */
+   url: string;
+   /** The page's og:title, <title> or first <h1> (a linked document's file name); empty
+    *  when there is none. */
+   title: string;
+   /** The response's media type, e.g. `'text/html'` or `'application/pdf'`. */
+   content_type: string;
+   /** Characters scored (and billed). */
+   characters: number;
+   /** True when the page (2MB of HTML), document (15MB) or text (200,000 characters) was cut
+    *  off, so only a prefix was scored. */
+   truncated: boolean;
+}
+
+/** urlAidetect(): the aidetect() response plus where the scored text came from. */
+export type URLAIDetectResponse = AIDetectResponse & AIDetectReportFields & {
+   source: URLAIDetectSource;
+}
+
+export type AIDetectBatchResponse = {
+   results: AIDetectResponse[];
 }
 
 export type StyleguideRule = string | { name: string; description?: string };
@@ -136,6 +395,85 @@ export type AccountStatusResponse = {
    };
 }
 
+export type ReportingWindowOptions = {
+   /** Days before today the window starts (non-negative integer). */
+   start_days_back?: number,
+   /** Days before today the window ends (non-negative integer). Defaults to 0. */
+   end_days_back?: number,
+}
+
+export type ApiUsageKeySummary = {
+   /** Masked id, `****<last4>-<hash8>`; the raw key is never returned. */
+   api_key: string;
+   tag: string;
+   /** Characters in the window. */
+   characters: number;
+   /** Monthly character limit; -1 for none. */
+   monthly_limit: number | null;
+   /** Characters this calendar month. */
+   monthly_usage: number;
+   /** null when there is no limit. */
+   remaining_quota: number | null;
+   quota_exceeded: boolean;
+}
+
+export type ApiUsageResponse = {
+   /** Inclusive ISO dates of the resolved window. */
+   start_date: string;
+   end_date: string;
+   total_characters: number;
+   /** At list prices, per (endpoint, month). */
+   total_cost_usd: number;
+   currency: string;
+   /** Keyed by masked key id. */
+   by_api_key: Record<string, ApiUsageKeySummary>;
+   /** Keyed by endpoint name, e.g. `EDIT`. */
+   by_endpoint: Record<string, { characters: number; cost_usd: number }>;
+   /** Masked key id → `YYYY-MM-DD` → characters. */
+   daily_usage: Record<string, Record<string, number>>;
+   /** Masked key id → `YYYY-MM` → characters. */
+   monthly_usage: Record<string, Record<string, number>>;
+   /** ISO timestamp of the latest usage row in the window, or null. */
+   last_updated: string | null;
+   /** Omitted for team-scoped keys. Same object as accountStatus()'s `credits`. */
+   credit_balance_data?: AccountCreditSummary;
+}
+
+export type ApiEndpointUsageInterval = 'Daily' | 'Weekly' | 'Monthly';
+
+export type ApiEndpointUsageOptions = ReportingWindowOptions & {
+   /** Defaults to 'Daily'. */
+   interval?: ApiEndpointUsageInterval,
+}
+
+export type ApiEndpointUsageResponse = {
+   /** Endpoint name → bucket start (days before today, as a string key) → characters. */
+   data: Record<string, Record<string, number>>;
+   last_updated: string | null;
+}
+
+export type ApiQuotaUsageResponse = {
+   /** Monthly character limit; -1 for none. */
+   quota: number;
+   /** Characters in the window. */
+   usage: number;
+   /** Suggestions accepted / ignored via acceptEdit()/rejectEdit() since the first of the month. */
+   accepts: number;
+   ignores: number;
+   /** Unix epoch seconds. */
+   last_updated: number;
+}
+
+export type ApiUserActivityResponse = {
+   edits_shown: number;
+   edits_accepted: number;
+   edits_ignored: number;
+   active_users: {
+      logged_in: number;
+      anonymous: number;
+   };
+}
+
 export type SimplifyReadingLevel = 'plain' | 'elementary' | 'middle_school' | 'high_school';
 
 export type SimplifyOptions = {
@@ -168,6 +506,43 @@ export type LangdetectOptions = {
    segments?: boolean,
 }
 
+export type LangdetectCandidate = {
+   lang: string;
+   conf: number;
+   name: string | null;
+}
+
+export type LangdetectResult = {
+   /** ISO 639-1 code of the most likely language. */
+   lang: string;
+   conf: number;
+   name: string | null;
+   /** The recommended trust bar: true only when the confidence is high and the text has enough
+    *  letters. Short inputs like "OK" or "Hola" are never reliable. */
+   reliable: boolean;
+   /** Dominant writing system as an ISO 15924 code (`Latn`, `Cyrl`, `Arab`, `Hani`, `Jpan`,
+    *  `Hang`, ...). `Zzzz` when the letters are in an unmapped script; null when the text has no
+    *  letters. */
+   script: string | null;
+   /** The top_k most likely languages, best first. */
+   candidates: LangdetectCandidate[];
+}
+
+export type LangdetectSegment = LangdetectResult & {
+   start: number;
+   end: number;
+   text: string;
+}
+
+export type LangdetectResponse = LangdetectResult & {
+   /** Present only when the request sent segments: true. */
+   segments?: LangdetectSegment[];
+}
+
+export type LangdetectBatchResponse = {
+   results: LangdetectResponse[];
+}
+
 export type ClassifyLabel = string | { name: string; description?: string };
 
 export type ClassifyOptions = {
@@ -274,7 +649,12 @@ export type QualityBatchResponse = {
    results: QualityResponse[];
 }
 
-export type PIIType = 'email' | 'phone' | 'ssn' | 'credit_card' | 'ip_address' | 'iban' | 'us_bank_routing';
+export type PIIDeterministicType = 'email' | 'phone' | 'ssn' | 'credit_card' | 'ip_address' | 'iban' | 'us_bank_routing';
+// Opt-in, LLM-backed named-entity PII types: detected only when listed in
+// `types` explicitly (a request without them stays deterministic-only), and
+// the text is then capped at 10,000 characters rather than 20,000.
+export type PIINerType = 'person' | 'organization' | 'location';
+export type PIIType = PIIDeterministicType | PIINerType;
 
 export type PIIOptions = {
    types?: PIIType[],
@@ -319,6 +699,35 @@ export type NERBatchResponse = {
    results: NERResponse[];
 }
 
+export type InclusiveCategory = 'gender' | 'race_ethnicity' | 'disability' | 'age' |
+   'lgbtq' | 'religion' | 'socioeconomic' | 'appearance';
+
+export type InclusiveSeverity = 'low' | 'medium' | 'high';
+
+export type InclusiveOptions = {
+   categories?: InclusiveCategory[],
+}
+
+export type InclusiveIssue = {
+   category: InclusiveCategory;
+   severity: InclusiveSeverity;
+   text: string;
+   start: number | null;
+   end: number | null;
+   note: string;
+   suggestion: string;
+}
+
+export type InclusiveResponse = {
+   issues: InclusiveIssue[];
+   categories: InclusiveCategory[];
+   inclusive: boolean;
+}
+
+export type InclusiveBatchResponse = {
+   results: InclusiveResponse[];
+}
+
 export type SafetyCategory = 'toxicity' | 'profanity' | 'harassment' | 'hate_speech' |
    'self_harm' | 'sexual' | 'violence';
 
@@ -352,7 +761,9 @@ export type SpellcheckOptions = {
    multipleEdits?: boolean,
    lang?: string,
    autoApply?: boolean,
-   variety?: string,
+   /** English variety to enforce. The API rejects other values with a 400. */
+   variety?: EnglishVariety,
+   /** Arbitrary JSON echoed back as `user_data` on the response. */
    userData?: any,
 }
 
@@ -389,6 +800,36 @@ export type ExtractBatchResponse = {
    results: ExtractResponse[];
 }
 
+/** A document for fileAidetect()/fileExtract()/fileSummarize(): a Blob/File, or the file's bytes (Buffer,
+ *  Uint8Array, ArrayBuffer). The API picks the format by file extension (.pdf, .docx, .pptx,
+ *  .odt, .txt, .md, .html, .htm; up to 30MB), so bytes need `options.filename`. */
+export type UploadFile = Blob | ArrayBuffer | ArrayBufferView;
+
+export type FileUploadOptions = {
+   /** Required unless `file` is a File (whose own name is used otherwise), e.g. 'report.pdf'. */
+   filename?: string,
+}
+
+export type FileExtractOptions = ExtractOptions & FileUploadOptions;
+
+export type FileAIDetectOptions = FileUploadOptions & Pick<AIDetectOptions, 'zero_retention' | 'create_report'>;
+
+export type FileExtractDocument = {
+   /** The extension the document was read as, e.g. 'pdf'. */
+   file_type: string,
+   /** Characters of text extracted from the file. */
+   characters: number,
+   /** Characters read for extraction (at most 10,000) and billed. */
+   characters_used: number,
+   /** True when the text was cut to its first 10,000 characters; fields stated only
+    *  later in the document are reported missing. */
+   truncated: boolean,
+}
+
+export type FileExtractResponse = ExtractResponse & {
+   document: FileExtractDocument,
+}
+
 export type TranslateOptions = {
    source_lang?: string,
    formality?: 'formal' | 'informal',
@@ -422,6 +863,196 @@ export type SummarizeBatchResponse = {
    results: SummarizeResponse[];
 }
 
+export type FileSummarizeOptions = SummarizeOptions & FileUploadOptions;
+
+export type FileSummarizeDocument = {
+   /** The extension the document was read as, e.g. 'pdf'. */
+   file_type: string,
+   /** Characters of text extracted from the file. */
+   characters: number,
+   /** Characters summarized (at most 20,000) and billed. */
+   characters_used: number,
+   /** True when the text was cut to its first 20,000 characters; the summary covers
+    *  only that part of the document. */
+   truncated: boolean,
+}
+
+export type FileSummarizeResponse = SummarizeResponse & {
+   document: FileSummarizeDocument,
+}
+
+export type RephraseMapping =
+   'paraphrase' | 'passive_to_active' | 'active_to_passive' | 'informal_to_formal' |
+   'formal_to_informal' | 'sentence_split' | 'reword' | 'generate_title' | 'generate_acronym' |
+   'generate_meta_description' | 'summarize' | 'expand' | 'shorten' | 'switch_tone' | 'switch_tense';
+
+export type RephraseToneMapping =
+   'straightforward' | 'confident' | 'friendly' | 'empathetic' | 'professional' | 'casual' |
+   'diplomatic' | 'persuasive';
+
+export type RephraseTenseMapping =
+   'simple past' | 'past perfect' | 'past continuous' | 'past perfect continuous' |
+   'simple present' | 'present perfect' | 'present continuous' | 'present perfect continuous' |
+   'simple future' | 'future perfect' | 'future continuous' | 'future perfect continuous';
+
+export type RephraseOptions = {
+   /** Defaults to 'paraphrase'. */
+   mapping?: RephraseMapping,
+   /** Only used with mapping 'switch_tone'. Defaults to 'straightforward'. */
+   tone_mapping?: RephraseToneMapping,
+   /** Only used with mapping 'switch_tense'. Defaults to 'simple past'. */
+   tense_mapping?: RephraseTenseMapping,
+   /** Number of alternatives, 1-8 (default 5). Honored by paraphrase, informal_to_formal,
+    *  formal_to_informal, generate_title and generate_acronym. */
+   num_results?: number,
+   session_id?: string,
+}
+
+export type RephraseResult = {
+   hash: string,
+   original: string,
+   replacement: string,
+   rephrase_type: RephraseMapping,
+   model_version: string,
+}
+
+export type RephraseResponse = {
+   results: RephraseResult[],
+}
+
+export type CompleteResponse = {
+   /** The predicted continuation of `query`. */
+   output: string,
+   /** The part of the sent query the prediction continues: the API keeps only the text
+    *  after the last run of three spaces. */
+   query: string,
+   /** Pass to acceptComplete() as `completeUUID`, with this `query` and `output`. */
+   hash: string,
+}
+
+export type AcceptCompleteResponse = {
+   result: 'success',
+}
+
+/** [probability, tone name, emoji] triples, e.g. [1.0, 'neutral', '😐']. */
+export type ToneScores = Array<[number, string, string]>;
+
+export type ToneResponse = {
+   /** Up to 3 tones for the whole text, most likely first; the probabilities sum to 1. */
+   overall: ToneScores,
+   /** One entry per sentence, aligned with `sents`. */
+   results: ToneScores[],
+   sents: string[],
+}
+
+export type SentimentLabel = 'POSITIVE' | 'NEUTRAL' | 'NEGATIVE';
+
+/** [probability, label] pairs, most likely first. */
+export type SentimentScores = Array<[number, SentimentLabel]>;
+
+export type SentimentResponse = {
+   overall: SentimentScores,
+   /** One entry per sentence, aligned with `sents`. */
+   results: SentimentScores[],
+   sents: string[],
+}
+
+export type StatisticsLang = 'en' | 'de' | 'es' | 'fr' | 'it' | 'nl' | 'pl' | 'ru' | 'ar' | 'auto';
+
+export type StatisticsOptions = {
+   /** Defaults to 'en'. */
+   lang?: StatisticsLang,
+}
+
+export type StatisticsResponse = {
+   chars: number,
+   words: number,
+   sentences: number,
+   reading_time_sec: number,
+   reading_time_min: number,
+   /** Flesch-Kincaid grade level; -3.4 when the text cannot be scored. */
+   readability: number,
+   /** Formula name -> score. The formulas present depend on `lang`; empty for 'auto'.
+    *  `text_standard` is a string (e.g. "8th and 9th grade"). */
+   readability_scores: Record<string, number | string>,
+}
+
+export type SimilarTermsResponse = {
+   /** Up to 5 [similarity, term] pairs (similarity 0-1), most similar first. */
+   neighbors: Array<[number, string]>,
+   /** WordNet lemma names; multi-word ones use underscores (e.g. "domestic_dog"). */
+   synonyms: string[],
+}
+
+export type ProfanityResponse = {
+   /** The text split on whitespace (punctuation stays attached). */
+   toks: string[],
+   /** Aligned with `toks`: 1 for profanity, 0 otherwise. */
+   labels: Array<0 | 1>,
+}
+
+export type DictionaryEntry = {
+   id: string,
+   entry: string,
+   case_sensitive: boolean,
+   /** RFC 1123 timestamp, e.g. "Wed, 07 Oct 2020 21:15:47 GMT". */
+   created_at: string,
+   updated_at: string,
+}
+
+export type AddDictionaryEntryOptions = {
+   /** Defaults to true. */
+   case_sensitive?: boolean,
+}
+
+export type CustomMapping = {
+   id: string,
+   /** The text to match; `^` / `$` anchor to a sentence's start / end, `#` matches a number. */
+   entry: string,
+   /** The replacement suggested; a `#` substitutes the matched number back in. */
+   mapping: string,
+   /** Shown with the suggestion; empty string or null (older rules) when none was set. */
+   description: string | null,
+   case_sensitive: boolean,
+   /** RFC 1123 timestamp, e.g. "Wed, 07 Oct 2020 21:15:47 GMT". */
+   created_at: string,
+   updated_at: string,
+}
+
+export type CustomMappingsResponse = {
+   /** Sorted by entry. */
+   custom_mappings: CustomMapping[],
+}
+
+export type AddCustomMappingOptions = {
+   /** Shown to the end user with the suggestion; a mapping with a description cannot be ignored. */
+   description?: string,
+   /** Defaults to true. */
+   case_sensitive?: boolean,
+}
+
+export type CustomFilter = {
+   id: string,
+   /** The original text of the suppressed edits; empty string is a wildcard. */
+   input: string,
+   /** The replacement text of the suppressed edits; empty string is a wildcard. */
+   output: string,
+   case_sensitive: boolean,
+   /** RFC 1123 timestamp, e.g. "Wed, 07 Oct 2020 21:15:47 GMT". */
+   created_at: string,
+   updated_at: string,
+}
+
+export type CustomFiltersResponse = {
+   /** Sorted by input. */
+   custom_filters: CustomFilter[],
+}
+
+export type AddCustomFilterOptions = {
+   /** Defaults to true. */
+   case_sensitive?: boolean,
+}
+
 export type UserDetails = {
    userId?: string,
    anonUser?: boolean,
@@ -430,49 +1061,91 @@ export type UserDetails = {
 export declare class Client {
    constructor(apiKey: string, options?: ConstructorOptions);
 
-   edits(text: string, sessionId?: string, options?: EditOptions, userDetails?: UserDetails): Promise<AxiosResponse>;
+   edits(text: string, sessionId?: string, options?: EditOptions, userDetails?: UserDetails): Promise<AxiosResponse<WithUsage<EditsResponse>>>;
    acceptEdit(editUUID: string, sessionId?: string, userId?: string): Promise<AxiosResponse>;
    rejectEdit(editUUID: string, sessionId?: string, userId?: string): Promise<AxiosResponse>;
 
-   spellcheck(text: string, sessionId?: string, options?: SpellcheckOptions, userDetails?: UserDetails): Promise<AxiosResponse>;
-
-   complete(query: string, sessionId?: string): Promise<AxiosResponse>;
-   acceptComplete(completeUUID: string, query: string, completion: string, sessionId?: string): Promise<AxiosResponse>;
-   tone(text: string): Promise<AxiosResponse>;
-   extract(text: string, fields: ExtractField[], options?: ExtractOptions): Promise<AxiosResponse<ExtractResponse>>;
-   extract(texts: string[], fields: ExtractField[], options?: ExtractOptions): Promise<AxiosResponse<ExtractBatchResponse>>;
-   extract(text: string | string[], fields: ExtractField[], options?: ExtractOptions): Promise<AxiosResponse<ExtractResponse | ExtractBatchResponse>>;
-   translate(text: string, targetLang: string, options?: TranslateOptions): Promise<AxiosResponse<TranslateResponse>>;
-   translate(texts: string[], targetLang: string, options?: TranslateOptions): Promise<AxiosResponse<TranslateBatchResponse>>;
-   translate(text: string | string[], targetLang: string, options?: TranslateOptions): Promise<AxiosResponse<TranslateResponse | TranslateBatchResponse>>;
-   summarize(text: string, options?: SummarizeOptions): Promise<AxiosResponse<SummarizeResponse>>;
-   summarize(texts: string[], options?: SummarizeOptions): Promise<AxiosResponse<SummarizeBatchResponse>>;
-   summarize(text: string | string[], options?: SummarizeOptions): Promise<AxiosResponse<SummarizeResponse | SummarizeBatchResponse>>;
-
-   aidetect(text: string | string[], options?: AIDetectOptions): Promise<AxiosResponse>;
-   styleguide(text: string, rules: StyleguideRule[] | string): Promise<AxiosResponse<StyleguideResponse>>;
-   styleguide(texts: string[], rules: StyleguideRule[] | string): Promise<AxiosResponse<StyleguideBatchResponse>>;
-   styleguide(text: string | string[], rules: StyleguideRule[] | string): Promise<AxiosResponse<StyleguideResponse | StyleguideBatchResponse>>;
-   styleguideRulesets(): Promise<AxiosResponse<StyleguideRulesetsResponse>>;
-   saveStyleguideRuleset(name: string, rules: StyleguideRule[]): Promise<AxiosResponse<SaveStyleguideRulesetResponse>>;
-   deleteStyleguideRuleset(name: string): Promise<AxiosResponse<DeleteStyleguideRulesetResponse>>;
-   simplify(text: string, options?: SimplifyOptions): Promise<AxiosResponse<SimplifyResponse>>;
-   simplify(texts: string[], options?: SimplifyOptions): Promise<AxiosResponse<SimplifyBatchResponse>>;
-   simplify(text: string | string[], options?: SimplifyOptions): Promise<AxiosResponse<SimplifyResponse | SimplifyBatchResponse>>;
-   langdetect(text: string | string[], options?: LangdetectOptions): Promise<AxiosResponse>;
-   quality(text: string, options?: QualityOptions): Promise<AxiosResponse<QualityResponse>>;
-   quality(texts: string[], options?: QualityOptions): Promise<AxiosResponse<QualityBatchResponse>>;
-   quality(text: string | string[], options?: QualityOptions): Promise<AxiosResponse<QualityResponse | QualityBatchResponse>>;
-   pii(text: string, options?: PIIOptions): Promise<AxiosResponse<PIIResponse>>;
-   ner(text: string, options?: NEROptions): Promise<AxiosResponse<NERResponse>>;
-   ner(texts: string[], options?: NEROptions): Promise<AxiosResponse<NERBatchResponse>>;
-   ner(text: string | string[], options?: NEROptions): Promise<AxiosResponse<NERResponse | NERBatchResponse>>;
-   safety(text: string, options?: SafetyOptions): Promise<AxiosResponse<SafetyResponse>>;
-   safety(texts: string[], options?: SafetyOptions): Promise<AxiosResponse<SafetyBatchResponse>>;
-   safety(text: string | string[], options?: SafetyOptions): Promise<AxiosResponse<SafetyResponse | SafetyBatchResponse>>;
-   classify(text: string, labels: ClassifyLabel[], options?: ClassifyOptions): Promise<AxiosResponse<ClassifyResponse>>;
-   classify(texts: string[], labels: ClassifyLabel[], options?: ClassifyOptions): Promise<AxiosResponse<ClassifyBatchResponse>>;
-   classify(text: string | string[], labels: ClassifyLabel[], options?: ClassifyOptions): Promise<AxiosResponse<ClassifyResponse | ClassifyBatchResponse>>;
-   seo(text: string, options?: SeoOptions): Promise<AxiosResponse<SeoResponse>>;
+   spellcheck(text: string, sessionId?: string, options?: SpellcheckOptions, userDetails?: UserDetails): Promise<AxiosResponse<WithUsage<SpellcheckResponse>>>;
+
+   /** `data` is `[]` when no completion is available (the prediction failed or was too
+    *  short). Check `Array.isArray(data)` before reading fields. */
+   complete(query: string, sessionId?: string): Promise<AxiosResponse<WithUsage<CompleteResponse> | never[]>>;
+   /** Pass the `hash`, `query` and `output` that complete() returned. A changed `query` or
+    *  `completion` gets a 400 ("Arguments do not match hash."). */
+   acceptComplete(completeUUID: string, query: string, completion: string, sessionId?: string): Promise<AxiosResponse<WithUsage<AcceptCompleteResponse>>>;
+   /** `data` is `[]` when the API cannot split the text into sentences. Check
+    *  `Array.isArray(data)` before reading fields. */
+   tone(text: string): Promise<AxiosResponse<WithUsage<ToneResponse> | never[]>>;
+   rephrase(text: string, options?: RephraseOptions): Promise<AxiosResponse<WithUsage<RephraseResponse>>>;
+   /** A text with no sentences (e.g. markup or punctuation only) gets a 204 with an empty
+    *  body, so `data` is `''` then; a text the API cannot split into sentences gets a 200
+    *  with `[]`. Check `Array.isArray(data) || !data` before reading fields. */
+   sentiment(text: string): Promise<AxiosResponse<WithUsage<SentimentResponse> | '' | never[]>>;
+   statistics(text: string, options?: StatisticsOptions): Promise<AxiosResponse<WithUsage<StatisticsResponse>>>;
+   similarTerms(query: string): Promise<AxiosResponse<WithUsage<SimilarTermsResponse>>>;
+   profanity(text: string): Promise<AxiosResponse<WithUsage<ProfanityResponse>>>;
+   dictionaryEntries(): Promise<AxiosResponse<DictionaryEntry[]>>;
+   addDictionaryEntry(entry: string, options?: AddDictionaryEntryOptions): Promise<AxiosResponse<WithUsage<DictionaryEntry>>>;
+   /** Answers 204 with an empty body. */
+   deleteDictionaryEntry(entryId: string): Promise<AxiosResponse<''>>;
+   customMappings(): Promise<AxiosResponse<WithUsage<CustomMappingsResponse>>>;
+   addCustomMapping(entry: string, mapping: string, options?: AddCustomMappingOptions): Promise<AxiosResponse<WithUsage<CustomMapping>>>;
+   /** Answers 204 with an empty body. */
+   deleteCustomMapping(mappingId: string): Promise<AxiosResponse<''>>;
+   customFilters(): Promise<AxiosResponse<WithUsage<CustomFiltersResponse>>>;
+   addCustomFilter(input: string, output: string, options?: AddCustomFilterOptions): Promise<AxiosResponse<WithUsage<CustomFilter>>>;
+   /** Answers 204 with an empty body. */
+   deleteCustomFilter(filterId: string): Promise<AxiosResponse<''>>;
+   extract(text: string, fields: ExtractField[], options?: ExtractOptions): Promise<AxiosResponse<WithUsage<ExtractResponse>>>;
+   extract(texts: string[], fields: ExtractField[], options?: ExtractOptions): Promise<AxiosResponse<WithUsage<ExtractBatchResponse>>>;
+   extract(text: string | string[], fields: ExtractField[], options?: ExtractOptions): Promise<AxiosResponse<WithUsage<ExtractResponse | ExtractBatchResponse>>>;
+   fileExtract(file: UploadFile, fields: ExtractField[], options?: FileExtractOptions): Promise<AxiosResponse<WithUsage<FileExtractResponse>>>;
+   translate(text: string, targetLang: string, options?: TranslateOptions): Promise<AxiosResponse<WithUsage<TranslateResponse>>>;
+   translate(texts: string[], targetLang: string, options?: TranslateOptions): Promise<AxiosResponse<WithUsage<TranslateBatchResponse>>>;
+   translate(text: string | string[], targetLang: string, options?: TranslateOptions): Promise<AxiosResponse<WithUsage<TranslateResponse | TranslateBatchResponse>>>;
+   summarize(text: string, options?: SummarizeOptions): Promise<AxiosResponse<WithUsage<SummarizeResponse>>>;
+   summarize(texts: string[], options?: SummarizeOptions): Promise<AxiosResponse<WithUsage<SummarizeBatchResponse>>>;
+   summarize(text: string | string[], options?: SummarizeOptions): Promise<AxiosResponse<WithUsage<SummarizeResponse | SummarizeBatchResponse>>>;
+   fileSummarize(file: UploadFile, options?: FileSummarizeOptions): Promise<AxiosResponse<WithUsage<FileSummarizeResponse>>>;
+
+   aidetect(text: string, options?: AIDetectOptions): Promise<AxiosResponse<WithUsage<AIDetectResponse & AIDetectReportFields>>>;
+   aidetect(texts: string[], options?: AIDetectBatchOptions): Promise<AxiosResponse<WithUsage<AIDetectBatchResponse>>>;
+   aidetect(text: string | string[], options?: AIDetectBatchOptions): Promise<AxiosResponse<WithUsage<AIDetectResponse | AIDetectBatchResponse>>>;
+   fileAidetect(file: UploadFile, options?: FileAIDetectOptions): Promise<AxiosResponse<WithUsage<FileAIDetectResponse>>>;
+   urlAidetect(url: string, options?: AIDetectOptions): Promise<AxiosResponse<WithUsage<URLAIDetectResponse>>>;
+   styleguide(text: string, rules: StyleguideRule[] | string): Promise<AxiosResponse<WithUsage<StyleguideResponse>>>;
+   styleguide(texts: string[], rules: StyleguideRule[] | string): Promise<AxiosResponse<WithUsage<StyleguideBatchResponse>>>;
+   styleguide(text: string | string[], rules: StyleguideRule[] | string): Promise<AxiosResponse<WithUsage<StyleguideResponse | StyleguideBatchResponse>>>;
+   styleguideRulesets(): Promise<AxiosResponse<WithUsage<StyleguideRulesetsResponse>>>;
+   saveStyleguideRuleset(name: string, rules: StyleguideRule[]): Promise<AxiosResponse<WithUsage<SaveStyleguideRulesetResponse>>>;
+   deleteStyleguideRuleset(name: string): Promise<AxiosResponse<WithUsage<DeleteStyleguideRulesetResponse>>>;
+   simplify(text: string, options?: SimplifyOptions): Promise<AxiosResponse<WithUsage<SimplifyResponse>>>;
+   simplify(texts: string[], options?: SimplifyOptions): Promise<AxiosResponse<WithUsage<SimplifyBatchResponse>>>;
+   simplify(text: string | string[], options?: SimplifyOptions): Promise<AxiosResponse<WithUsage<SimplifyResponse | SimplifyBatchResponse>>>;
+   langdetect(text: string, options?: LangdetectOptions): Promise<AxiosResponse<WithUsage<LangdetectResponse>>>;
+   langdetect(texts: string[], options?: LangdetectOptions): Promise<AxiosResponse<WithUsage<LangdetectBatchResponse>>>;
+   langdetect(text: string | string[], options?: LangdetectOptions): Promise<AxiosResponse<WithUsage<LangdetectResponse | LangdetectBatchResponse>>>;
+   quality(text: string, options?: QualityOptions): Promise<AxiosResponse<WithUsage<QualityResponse>>>;
+   quality(texts: string[], options?: QualityOptions): Promise<AxiosResponse<WithUsage<QualityBatchResponse>>>;
+   quality(text: string | string[], options?: QualityOptions): Promise<AxiosResponse<WithUsage<QualityResponse | QualityBatchResponse>>>;
+   pii(text: string, options?: PIIOptions): Promise<AxiosResponse<WithUsage<PIIResponse>>>;
+   ner(text: string, options?: NEROptions): Promise<AxiosResponse<WithUsage<NERResponse>>>;
+   ner(texts: string[], options?: NEROptions): Promise<AxiosResponse<WithUsage<NERBatchResponse>>>;
+   ner(text: string | string[], options?: NEROptions): Promise<AxiosResponse<WithUsage<NERResponse | NERBatchResponse>>>;
+   inclusive(text: string, options?: InclusiveOptions): Promise<AxiosResponse<WithUsage<InclusiveResponse>>>;
+   inclusive(texts: string[], options?: InclusiveOptions): Promise<AxiosResponse<WithUsage<InclusiveBatchResponse>>>;
+   inclusive(text: string | string[], options?: InclusiveOptions): Promise<AxiosResponse<WithUsage<InclusiveResponse | InclusiveBatchResponse>>>;
+   safety(text: string, options?: SafetyOptions): Promise<AxiosResponse<WithUsage<SafetyResponse>>>;
+   safety(texts: string[], options?: SafetyOptions): Promise<AxiosResponse<WithUsage<SafetyBatchResponse>>>;
+   safety(text: string | string[], options?: SafetyOptions): Promise<AxiosResponse<WithUsage<SafetyResponse | SafetyBatchResponse>>>;
+   classify(text: string, labels: ClassifyLabel[], options?: ClassifyOptions): Promise<AxiosResponse<WithUsage<ClassifyResponse>>>;
+   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>>>;
    accountStatus(): Promise<AxiosResponse<AccountStatusResponse>>;
+   apiUsage(options?: ReportingWindowOptions): Promise<AxiosResponse<WithUsage<ApiUsageResponse>>>;
+   apiEndpointUsage(options?: ApiEndpointUsageOptions): Promise<AxiosResponse<WithUsage<ApiEndpointUsageResponse>>>;
+   /** Not WithUsage<>: the response's own `usage` is an integer and return_usage is not sent. */
+   apiQuotaUsage(options?: ReportingWindowOptions): Promise<AxiosResponse<ApiQuotaUsageResponse>>;
+   apiUserActivity(options?: ReportingWindowOptions): Promise<AxiosResponse<WithUsage<ApiUserActivityResponse>>>;
 }