@radsoft/markbase 2026.10.2 → 2026.11.2

package/README.md

@@ -157,12 +157,23 @@ Keep the key server-side. It's a secret; don't ship it to the browser.
 
 ---
 
+## Unreleased: opt-in phonetic clearance
+
+The source client accepts an optional `phonetic` boolean in `clearance` and
+`clearanceBatch` options. The API mode is not enabled in production yet; client
+support alone does not make it available. Omit the option for current spelling-only
+behavior. An unavailable opt-in request returns 503, and batches are never retried
+automatically. See the [unreleased contract](../docs/phonetic-clearance.md) for
+response evidence, ranking, and input limits. Existing spelling scores and risk
+thresholds remain unchanged; phonetic evidence is not a legal availability decision.
+
 ## Reference
 
 | Method | Returns |
 |---|---|
 | `search(opts \| string)` | `SearchResult` — typo-tolerant full-text search |
 | `clearance(mark, opts?)` | `ClearanceResult` — ranked conflicts with a risk level |
+| `clearanceBatch(marks, opts?)` | `ClearanceBatchResult` — 1–25 names in input order (**Launch or Scale**) |
 | `suggest(q, limit?)` | `Suggestion[]` — autocomplete, tuned for as-you-type |
 | `getTrademark(serial)` | `Trademark` — one full record |
 | `getTimeline(serial)` | prosecution history |
