@radsoft/markbase 2026.8.2 → 2026.8.3

package/README.md

@@ -1,152 +1,330 @@
 # @radsoft/markbase
 
-Official Node client for the [Markbase](https://markbase.co) USPTO trademark API.
-Search, screen, and look up 14M+ US trademarks with full TypeScript types.
-
-Covers the **USPTO only**. If you need EUIPO, WIPO, or UKIPO, a multi-office
-platform is a better fit.
+Node client for the [Markbase](https://markbase.co) USPTO trademark API — search,
+screen, and look up **14M+ US trademarks**. Fully typed, zero dependencies.
 
 ```bash
 npm i @radsoft/markbase
 ```
 
-## Quick start
+Covers the **USPTO only**. If you need EUIPO, WIPO, or UKIPO, a multi-office
+platform is a better fit — we'd rather say so than waste your time.
+
+---
+
+## 30 seconds
 
-No key needed to try it — the keyless tier allows 1,000 requests a month.
-[Get a free key](https://markbase.co/login) for 5,000.
+No key needed to try it. The keyless tier allows 1,000 requests a month;
+[a free account](https://markbase.co/login) raises that to 5,000.
 
 ```ts
 import { Markbase } from "@radsoft/markbase";
 
-const mb = new Markbase({ apiKey: process.env.MARKBASE_API_KEY });
+const mb = new Markbase(); // reads MARKBASE_API_KEY if set
 
-// "can we call it this?"
-const result = await mb.clearance("Acme", { trademarkClass: 9 });
-if (result.highest_risk === "high") {
-  console.log("Conflicts:", result.matches.map((m) => m.word_mark));
-}
+const { highest_risk, matches } = await mb.clearance("nikee", {
+  trademarkClass: 25, // clothing
+});
+
+console.log(highest_risk);        // "high"
+console.log(matches[0].word_mark); // "NIKE"
+console.log(matches[0].owner_name);// "Nike, Inc."
+console.log(matches[0].similarity);// 0.85
 ```
 
-The key is read from `MARKBASE_API_KEY` if you don't pass one. Pass `apiKey: null`
-to force the keyless tier even when that variable is set.
+---
+
+## The one thing to get right: classes
+
+Trademark rights are scoped to **goods and services**, not to names. DELTA
+coexists as an airline, a faucet maker, and dental insurance — same word, three
+owners, no conflict.
 
-## Screening a name
+So screening without a class gives you noise:
 
-Trademark rights are scoped to goods and services — DELTA coexists as an airline,
-a faucet maker, and dental insurance. **Always pass a class**, or you get noise
-instead of blockers.
+```ts
+await mb.clearance("Delta");                      // ~everything, mostly irrelevant
+await mb.clearance("Delta", { trademarkClass: 9 }); // only what could block you
+```
+
+There are 45 classes. Fetch them to build a picker:
 
 ```ts
-const { highest_risk, matches } = await mb.clearance("nikee", { trademarkClass: 25 });
-// highest_risk: "high"
-// matches[0]: { word_mark: "NIKE", owner_name: "Nike, Inc.", similarity: 0.85, risk: "high" }
+const classes = await mb.classes();
+// [{ code: "009", title: "Computers & electronics" }, ...]
 ```
 
-`mb.classes()` returns all 45 Nice classes if you need to pick one.
+Common ones: **9** software · **25** clothing · **35** advertising & business ·
+**41** education & entertainment · **42** science & technology services (where
+most SaaS sits).
 
-## Searching
+---
 
-Typo-tolerant — `gogle` finds Google's marks.
+## Recipes
+
+### Screen names from a generator
+
+The usual shape: generate candidates, drop the ones that are obviously taken.
 
 ```ts
-const res = await mb.search({ q: "gogle", limit: 10 });
+import { Markbase } from "@radsoft/markbase";
 
-// filters
-await mb.search({
-  q: "acme",
-  trademarkClass: 9,        // 9 and "009" both work
-  statusCode: "800",        // registered
-  ownerCountry: "US",
-  filingDateFrom: "20200101",
+const mb = new Markbase();
+
+async function viable(names: string[], trademarkClass: number) {
+  const checks = await Promise.all(
+    names.map(async (name) => {
+      const { highest_risk } = await mb.clearance(name, { trademarkClass });
+      return { name, risk: highest_risk };
+    })
+  );
+  return checks.filter((c) => c.risk === "low" || c.risk === "none");
+}
+
+await viable(["Zeplo", "Nikee", "Flowmint"], 25);
+// [{ name: "Zeplo", risk: "low" }, { name: "Flowmint", risk: "low" }]
+// "Nikee" is dropped — high risk against NIKE in class 25
+```
+
+### Flag conflicts at checkout
+
+For a registrar or a "claim your brand" flow — warn before they pay.
+
+```ts
+const { highest_risk, matches } = await mb.clearance(brand, {
+  trademarkClass: 42,
+  limit: 3,
 });
+
+if (highest_risk === "high") {
+  return {
+    warn: `“${matches[0].word_mark}” is already registered by ${matches[0].owner_name}.`,
+    conflicts: matches,
+  };
+}
 ```
 
-`total_hits` is capped at 1,000 by the search engine — narrow with filters when
-you need an exact count, or use `aggregate()`.
+### Watch a competitor's portfolio
+
+```ts
+const { hits } = await mb.byOwner("Nike, Inc.", { limit: 50 });
 
-Walk large result sets without managing pages:
+const live = hits.filter((m) => statusOf(m.status_code) === "registered");
+console.log(`${live.length} live in this page`);
+
+// note: total_hits saturates at 1000 for large portfolios — page through with
+// the `page` option, or use aggregate() if you need a true count
+```
+
+### Analyse a whole class
+
+`total_hits` caps at 1,000, so use `aggregate()` when you want real numbers.
+
+```ts
+const { buckets } = await mb.aggregate("class");
+// [{ key: "009", count: 1839467 }, { key: "035", count: 1437003 }, ...]
+
+const byCountry = await mb.aggregate("country");
+const byYear = await mb.aggregate("year");
+```
+
+### Walk a large result set
+
+`paginate()` handles the page arithmetic and stops when results run out.
 
 ```ts
 for await (const mark of mb.paginate({ q: "coffee", limit: 100 }, 5)) {
-  console.log(mark.word_mark);
+  console.log(mark.serial_number, mark.word_mark);
 }
 ```
 
-## Everything else
+### In a Next.js route handler
 
 ```ts
-await mb.suggest("nik", 5);              // autocomplete, tuned for as-you-type
-await mb.getTrademark("72414177");       // one full record
-await mb.getTimeline("72414177");        // prosecution history
-await mb.byOwner("Nike, Inc.");          // an owner's whole portfolio
-await mb.aggregate("class");             // distribution counts
-await mb.info();                         // index size and freshness
-await mb.getBatch([...]);                // up to 50 at once — Scale plan only
+// app/api/check/route.ts
+import { Markbase } from "@radsoft/markbase";
+
+const mb = new Markbase({ apiKey: process.env.MARKBASE_API_KEY });
+
+export async function POST(req: Request) {
+  const { name, trademarkClass } = await req.json();
+  const result = await mb.clearance(name, { trademarkClass });
+  return Response.json(result);
+}
 ```
 
-## Helpers
+Keep the key server-side. It's a secret; don't ship it to the browser.
+
+---
+
+## Reference
+
+| Method | Returns |
+|---|---|
+| `search(opts \| string)` | `SearchResult` — typo-tolerant full-text search |
+| `clearance(mark, opts?)` | `ClearanceResult` — ranked conflicts with a risk level |
+| `suggest(q, limit?)` | `Suggestion[]` — autocomplete, tuned for as-you-type |
+| `getTrademark(serial)` | `Trademark` — one full record |
+| `getTimeline(serial)` | prosecution history |
+| `byOwner(name, opts?)` | `OwnerResult` — an owner's portfolio |
+| `getBatch(serials)` | `BatchResult` — up to 50 at once (**Scale plan**) |
+| `aggregate(field)` | `AggregateResult` — counts by class/status/country/drawing/year |
+| `classes()` | `NiceClass[]` — all 45 |
+| `info()` | `IndexInfo` — index size and freshness |
+| `paginate(opts, maxPages?)` | `AsyncGenerator<Trademark>` |
+
+### Search options
+
+```ts
+await mb.search({
+  q: "acme",                  // typo-tolerant: "gogle" finds Google
+  trademarkClass: 9,          // 9, "009", or [9, 42] all work
+  statusCode: "800",          // 800 = registered
+  ownerCountry: "US",
+  ownerState: "CA",
+  filingDateFrom: "20200101", // YYYYMMDD
+  filingDateTo: "20251231",
+  sort: "filing_date:desc",
+  page: 1,
+  limit: 50,
+  facets: true,               // include distribution counts
+});
+```
+
+### Helpers
 
 USPTO records are raw. These make them presentable:
 
 ```ts
-import { statusOf, parseDate } from "@radsoft/markbase";
+import { statusOf, parseDate, padClass } from "@radsoft/markbase";
 
-statusOf("800");        // "registered"  (600s are dead, 710s cancelled, 900+ expired)
-parseDate("19720131");  // Date — USPTO stores YYYYMMDD strings
+statusOf("800");        // "registered"
+statusOf("601");        // "dead"
+statusOf("710");        // "cancelled"
+parseDate("19720131");  // Date(1972-01-31) — the register stores YYYYMMDD
+padClass(9);            // "009"
 ```
 
-## Errors and limits
+---
 
-Typed errors, so you can branch on what actually went wrong:
+## Errors
+
+Typed, so you can branch on what actually went wrong rather than parsing strings.
 
 ```ts
-import { RateLimitError, PlanError, AuthError, NotFoundError } from "@radsoft/markbase";
+import {
+  MarkbaseError, AuthError, PlanError, RateLimitError, NotFoundError,
+} from "@radsoft/markbase";
 
 try {
   await mb.getBatch(serials);
 } catch (err) {
   if (err instanceof PlanError) {
-    // batch is Scale-only
+    // endpoint isn't on this plan — batch is Scale-only
   } else if (err instanceof RateLimitError && err.kind === "quota") {
-    // monthly allowance gone — err.resetsAt tells you when it returns.
-    // retrying sooner won't help, which is why the client doesn't.
+    // month's allowance is gone; err.resetsAt says when it returns
+  } else if (err instanceof AuthError) {
+    // bad or missing key
+  } else if (err instanceof NotFoundError) {
+    // no such serial number
   }
 }
 ```
 
-Per-minute limits and 5xx are retried automatically with backoff (`maxRetries`,
-default 2). Monthly quota exhaustion is not — waiting seconds can't fix a
-month-long window.
+| Error | When |
+|---|---|
+| `AuthError` | 401 — key missing or invalid |
+| `PlanError` | 403 — endpoint not on your plan |
+| `NotFoundError` | 404 — no such record |
+| `RateLimitError` | 429 — `kind` is `"rate"` or `"quota"` |
+| `MarkbaseError` | anything else, including network failures (`status: 0`) |
+
+---
 
-Current limits are on the client after any call:
+## Rate limits and quota
+
+Per-minute limits and 5xx are **retried automatically** with backoff
+(`maxRetries`, default 2).
+
+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
+your retries on a call that can't succeed.
+
+Live limits sit on the client after any call:
 
 ```ts
+await mb.search({ q: "nike" });
+
 mb.rateLimit;
-// { plan: "launch", rateLimit: 120, rateRemaining: 119,
-//   quotaLimit: 50000, quotaRemaining: 49873, quotaResetsAt: Date }
+// {
+//   plan: "launch",
+//   rateLimit: 120, rateRemaining: 119,
+//   quotaLimit: 50000, quotaRemaining: 49873,
+//   quotaResetsAt: Date
+// }
+```
+
+Useful for backing off before you hit the wall:
+
+```ts
+if (mb.rateLimit && mb.rateLimit.quotaRemaining !== null && mb.rateLimit.quotaRemaining < 100) {
+  console.warn("Nearly out of quota this month");
+}
 ```
 
+---
+
 ## Options
 
-| Option | Default | |
-|---|---|---|
-| `apiKey` | `MARKBASE_API_KEY` | `null` forces keyless |
-| `baseUrl` | `https://api.markbase.co` | |
-| `timeout` | `30000` | ms before abort |
-| `maxRetries` | `2` | rate limits and 5xx |
-| `fetch` | global `fetch` | inject your own |
+```ts
+new Markbase({
+  apiKey: process.env.MARKBASE_API_KEY, // null forces the keyless tier
+  baseUrl: "https://api.markbase.co",
+  timeout: 30_000,                       // ms before abort
+  maxRetries: 2,                         // rate limits and 5xx
+  fetch: customFetch,                    // inject your own
+});
+
+new Markbase("mb_your_key"); // shorthand
+```
+
+`apiKey` falls back to `MARKBASE_API_KEY`. Pass `null` to force keyless even
+when that variable is set.
+
+---
+
+## TypeScript
+
+Ships with declarations — no `@types` package needed.
+
+```ts
+import type {
+  Trademark, SearchResult, ClearanceResult, ClearanceMatch,
+  MarkStatus, RiskLevel, NiceClass, RateLimitInfo,
+} from "@radsoft/markbase";
+
+function render(m: ClearanceMatch): string {
+  return `${m.word_mark} — ${m.risk} risk (${m.similarity})`;
+}
+```
+
+---
 
 ## Not legal advice
 
-Clearance returns a first-pass screening signal over the federal register. It
+Clearance returns a **first-pass screening signal** over the federal register. It
 does not cover state trademarks, common-law rights, or the legal analysis of
-likelihood of confusion. Treat a clean result as "worth pursuing", not
-"cleared", and talk to a trademark attorney before adopting a name.
+likelihood of confusion — no API does.
+
+Treat a clean result as *worth pursuing*, not *cleared*, and put a trademark
+attorney at the end of the funnel for any name you actually intend to adopt.
+
+---
 
 ## Also available
 
-- **[@radsoft/markbase-mcp](https://www.npmjs.com/package/@radsoft/markbase-mcp)** — MCP server, so an AI assistant can screen names directly
-- **[API docs](https://api.markbase.co/docs)** · **[OpenAPI spec](https://api.markbase.co/openapi.json)**
+- **[@radsoft/markbase-mcp](https://www.npmjs.com/package/@radsoft/markbase-mcp)** — MCP server, so Claude and other assistants can screen names directly
+- **[API docs](https://api.markbase.co/docs)** · **[OpenAPI spec](https://api.markbase.co/openapi.json)** · **[Trademark classes](https://markbase.co/trademark-classes)**
 
 ## License
 

package/package.json

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