@saplingai/sapling-js 1.0.39 → 1.0.52

package/README.md

@@ -76,6 +76,56 @@ You should see something like the following output:
 }
 ```
 
+If you only need to apply the corrections, pass `includeErrorCategories: false`. The API then
+skips error classification (faster and lighter), and each edit comes back without
+`error_type`, `general_error_type` or classifier-generated descriptions:
+
+```javascript
+client.edits('I have a apple!', undefined, { includeErrorCategories: false, autoApply: true })
+```
+
+### Text classification
+
+Zero-shot classification with your own labels (plain names or `{ name, description }` objects, 2–20):
+
+```javascript
+client
+  .classify(
+    'I was charged twice and the app crashes on launch.',
+    ['billing', { name: 'technical issue', description: 'Bugs, crashes, errors.' }, 'other'],
+    { multiLabel: true, threshold: 0.5, context: 'Support tickets for a SaaS billing product' },
+  )
+  .then(function (response) {
+    console.log(response.data);
+    // { label: 'billing', labels: ['billing', 'technical issue'],
+    //   scores: [{ label: 'billing', score: 0.92 }, ...], rationale: '...', multi_label: true }
+  })
+```
+
+### Style-guide rulesets
+
+Check text against style rules inline, or save a named ruleset once (owned by
+your API key's account — its team, for team-scoped keys) and check against it
+by name:
+
+```javascript
+// Define the house style once…
+await client.saveStyleguideRuleset('House Style', [
+  'no exclamation marks',
+  { name: 'no jargon', description: 'No corporate buzzwords or filler.' },
+]);
+
+// …then check against it by name (names match case-insensitively).
+const response = await client.styleguide('Our synergy-driven solution!!', 'House Style');
+console.log(response.data);
+// { violations: [{ rule: 'no jargon', text: 'synergy-driven solution', ... }],
+//   rules: ['no exclamation marks', 'no jargon'], compliant: false }
+
+// List and delete:
+await client.styleguideRulesets();          // { rulesets: [{ name, rules, ... }] }
+await client.deleteStyleguideRuleset('House Style');
+```
+
 ## Frontend Quickstart
 
 The SDK provides a way to automatically apply edit suggestions to any HTML contenteditable and textarea elements.
@@ -108,8 +158,109 @@ function App() {
 }
 ```
 
+## Structured Data Extraction
+
+Pull caller-named fields out of unstructured text — invoices, emails, resumes, support tickets.
+Pass 1–20 fields (plain names, or `{ name, type, description, required }` objects):
+
+```javascript
+client
+  .extract(
+    'Invoice INV-1042 for Acme Corp, total $1,299.00, due March 5, 2026.',
+    [
+      'invoice_number',
+      { name: 'total', type: 'number', description: 'Amount due', required: true },
+      { name: 'due_date', type: 'date' },
+      'purchase_order',
+    ],
+    { context: 'A vendor invoice' },
+  )
+  .then(function (response) {
+    console.log(response.data);
+    // { data: { invoice_number: 'INV-1042', total: 1299.0, due_date: '2026-03-05', purchase_order: null },
+    //   fields: [{ name: 'invoice_number', type: 'string', value: 'INV-1042',
+    //              evidence: 'Invoice INV-1042', found: true }, ...],
+    //   missing: ['purchase_order'] }
+  })
+```
+
+`data` always contains every field you asked for, `null` where the text didn't state it, and each
+entry in `fields` carries the verbatim `evidence` span its value came from. Values are coerced to
+the declared `type` (`'string'` (default), `'number'`, `'integer'`, `'boolean'`, `'date'` returned
+as `YYYY-MM-DD`, or `'list'`), and every value must be grounded in a quote from the text — this is
+extraction, not inference, so a value that isn't stated is reported in `missing` rather than
+guessed.
+
+## Translation
+
+Translate text into a target language, named by ISO 639 code (`'fr'`, `'zh-TW'`) or English
+name (`'French'`). Line breaks and markup are preserved, and the detected source language is
+reported alongside the translation:
+
+```javascript
+client
+  .translate('Hello world.\nSee you at 5pm.', 'fr', { formality: 'formal' })
+  .then(function (response) {
+    console.log(response.data);
+    // { translation: 'Bonjour le monde.\nÀ 17h.',
+    //   source_lang: 'en', source_lang_name: 'English',
+    //   target_lang: 'fr', target_lang_name: 'French' }
+  })
+```
+
+Region variants `zh-CN`/`zh-TW`/`zh-HK`, `pt-BR`/`pt-PT`, `en-GB`/`en-US`, `fr-CA` and
+`es-419` are supported as targets; the optional `source_lang` hint never overrides what the
+text actually is, and `formality` (`'formal'`/`'informal'`) picks the register where the
+target language distinguishes them.
+
 ## 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).
