@radsoft/markbase 2026.11.1 → 2026.11.3

package/README.md

@@ -157,6 +157,27 @@ Keep the key server-side. It's a secret; don't ship it to the browser.
 
 ---
 
+## Opt-in phonetic clearance
+
+Starting with SDK `2026.11.2`, pass `phonetic: true` in `clearance` or
+`clearanceBatch` options to add whole-name ASCII phonetic matching. Omit it or use
+`false` for spelling-only behavior. One name still uses one monthly request;
+batches require Launch or Scale.
+
+Read `matching.phonetic_status` and each match's `signals.phonetic` separately from
+`similarity` and `risk`, which retain their spelling-based meaning. Names with
+digits, non-ASCII characters, more than 12 tokens, or no token of at least four
+letters return `not_evaluated` and retain spelling results. A changed token must
+have at least four letters; short tokens must match literally in the same position.
+`matching.truncated` reports a phonetic retrieval cap or hydration budget being
+reached; `false` does not establish exhaustive coverage.
+
+An unavailable opt-in request returns 503 without silently switching modes.
+Admission failures do not consume monthly quota. Accepted batches count even if a
+search fails and are never retried automatically. See the
+[phonetic contract](../docs/phonetic-clearance.md) for response evidence, ranking,
+and limits. Phonetic evidence does not establish legal availability.
+
 ## Reference
 
 | Method | Returns |

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { Trademark, SearchOptions, SearchResult, Suggestion, ClearanceResult, ClearanceBatchResult, 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,19 +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?: {
-        trademarkClass?: string | number;
-        limit?: number;
-    }): Promise<ClearanceBatchResult>;
+    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

@@ -188,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.
      */
@@ -198,6 +198,7 @@ export class Markbase {
                 mark,
                 class: opts.trademarkClass == null ? undefined : padClass(opts.trademarkClass),
                 limit: opts.limit,
+                phonetic: opts.phonetic,
             },
         });
     }
@@ -205,7 +206,7 @@ export class Markbase {
     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 }),
+            body: JSON.stringify({ marks, class: opts.trademarkClass == null ? undefined : padClass(opts.trademarkClass), limit: opts.limit, phonetic: opts.phonetic }),
         });
     }
     /** Distribution counts across a facet. */

package/dist/types.d.ts

@@ -52,16 +52,48 @@ export interface Suggestion {
     owner_name: string | null;
     status_code: string | null;
 }
+export interface ClearanceOptions {
+    trademarkClass?: string | number;
+    limit?: number;
+    /** Opt-in whole-name ASCII phonetic matching; 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[];

package/package.json

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