@radsoft/markbase 2026.10.1 → 2026.11.1

package/README.md

@@ -163,6 +163,7 @@ Keep the key server-side. It's a secret; don't ship it to the browser.
 |---|---|
 | `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 +246,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, 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
@@ -54,6 +54,11 @@ export declare class Markbase {
         trademarkClass?: string | number;
         limit?: number;
     }): 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>;
     /** 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);
                 }
@@ -199,6 +201,13 @@ export class Markbase {
             },
         });
     }
+    /** 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 }),
+        });
+    }
     /** Distribution counts across a facet. */
     aggregate(by) {
         return this.request("/aggregate", { query: { by } });

package/dist/types.d.ts

@@ -63,6 +63,12 @@ export interface ClearanceResult {
     highest_risk: RiskLevel;
     matches: ClearanceMatch[];
 }
+export interface ClearanceBatchResult {
+    results: ClearanceResult[];
+    usage: {
+        names: number;
+    };
+}
 export interface OwnerResult {
     owner: string;
     hits: Trademark[];

package/package.json

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