@@ -245,7 +256,14 @@ try {
 ## Rate limits and quota
 
 Per-minute limits and 5xx are **retried automatically** with backoff
-(`maxRetries`, default 2).
+(`maxRetries`, default 2), except for `clearanceBatch()`.
+
+Bulk clearance accepts 1–25 names, each up to 200 characters, with an optional
+shared `trademarkClass` and `limit` of 1–50 matches per name (default 20). Every
+submitted name counts toward monthly and per-minute limits, including duplicates.
+A batch that exceeds the remaining monthly quota is rejected in full. Accepted
+batches consume their full name count even if a search fails. The SDK never
+automatically retries bulk requests because that could charge the names again.
 
 Monthly quota exhaustion is **not retried** — waiting a few seconds can't fix a
 month-long window, so it throws immediately with `resetsAt` rather than burning

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { Trademark, SearchOptions, SearchResult, Suggestion, ClearanceResult, OwnerResult, BatchResult, AggregateField, AggregateResult, NiceClass, IndexInfo, RateLimitInfo, MarkStatus } from "./types.js";
+import type { Trademark, SearchOptions, SearchResult, Suggestion, ClearanceOptions, ClearanceResult, ClearanceBatchResult, OwnerResult, BatchResult, AggregateField, AggregateResult, NiceClass, IndexInfo, RateLimitInfo, MarkStatus } from "./types.js";
 export interface MarkbaseOptions {
     /**
      * Get one free at https://markbase.co. Omitted falls back to
@@ -46,14 +46,13 @@ export declare class Markbase {
         limit?: number;
     }): Promise<OwnerResult>;
     /**
-     * Screen a proposed name against the register, ranked by similarity.
+     * Screen a proposed name against the register. Spelling-only matching is the default.
      * A first-pass signal, not legal advice — pass a class, since trademark
      * rights are scoped to goods and services.
      */
-    clearance(mark: string, opts?: {
-        trademarkClass?: string | number;
-        limit?: number;
-    }): Promise<ClearanceResult>;
+    clearance(mark: string, opts?: ClearanceOptions): Promise<ClearanceResult>;
+    /** Screen 1–25 names on Launch or Scale. Each name consumes quota; retries are disabled. */
+    clearanceBatch(marks: string[], opts?: ClearanceOptions): Promise<ClearanceBatchResult>;
     /** Distribution counts across a facet. */
     aggregate(by: AggregateField): Promise<AggregateResult>;
     /** All 45 Nice classification classes. */

package/dist/client.js

@@ -68,8 +68,9 @@ export class Markbase {
         };
     }
     async request(path, init) {
+        const { query, retry, ...requestInit } = init ?? {};
         const url = new URL(this.baseUrl + path);
-        for (const [k, v] of Object.entries(init?.query ?? {})) {
+        for (const [k, v] of Object.entries(query ?? {})) {
             if (v == null)
                 continue;
             if (Array.isArray(v))
@@ -77,13 +78,14 @@ export class Markbase {
             else
                 url.searchParams.set(k, String(v));
         }
+        const maxRetries = retry === false ? 0 : this.maxRetries;
         let lastErr;
-        for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
             const ctrl = new AbortController();
             const timer = setTimeout(() => ctrl.abort(), this.timeout);
             try {
                 const res = await this.fetchImpl(url, {
-                    ...init,
+                    ...requestInit,
                     signal: ctrl.signal,
                     headers: {
                         accept: "application/json",
@@ -111,13 +113,13 @@ export class Markbase {
                     // per-minute limit is worth retrying
                     const retryAfterMs = isQuota ? null : 1000 * (attempt + 1) * 2;
                     const err = new RateLimitError(message, isQuota ? "quota" : "rate", retryAfterMs, resetsAt, body);
-                    if (isQuota || attempt >= this.maxRetries)
+                    if (isQuota || attempt >= maxRetries)
                         throw err;
                     lastErr = err;
                     await sleep(retryAfterMs);
                     continue;
                 }
-                if (res.status >= 500 && attempt < this.maxRetries) {
+                if (res.status >= 500 && attempt < maxRetries) {
                     lastErr = new MarkbaseError(message, res.status, body);
                     await sleep(1000 * (attempt + 1));
                     continue;
@@ -129,7 +131,7 @@ export class Markbase {
                     throw err;
                 // network error or timeout — worth one more go
                 lastErr = err;
-                if (attempt >= this.maxRetries) {
+                if (attempt >= maxRetries) {
                     const msg = err?.name === "AbortError" ? `Request timed out after ${this.timeout}ms` : String(err);
                     throw new MarkbaseError(msg, 0);
                 }
@@ -186,7 +188,7 @@ export class Markbase {
         return this.request("/owner", { query: { name, ...opts } });
     }
     /**
-     * Screen a proposed name against the register, ranked by similarity.
+     * Screen a proposed name against the register. Spelling-only matching is the default.
      * A first-pass signal, not legal advice — pass a class, since trademark
      * rights are scoped to goods and services.
      */
@@ -196,9 +198,17 @@ export class Markbase {
                 mark,
                 class: opts.trademarkClass == null ? undefined : padClass(opts.trademarkClass),
                 limit: opts.limit,
+                phonetic: opts.phonetic,
             },
         });
     }
+    /** Screen 1–25 names on Launch or Scale. Each name consumes quota; retries are disabled. */
+    clearanceBatch(marks, opts = {}) {
+        return this.request("/clearance/batch", {
+            method: "POST", retry: false,
+            body: JSON.stringify({ marks, class: opts.trademarkClass == null ? undefined : padClass(opts.trademarkClass), limit: opts.limit, phonetic: opts.phonetic }),
+        });
+    }
     /** Distribution counts across a facet. */
     aggregate(by) {
         return this.request("/aggregate", { query: { by } });

package/dist/types.d.ts

@@ -52,16 +52,54 @@ export interface Suggestion {
     owner_name: string | null;
     status_code: string | null;
 }
+export interface ClearanceOptions {
+    trademarkClass?: string | number;
+    limit?: number;
+    /** Unreleased opt-in; unavailable mode returns 503. Omit for spelling-only matching. */
+    phonetic?: boolean;
+}
+export interface ClearanceMatching {
+    mode: "spelling_and_phonetic";
+    algorithm: "double_metaphone_v1";
+    ranking: "phonetic_v1";
+    phonetic_status: "evaluated" | "not_evaluated";
+    truncated: boolean;
+}
+export interface ClearanceSignals {
+    exact: boolean;
+    spelling: {
+        score: number;
+    };
+    phonetic: {
+        algorithm: "double_metaphone_v1";
+        status: "matched" | "not_matched" | "not_evaluated";
+        scope?: "whole_name";
+        tokens?: Array<{
+            query: string;
+            candidate: string;
+            variant: "primary" | "alternate";
+        }>;
+    };
+}
 export interface ClearanceMatch extends Pick<Trademark, "serial_number" | "word_mark" | "owner_name" | "status_code" | "international_codes"> {
-    /** 0-1, higher means more similar to the proposed mark. */
+    /** 0-1 spelling score; phonetic evidence does not change this value. */
     similarity: number;
     risk: RiskLevel;
+    signals?: ClearanceSignals;
 }
 export interface ClearanceResult {
     mark: string;
     class: string | null;
+    /** Maximum spelling-based risk among retrieved candidates before the result limit. */
     highest_risk: RiskLevel;
     matches: ClearanceMatch[];
+    matching?: ClearanceMatching;
+}
+export interface ClearanceBatchResult {
+    results: ClearanceResult[];
+    usage: {
+        names: number;
+    };
 }
 export interface OwnerResult {
     owner: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radsoft/markbase",
-  "version": "2026.10.2",
+  "version": "2026.11.2",
   "description": "Official Node client for the Markbase USPTO trademark API — search, screen, and look up 14M+ US trademarks.",
   "license": "MIT",
   "type": "module",