+- JavaScript, HTML, and Python [starter code](https://github.com/saplingai/sapling-samples).
+
+## Error handling
+
+Every client method returns the axios promise, so API errors (a `400` for
+over-limit input, `401` for a bad key, `429` for rate limits, network errors and
+timeouts) **reject** with the [axios error](https://axios-http.com/docs/handling_errors);
+inspect `error.response.status` / `error.response.data`:
+
+```javascript
+try {
+  const response = await client.edits(text);
+} catch (error) {
+  console.error(error.response?.status, error.response?.data ?? error.message);
+}
+```
+
+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
+[Rate Limits & Errors](https://sapling.ai/docs/rate_limits/).
+
+To find out why a key is blocked, and for how long, call `accountStatus()`. It
+is unbilled and works while the key is blocked. It reports account-wide blocks:
+an expired key or subscription, depleted credits, a billing limit, the trial
+daily allowance or the monthly quota. It does not report a single endpoint's
+short-term rate limit, because each endpoint has its own allowance. For a
+`Capacity used.` 429, use that response's `retry_after` instead:
+
+```javascript
+const { data } = await client.accountStatus();
+if (!data.api_access) {
+  // blocked_reason: key_expired | subscription_expired | credits_depleted |
+  //   monthly_billing_limit | trial_daily_limit | monthly_quota_exhausted
+  const retry = data.retry_after ? `, retry in ${data.retry_after}s` : '';
+  console.log(`${data.blocked_reason}: ${data.message}${retry}`);
+}
+```
+
+Every response includes `api_access`, `blocked_reason`, `message` and
+`usage.monthly_quota_chars`. Keys that aren't team-scoped also get the
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saplingai/sapling-js",
-  "version": "1.0.39",
+  "version": "1.0.52",
   "description": "JavaScript library for using the Sapling.ai API.",
   "type": "module",
   "main": "./sapling/client.js",
@@ -29,7 +29,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/client.test.js test/pack.test.js",
+    "test": "node --test test/client.test.js test/errors.test.js test/pack.test.js",
     "prepublishOnly": "npm test"
   },
   "dependencies": {

package/sapling/client.d.ts

@@ -32,17 +32,321 @@ export type EditOptions = {
    lang?: string,
    medical?: boolean,
    advancedEdits?: AdvancedEditOptions,
+   /** Defaults to true. false skips error classification: edits omit error_type,
+    *  general_error_type and classifier-generated descriptions. */
+   includeErrorCategories?: boolean,
 }
 
 export type AIDetectOptions = {
    sent_scores?: boolean,
 }
 
+export type StyleguideRule = string | { name: string; description?: string };
+
+export type StyleguideViolation = {
+   rule: string;
+   text: string;
+   start: number | null;
+   end: number | null;
+   note: string;
+   suggestion: string;
+}
+
+export type StyleguideResponse = {
+   violations: StyleguideViolation[];
+   rules: string[];
+   compliant: boolean;
+}
+
+export type StyleguideBatchResponse = {
+   results: StyleguideResponse[];
+}
+
+export type StyleguideRuleset = {
+   name: string;
+   rules: { name: string; description: string }[];
+   created_at: string | null;
+   updated_at: string | null;
+}
+
+export type StyleguideRulesetsResponse = {
+   rulesets: StyleguideRuleset[];
+}
+
+export type SaveStyleguideRulesetResponse = {
+   ruleset: StyleguideRuleset;
+   created: boolean;
+}
+
+export type DeleteStyleguideRulesetResponse = {
+   deleted: string;
+}
+
+export type AccountBlockedReason =
+   | 'key_expired'
+   | 'subscription_expired'
+   | 'credits_depleted'
+   | 'monthly_billing_limit'
+   | 'trial_daily_limit'
+   | 'monthly_quota_exhausted';
+
+export type AccountCreditSummary = {
+   enabled: boolean;
+   currency: string;
+   alert_threshold_percent: number;
+   // Present only when `enabled` is true.
+   balance_credits?: number;
+   purchased_credits?: number;
+   consumed_credits?: number;
+   consumed_percent?: number;
+   low_balance?: boolean;
+   depleted?: boolean;
+   billing_mode?: string;
+   billing_mode_effective_at?: string | null;
+   metered_fallback_available?: boolean;
+   stops_when_depleted?: boolean;
+   billing_started_at?: string;
+   auto_topup?: { enabled: boolean; [field: string]: unknown };
+   [field: string]: unknown;
+}
+
+export type AccountStatusResponse = {
+   api_access: boolean;
+   blocked_reason: AccountBlockedReason | null;
+   message: string | null;
+   // Seconds until the block may clear; present only when blocked.
+   retry_after?: number;
+   usage: {
+      monthly_quota_chars: number | null;
+      // Omitted for team-scoped keys, like `subscription`, `credits` and `trial`.
+      month_start?: string;
+      chars_this_month?: number;
+   };
+   subscription?: {
+      active: boolean;
+      trial_only: boolean;
+      key_expired: boolean;
+   };
+   credits?: AccountCreditSummary;
+   // Present only for free-trial accounts.
+   trial?: {
+      daily_limit_chars: number | null;
+      chars_used_today: number;
+      resets_at: 'utc_midnight';
+   };
+}
+
+export type SimplifyReadingLevel = 'plain' | 'elementary' | 'middle_school' | 'high_school';
+
+export type SimplifyOptions = {
+   reading_level?: SimplifyReadingLevel,
+   preserve_terms?: string[],
+   lang?: string,
+}
+
+export type SimplifyReadabilityScores = {
+   grade: number;
+   ease: number;
+}
+
+export type SimplifyResponse = {
+   simplified: string;
+   reading_level: SimplifyReadingLevel;
+   lang: string;
+   readability?: {
+      before: SimplifyReadabilityScores;
+      after: SimplifyReadabilityScores;
+   };
+}
+
+export type SimplifyBatchResponse = {
+   results: SimplifyResponse[];
+}
+
 export type LangdetectOptions = {
    top_k?: number,
    segments?: boolean,
 }
 
+export type ClassifyLabel = string | { name: string; description?: string };
+
+export type ClassifyOptions = {
+   multiLabel?: boolean,
+   threshold?: number,
+   context?: string,
+}
+
+export type ClassifyResponse = {
+   label: string;
+   labels: string[];
+   scores: { label: string; score: number }[];
+   rationale: string;
+   multi_label: boolean;
+}
+
+export type ClassifyBatchResponse = {
+   results: ClassifyResponse[];
+}
+
+export type SeoOptions = {
+   keywords?: string[],
+   suggestions?: boolean,
+   lang?: string,
+}
+
+export type SeoStats = {
+   chars: number;
+   words: number;
+   sentences: number;
+   paragraphs: number;
+   reading_time_min: number;
+   flesch_reading_ease: number | null;
+   flesch_kincaid_grade: number | null;
+}
+
+export type SeoKeyword = {
+   keyword: string;
+   count: number;
+   density: number;
+   in_first_100_words: boolean;
+}
+
+export type SeoTopTerm = {
+   term: string;
+   count: number;
+}
+
+export type SeoSuggestions = {
+   titles: string[];
+   meta_descriptions: string[];
+   slug: string | null;
+   keywords: string[];
+}
+
+export type SeoResponse = {
+   stats: SeoStats;
+   keywords: SeoKeyword[];
+   top_terms: SeoTopTerm[];
+   suggestions?: SeoSuggestions;
+}
+
+export type QualityOptions = {
+   sentence_scores?: boolean,
+   rubric?: boolean,
+}
+
+export type QualitySentenceScore = {
+   start: number;
+   end: number;
+   text: string;
+   score: number;
+}
+
+export type QualityRubricIssue = {
+   quote: string;
+   dimension: string;
+   note: string;
+   suggestion: string;
+   start: number;
+   end: number;
+}
+
+export type QualityRubric = {
+   overall: number;
+   dimensions: {
+      clarity: number;
+      coherence: number;
+      correctness: number;
+      concision: number;
+   };
+   summary: string;
+   issues: QualityRubricIssue[];
+}
+
+export type QualityResponse = {
+   score: number;
+   sentences?: QualitySentenceScore[];
+   truncated?: boolean;
+   rubric?: QualityRubric;
+}
+
+export type QualityBatchResponse = {
+   results: QualityResponse[];
+}
+
+export type PIIType = 'email' | 'phone' | 'ssn' | 'credit_card' | 'ip_address' | 'iban' | 'us_bank_routing';
+
+export type PIIOptions = {
+   types?: PIIType[],
+   redact?: boolean,
+}
+
+export type PIIEntity = {
+   type: PIIType;
+   text: string;
+   start: number;
+   end: number;
+   replacement: string;
+}
+
+export type PIIResponse = {
+   entities: PIIEntity[];
+   flagged: boolean;
+   types: PIIType[];
+   redacted_text?: string;
+}
+
+export type NERType = 'person' | 'organization' | 'location' | 'date' | 'time' |
+   'money' | 'percent' | 'quantity' | 'product' | 'event';
+
+export type NEROptions = {
+   types?: NERType[],
+}
+
+export type NEREntity = {
+   text: string;
+   type: NERType;
+   start: number;
+   end: number;
+}
+
+export type NERResponse = {
+   entities: NEREntity[];
+   types: NERType[];
+}
+
+export type NERBatchResponse = {
+   results: NERResponse[];
+}
+
+export type SafetyCategory = 'toxicity' | 'profanity' | 'harassment' | 'hate_speech' |
+   'self_harm' | 'sexual' | 'violence';
+
+export type SafetySpan = {
+   text: string;
+   start: number | null;
+   end: number | null;
+   scores: Partial<Record<SafetyCategory, number>>;
+   flagged_categories: SafetyCategory[];
+}
+
+export type SafetyResponse = {
+   scores: Record<SafetyCategory, number>;
+   flagged: boolean;
+   flagged_categories: SafetyCategory[];
+   threshold: number;
+   spans?: SafetySpan[];
+}
+
+export type SafetyBatchResponse = {
+   results: SafetyResponse[];
+}
+
+export type SafetyOptions = {
+   threshold?: number,
+   spans?: boolean,
+}
+
 export type SpellcheckOptions = {
    minLength?: number,
    multipleEdits?: boolean,
@@ -52,6 +356,72 @@ export type SpellcheckOptions = {
    userData?: any,
 }
 
+export type ExtractFieldType = 'string' | 'number' | 'integer' | 'boolean' | 'date' | 'list';
+
+export type ExtractField = string | {
+   name: string,
+   type?: ExtractFieldType,
+   description?: string,
+   required?: boolean,
+}
+
+export type ExtractOptions = {
+   context?: string,
+}
+
+export type ExtractedValue = string | number | boolean | string[] | null;
+
+export type ExtractedField = {
+   name: string,
+   type: ExtractFieldType,
+   value: ExtractedValue,
+   evidence: string,
+   found: boolean,
+}
+
+export type ExtractResponse = {
+   data: Record<string, ExtractedValue>,
+   fields: ExtractedField[],
+   missing: string[],
+}
+
+export type ExtractBatchResponse = {
+   results: ExtractResponse[];
+}
+
+export type TranslateOptions = {
+   source_lang?: string,
+   formality?: 'formal' | 'informal',
+}
+
+export type TranslateResponse = {
+   translation: string,
+   source_lang: string,
+   source_lang_name: string | null,
+   target_lang: string,
+   target_lang_name: string,
+}
+
+export type TranslateBatchResponse = {
+   results: TranslateResponse[];
+}
+
+export type SummarizeOptions = {
+   length?: 'short' | 'medium' | 'long',
+}
+
+export type SummarizeResponse = {
+   /** Mirrors `summary` — the endpoint's original response key. */
+   result: string,
+   summary: string,
+   key_points: string[],
+   length: 'short' | 'medium' | 'long',
+}
+
+export type SummarizeBatchResponse = {
+   results: SummarizeResponse[];
+}
+
 export type UserDetails = {
    userId?: string,
    anonUser?: boolean,
@@ -69,7 +439,40 @@ export declare class Client {
    complete(query: string, sessionId?: string): Promise<AxiosResponse>;
    acceptComplete(completeUUID: string, query: string, completion: string, sessionId?: string): Promise<AxiosResponse>;
    tone(text: string): Promise<AxiosResponse>;
+   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, options?: AIDetectOptions): Promise<AxiosResponse>;
-   langdetect(text: string, options?: LangdetectOptions): Promise<AxiosResponse>;
+   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>>;
+   accountStatus(): Promise<AxiosResponse<AccountStatusResponse>>;
 }