@tradeproof/sdk — TypeScript / JavaScript SDK

Official SDK for the TradeProof contractor-license API (/v1). Hand-written, fully typed, zero runtime dependencies, ESM + CommonJS, and isomorphic (browser + Node 18+, built on the global fetch and Web Crypto).

npm install @tradeproof/sdk

Quickstart

import { TradeProof } from "@tradeproof/sdk";

const client = new TradeProof({ apiKey: "tp_read_..." });

const results = await client.licenses.search("roofing contractors in texas", { limit: 5 });
for (const hit of results.hits) {
  console.log(hit.license_number, hit.business_name, hit.state);
}

const record = await client.licenses.get("TX", "tdlr", "ABC123");
console.log(record.status, record.expiration_date);

See examples/quickstart.ts.

MVP scope — these features only

This is the 0.1.0 MVP. It intentionally covers a small, stable surface and nothing else:

• Authentication — API key (tp_...) or JWT bearer token; both sent as Authorization: Bearer.
• License lookup — client.licenses.get(...), .lookup(...), .search(...), .list(...), .coverage().
• Watchlist CRUD — client.watchlist.list() / .add() / .remove() (org-scoped; also needs internalAuthToken).
• Webhook subscription CRUD — client.webhooks.create() / .list() / .get() / .update() / .delete().
• HMAC signature verification — verify(body, signature, secret) for the X-TradeProof-Signature header on inbound webhooks.

Everything else in the API (billing, audits, insurance/COI, notifications, Procore, admin) is out of scope for the MVP and lands in later minor releases.

Authentication

new TradeProof({ apiKey: "tp_read_..." });            // programmatic API key
new TradeProof({ bearerToken: "<jwt>" });             // OIDC/JWT bearer
new TradeProof({ apiKey: "tp_...", internalAuthToken: "..." }); // org-scoped (watchlist)

Webhook signature verification (HMAC)

verify() is the cryptographic primitive that authenticates a webhook body — it confirms the payload was signed with your subscription secret and is within the replay-tolerance window. It is async (Web Crypto) and does not assert anything about a contractor.

import { verify } from "@tradeproof/sdk/hmac"; // tree-shaken subpath: HMAC only, no HTTP client

const ok = await verify(rawBody, req.headers["x-tradeproof-signature"], secret);
if (!ok) res.status(400).end();

The signature is t=<unix>,v1=<hex> where v1 = HMAC-SHA256(secret, + "${t}.${body}" + ); during secret rotation several v1= values may be present and any valid one is accepted.

Bundle size & tree-shaking

The package is sideEffects: false with per-feature subpath entry points, so a browser webhook receiver that imports only @tradeproof/sdk/hmac ships just the HMAC primitive (well under the 30 KB minified+gzipped budget) without pulling in the HTTP client.

Errors & retries

Non-2xx responses reject with typed errors (NotFoundError, AuthenticationError, RateLimitError, ...), all subclasses of APIError. The client automatically retries on 429 (honouring Retry-After) and 5xx, up to maxRetries (default 2).

Roadmap to 1.0

| Milestone | Adds | | --- | --- | | 0.2.0 | Auto-pagination async iterators, request/response hooks | | 0.3.0 | Insurance/COI + audit-report read surfaces | | 0.4.0 | Notifications + billing read surfaces | | 1.0.0 | Full /v1 coverage, frozen public surface, stability commitment |

Versioning & stability

Pre-1.0 the SDK follows tight semantic-versioning discipline so you can pin safely:

• 0.1.x — bug-fix patches only; no breaking changes.
• 0.2.0, 0.3.0, ... — additive minor releases; existing calls keep working.
• 1.0.0 — the stability commitment: the public surface is frozen and any future breaking change ships with a 12-month deprecation window and a migration note.

Until 1.0.0, pin a minor range (e.g. "@tradeproof/sdk": "~0.1.0").

License

Apache-2.0.