@saplingai/sapling-js 1.0.38 → 1.0.45

package/README.md

@@ -76,6 +76,24 @@ You should see something like the following output:
 }
 ```
 
+### 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 }
+  })
+```
+
 ## Frontend Quickstart
 
 The SDK provides a way to automatically apply edit suggestions to any HTML contenteditable and textarea elements.
@@ -108,8 +126,56 @@ 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.
+
 ## 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);
+}
+```

package/client/index.d.ts

@@ -0,0 +1 @@
+export * from '../sapling/client';

package/package.json

@@ -1,24 +1,54 @@
 {
   "name": "@saplingai/sapling-js",
-  "version": "1.0.38",
+  "version": "1.0.45",
   "description": "JavaScript library for using the Sapling.ai API.",
   "type": "module",
+  "main": "./sapling/client.js",
+  "types": "./sapling/client.d.ts",
+  "exports": {
+    ".": {
+      "types": "./sapling/client.d.ts",
+      "default": "./sapling/client.js"
+    },
+    "./client": {
+      "types": "./sapling/client.d.ts",
+      "default": "./sapling/client.js"
+    },
+    "./observer": {
+      "types": "./sapling/observer.d.ts",
+      "default": "./sapling/observer.js"
+    }
+  },
+  "files": [
+    "sapling",
+    "client",
+    "observer",
+    "index.ts",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/client.test.js test/errors.test.js test/pack.test.js",
+    "prepublishOnly": "npm test"
+  },
   "dependencies": {
-    "axios": "^1.6.7",
+    "axios": "^1.19.0",
     "uuid": "^8.3.2"
   },
-  "main": "./sapling/client.js",
-  "types": "./sapling/client.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
   "author": "Sapling Intelligence",
   "email": "info@sapling.ai",
   "url": "https://sapling.ai",
   "homepage": "https://sapling.ai/docs/",
   "repository": {
     "type": "git",
-    "url": "https://github.com/saplingai/sapling-samples.git"
+    "url": "git+https://github.com/saplingai/sapling-js.git"
   },
   "bugs": {
-    "url": "https://github.com/saplingai/sapling-samples/issues",
+    "url": "https://github.com/saplingai/sapling-js/issues",
     "email": "support@sapling.ai"
   },
   "license": "Apache-2.0",
@@ -27,15 +57,5 @@
       "type": "Apache-2.0",
       "url": "http://www.apache.org/licenses/LICENSE-2.0"
     }
-  ],
-  "exports": {
-    "./client": {
-      "types": "./sapling/client.d.ts",
-      "default": "./sapling/client.js"
-    },
-    "./observer": {
-      "types": "./sapling/observer.d.ts",
-      "default": "./sapling/observer.js"
-    }
-  }
+  ]
 }

package/sapling/client.d.ts

@@ -1,6 +1,6 @@
 import { AxiosResponse } from "axios";
 
-type AdvancedEditOptions = {
+export type AdvancedEditOptions = {
    advanced_edits?: boolean,
    adverbs?: boolean,
    simplifications?: boolean,
@@ -20,13 +20,13 @@ type AdvancedEditOptions = {
    violence?: boolean,
 }
 
-type ConstructorOptions = {
+export type ConstructorOptions = {
    timeout?: number,
    hostname?: string,
    pathname?: string,
 }
 
-type EditOptions = {
+export type EditOptions = {
    variety?: string,
    autoApply?: boolean,
    lang?: string,
@@ -34,11 +34,150 @@ type EditOptions = {
    advancedEdits?: AdvancedEditOptions,
 }
 
-type AIDetectOptions = {
+export type AIDetectOptions = {
    sent_scores?: boolean,
 }
 
-type SpellcheckOptions = {
+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 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[];
+   rubric?: QualityRubric;
+}
+
+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 SafetyResponse = {
+   toxicity: number;
+   profanity: number;
+   harassment: number;
+   hate_speech: number;
+   self_harm: number;
+   sexual: number;
+   violence: number;
+   flagged: string[];
+}
+
+export type SafetyOptions = {
+   threshold?: number,
+}
+
+export type SpellcheckOptions = {
    minLength?: number,
    multipleEdits?: boolean,
    lang?: string,
@@ -47,18 +186,59 @@ type SpellcheckOptions = {
    userData?: any,
 }
 
-declare class Client {
+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 UserDetails = {
+   userId?: string,
+   anonUser?: boolean,
+}
+
+export declare class Client {
    constructor(apiKey: string, options?: ConstructorOptions);
 
-   edits(text: string, sessionId: string, options?: EditOptions): Promise<AxiosResponse>;
-   acceptEdit(editUUID: string, sessionId: string): Promise<AxiosResponse>;
-   rejectEdit(editUUID: string, sessionId: string): Promise<AxiosResponse>;
+   edits(text: string, sessionId?: string, options?: EditOptions, userDetails?: UserDetails): Promise<AxiosResponse>;
+   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): 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>;
+   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>>;
 
    aidetect(text: string, options?: AIDetectOptions): Promise<AxiosResponse>;
+   langdetect(text: string, options?: LangdetectOptions): Promise<AxiosResponse>;
+   quality(text: string, options?: QualityOptions): Promise<AxiosResponse<QualityResponse>>;
+   pii(text: string, options?: PIIOptions): Promise<AxiosResponse<PIIResponse>>;
+   safety(text: string, options?: SafetyOptions): Promise<AxiosResponse<SafetyResponse>>;
+   classify(text: string, labels: ClassifyLabel[], options?: ClassifyOptions): Promise<AxiosResponse<ClassifyResponse>>;
+   seo(text: string, options?: SeoOptions): Promise<AxiosResponse<SeoResponse>>;
 }

package/sapling/client.js

@@ -1,6 +1,9 @@
 import axios from "axios";
 import { v4 as uuidv4 } from 'uuid';
 
+// Value types an extract() field may declare; 'string' is the default.
+const EXTRACT_FIELD_TYPES = ['string', 'number', 'integer', 'boolean', 'date', 'list'];
+
 export class Client {
   constructor(apiKey, options = {}) {
     this.apiKey = apiKey;
@@ -13,7 +16,7 @@ export class Client {
   }
 
   axiosPromise(url, method, data) {
-    return new Promise((resolve) => {
+    return new Promise((resolve, reject) => {
       axios({
         url,
         method,
@@ -22,7 +25,8 @@ export class Client {
       })
       .then(function (response) {
           resolve(response);
-      });
+      })
+      .catch(reject);
     });
   }
 
@@ -106,27 +110,27 @@ export class Client {
     }
 
     if (options.minLength != null) {
-      data.min_length = minLength;
+      data.min_length = options.minLength;
     }
 
     if (options.multipleEdits != null) {
-      data.multiple_edits = multipleEdits;
+      data.multiple_edits = options.multipleEdits;
     }
 
     if (options.lang != null) {
-      data.lang = lang;
+      data.lang = options.lang;
     }
 
     if (options.autoApply != null) {
-      data.auto_apply = autoApply;
+      data.auto_apply = options.autoApply;
     }
 
     if (options.variety != null) {
-      data.variety = variety;
+      data.variety = options.variety;
     }
 
     if (options.userData != null) {
-      data.user_data = userData;
+      data.user_data = options.userData;
     }
 
     if (userDetails) {
@@ -176,6 +180,356 @@ export class Client {
     return this.axiosPromise(url, 'post', data);
   }
 
+  /**
+   * Structured data extraction: pull caller-named fields out of unstructured text.
+   *
+   * `classify()` answers "what kind of text is this"; `extract()` answers "what's in it".
+   * Pass 1–20 fields — plain names, or `{name, type, description, required}` objects to
+   * declare the value type and sharpen ambiguous fields. Returns `data` (a
+   * `{field name: value}` map with every requested field present and `null` where the text
+   * didn't state it), `fields` (one entry per requested field, in request order, each with
+   * the verbatim `evidence` span the value came from) and `missing` (the names the text
+   * didn't yield).
+   *
+   * Values are coerced to the declared type server-side and must be grounded in a quote
+   * from the text, so this is extraction, not inference: a value that isn't stated is
+   * reported missing rather than guessed. Finding nothing is a normal 200.
+   *
+   * @param {string} text - The document to extract from, plain text or HTML (the API caps
+   *   it at 10,000 characters).
+   * @param {Array<string|{name: string, type?: string, description?: string, required?: boolean}>} fields -
+   *   The fields to pull out (1–20): field names, or objects. `type` is one of 'string'
+   *   (default), 'number', 'integer', 'boolean', 'date' (returned as YYYY-MM-DD) or 'list'.
+   *   Names must be unique case-insensitively; the API caps names at 50 characters and
+   *   descriptions at 200.
+   * @param {Object} [options]
+   * @param {string} [options.context] - Optional guidance (the API caps it at 500
+   *   characters): what the document is and how to read ambiguous fields, e.g.
+   *   'A vendor invoice'.
+   * @returns {Promise<AxiosResponse>}
+   */
+  extract(text, fields, options = {}) {
+    const url = `${this.urlEndpoint}extract`;
+
+    // Shape/type checks only. Size limits (text length, field name/description/
+    // context length) are server configuration and enforced there with a clear
+    // 400 — mirroring them here would drift the day they change (and JS
+    // `length` counts UTF-16 units, not the characters the API counts).
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('extract: text must be a non-empty string.');
+    }
+
+    const isValidField = (field) => {
+      if (typeof field === 'string') {
+        return field.trim().length > 0;
+      }
+      if (field == null || typeof field !== 'object' || Array.isArray(field)) {
+        return false;
+      }
+      if (typeof field.name !== 'string' || field.name.trim().length === 0) {
+        return false;
+      }
+      if (field.type !== undefined && !EXTRACT_FIELD_TYPES.includes(field.type)) {
+        return false;
+      }
+      if (field.description !== undefined && typeof field.description !== 'string') {
+        return false;
+      }
+      if (field.required !== undefined && typeof field.required !== 'boolean') {
+        return false;
+      }
+      // Reject unknown keys so a typo like `{ name, typ: 'number' }` fails here
+      // rather than being forwarded to the API as a malformed field (the MCP
+      // schema is `.strict()` for the same reason).
+      const allowed = new Set(['name', 'type', 'description', 'required']);
+      if (Object.keys(field).some((key) => !allowed.has(key))) {
+        return false;
+      }
+      return true;
+    };
+
+    if (
+      !Array.isArray(fields)
+      || fields.length < 1
+      || fields.length > 20
+      // Array.from() materializes holes in sparse arrays as `undefined` (which
+      // isValidField rejects); a bare `.every()` would skip them and let a hole
+      // through to be serialized as `null`.
+      || !Array.from(fields).every(isValidField)
+    ) {
+      throw new TypeError('extract: fields must be an array of 1 to 20 non-empty strings or '
+        + '{name, type?, description?, required?} objects (string name, type one of '
+        + `${EXTRACT_FIELD_TYPES.join(', ')}, optional string description, optional boolean required).`);
+    }
+
+    const names = fields.map((field) => (typeof field === 'string' ? field : field.name).toLowerCase());
+    if (names.length !== new Set(names).size) {
+      throw new TypeError('extract: field names must be unique (case-insensitive).');
+    }
+
+    let data = {
+      text,
+      fields,
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a bad
+    // type rather than silently treated as "omitted", matching how a null
+    // `description` is rejected above.
+    if (options?.context !== undefined) {
+      if (typeof options.context !== 'string') {
+        throw new TypeError('extract: context must be a string.');
+      }
+      data.context = options.context;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  langdetect(text, options = {}) {
+    const url = `${this.urlEndpoint}langdetect`;
+
+    let data = {
+      text,
+      key: this.apiKey,
+    }
+
+    if (options?.top_k != null) {
+      data.top_k = options.top_k;
+    }
+    if (options?.segments != null) {
+      data.segments = options.segments;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * Zero-shot text classification: assign one (or several) of your own labels to a text.
+   *
+   * No training data needed — pass 2–20 candidate labels (plain names, or
+   * `{name, description}` objects; a short description per label sharpens borderline
+   * decisions). Returns `label` (best match, always one of your labels), `labels`
+   * (single-label: `[label]`; multi-label: every label with `score >= threshold`, possibly
+   * empty), `scores` (one `{label, score}` per input label, descending), a one-sentence
+   * `rationale` and the echoed `multi_label` mode.
+   *
+   * @param {string} text - Text to classify, plain text or HTML (the API caps it at 10,000 chars).
+   * @param {Array<string|{name: string, description?: string}>} labels - Candidate labels
+   *   (2–20). Names unique case-insensitively; the API caps names at 50 and descriptions at 200 chars.
+   * @param {Object} [options]
+   * @param {boolean} [options.multiLabel] - true: zero, one or several labels may apply
+   *   (independent 0–1 scores). Defaults to false: exactly one label (scores sum to ~1).
+   * @param {number} [options.threshold] - Multi-label cut-off on the per-label score (0–1,
+   *   default 0.5). Ignored in single-label mode.
+   * @param {string} [options.context] - Optional guidance (max 500 chars): what the texts
+   *   are and how to decide borderline cases, e.g. 'Support tickets for a SaaS billing product'.
+   * @returns {Promise<AxiosResponse>}
+   */
+  classify(text, labels, options = {}) {
+    const url = `${this.urlEndpoint}classify`;
+
+    // Shape/type checks only. Size limits (text length, label/description/
+    // context length) are server configuration and enforced there with a
+    // clear 400 — mirroring them here would drift the day they change (and
+    // JS `length` counts UTF-16 units, not the characters the API counts).
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('classify: text must be a non-empty string.');
+    }
+
+    const isValidLabel = (label) => {
+      if (typeof label === 'string') {
+        return label.trim().length > 0;
+      }
+      if (label == null || typeof label !== 'object' || Array.isArray(label)) {
+        return false;
+      }
+      if (typeof label.name !== 'string' || label.name.trim().length === 0) {
+        return false;
+      }
+      if (label.description !== undefined && typeof label.description !== 'string') {
+        return false;
+      }
+      // Reject unknown keys so a typo like `{ name, descrption: '...' }` fails
+      // here rather than being forwarded to the API as a malformed label (the
+      // MCP object schema is `.strict()` and `extract()` does the same).
+      const allowed = new Set(['name', 'description']);
+      if (Object.keys(label).some((key) => !allowed.has(key))) {
+        return false;
+      }
+      return true;
+    };
+
+    if (
+      !Array.isArray(labels)
+      || labels.length < 2
+      || labels.length > 20
+      // Array.from() materializes holes in sparse arrays as `undefined` (which
+      // isValidLabel rejects); a bare `.every()` would skip them and let a hole
+      // through to be serialized as `null`.
+      || !Array.from(labels).every(isValidLabel)
+    ) {
+      throw new TypeError('classify: labels must be an array of 2 to 20 non-empty strings or '
+        + '{name, description?} objects (string name, optional string description).');
+    }
+
+    const names = labels.map((label) => (typeof label === 'string' ? label : label.name).toLowerCase());
+    if (names.length !== new Set(names).size) {
+      throw new TypeError('classify: label names must be unique (case-insensitive).');
+    }
+
+    let data = {
+      text,
+      labels,
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a bad
+    // type rather than silently treated as "omitted", matching how a null
+    // `description` is rejected above.
+    if (options?.multiLabel !== undefined) {
+      if (typeof options.multiLabel !== 'boolean') {
+        throw new TypeError('classify: multiLabel must be a boolean.');
+      }
+      data.multi_label = options.multiLabel;
+    }
+    if (options?.threshold !== undefined) {
+      if (typeof options.threshold !== 'number' || !Number.isFinite(options.threshold)
+        || options.threshold < 0 || options.threshold > 1) {
+        throw new TypeError('classify: threshold must be a finite number between 0 and 1.');
+      }
+      data.threshold = options.threshold;
+    }
+    if (options?.context !== undefined) {
+      if (typeof options.context !== 'string') {
+        throw new TypeError('classify: context must be a string.');
+      }
+      data.context = options.context;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  /**
+   * SEO analysis and metadata generation for a page or article body (plain text or HTML).
+   *
+   * Always returns deterministic `stats` (word/sentence/paragraph counts, reading time,
+   * Flesch readability), `keywords` (count/density/in_first_100_words for each target
+   * keyword) and `top_terms` (most frequent unigrams/bigrams). By default also returns
+   * LLM-generated `suggestions` (titles, meta_descriptions, slug — null when no ASCII slug
+   * can be derived — and keywords) — pass
+   * `suggestions: false` for the free stats-only mode.
+   *
+   * @param {string} text - Page/article body, plain text or HTML (max 20,000 chars).
+   * @param {Object} [options]
+   * @param {string[]} [options.keywords] - Target keyword phrases, most important first
+   *   (max 10, each 1–100 chars). Measured in the text and steered into the suggestions.
+   * @param {boolean} [options.suggestions] - Generate LLM suggestions. Defaults to true;
+   *   false returns stats/keywords/top_terms only (unbilled).
+   * @param {string} [options.lang] - ISO 639-1 language code of the text (region subtag
+   *   allowed, e.g. 'pt-BR'; or 'auto'). Defaults to 'en'. Only selects the readability
+   *   formulas: supported for en/de/es/fr/it/nl/pl/ru, otherwise flesch_reading_ease /
+   *   flesch_kincaid_grade are null.
+   * @returns {Promise<AxiosResponse>}
+   */
+  seo(text, options = {}) {
+    const url = `${this.urlEndpoint}seo`;
+
+    // Shape/type checks only. Size limits (text length, keyword count/length)
+    // are server configuration and enforced there with a clear 400 — mirroring
+    // them here would drift the day they change (and JS `length` counts UTF-16
+    // units, not the characters the API counts).
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('seo: text must be a non-empty string.');
+    }
+
+    let data = {
+      text,
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a bad
+    // type rather than silently treated as "omitted", matching classify().
+    if (options?.keywords !== undefined) {
+      if (!Array.isArray(options.keywords)
+        || !Array.from(options.keywords).every((k) => typeof k === 'string' && k.trim().length > 0)) {
+        throw new TypeError('seo: keywords must be an array of non-empty strings.');
+      }
+      data.keywords = options.keywords;
+    }
+    if (options?.suggestions !== undefined) {
+      if (typeof options.suggestions !== 'boolean') {
+        throw new TypeError('seo: suggestions must be a boolean.');
+      }
+      data.suggestions = options.suggestions;
+    }
+    if (options?.lang !== undefined) {
+      if (typeof options.lang !== 'string') {
+        throw new TypeError('seo: lang must be a string.');
+      }
+      data.lang = options.lang;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  quality(text, options = {}) {
+    const url = `${this.urlEndpoint}quality`;
+
+    // Shape/type checks only; size limits are server configuration (see seo()).
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('quality: text must be a non-empty string.');
+    }
+
+    let data = {
+      text,
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a bad
+    // type rather than silently treated as "omitted", matching classify()/seo().
+    if (options?.sentence_scores !== undefined) {
+      if (typeof options.sentence_scores !== 'boolean') {
+        throw new TypeError('quality: sentence_scores must be a boolean.');
+      }
+      data.sentence_scores = options.sentence_scores;
+    }
+    if (options?.rubric !== undefined) {
+      if (typeof options.rubric !== 'boolean') {
+        throw new TypeError('quality: rubric must be a boolean.');
+      }
+      data.rubric = options.rubric;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
+  safety(text, options = {}) {
+    const url = `${this.urlEndpoint}safety`;
+
+    // Shape/type checks only; size limits are server configuration (see seo()).
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('safety: text must be a non-empty string.');
+    }
+
+    let data = {
+      text,
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a bad
+    // type rather than silently treated as "omitted", matching classify().
+    if (options?.threshold !== undefined) {
+      if (typeof options.threshold !== 'number' || !Number.isFinite(options.threshold)
+        || options.threshold < 0 || options.threshold > 1) {
+        throw new TypeError('safety: threshold must be a finite number between 0 and 1.');
+      }
+      data.threshold = options.threshold;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
+
   aidetect(text, options = {}) {
     const url = `${this.urlEndpoint}aidetect`;
 
@@ -190,4 +544,37 @@ export class Client {
 
     return this.axiosPromise(url, 'post', data);
   }
+
+  pii(text, options = {}) {
+    const url = `${this.urlEndpoint}pii`;
+
+    // Shape/type checks only; the set of valid PII types is server configuration
+    // and enforced there with a clear 400 (see seo()).
+    if (typeof text !== 'string' || text.trim().length === 0) {
+      throw new TypeError('pii: text must be a non-empty string.');
+    }
+
+    let data = {
+      text,
+      key: this.apiKey,
+    }
+
+    // `!== undefined` (not `!= null`) so an explicit `null` is rejected as a bad
+    // type rather than silently treated as "omitted", matching classify()/seo().
+    if (options?.types !== undefined) {
+      if (!Array.isArray(options.types)
+        || !Array.from(options.types).every((type) => typeof type === 'string' && type.trim().length > 0)) {
+        throw new TypeError('pii: types must be an array of non-empty strings.');
+      }
+      data.types = options.types;
+    }
+    if (options?.redact !== undefined) {
+      if (typeof options.redact !== 'boolean') {
+        throw new TypeError('pii: redact must be a boolean.');
+      }
+      data.redact = options.redact;
+    }
+
+    return this.axiosPromise(url, 'post', data);
+  }
 }

package/npmtest/package.json

@@ -1,11 +0,0 @@
-{
-  "name": "@saplingai/sapling-js",
-  "version": "1.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "author": "",
-  "license": "Apache-2.0"
-}