@buildcalcapi/sdk (TypeScript SDK)

Auto-generated TypeScript client for the BuildCalc API — a vertical construction-data API for AI agents and developers. Provides typed fetch-based access to all /v1/* endpoints across the five verticals (codes, calculators, costs, products, benchmarks).

• API docs: https://docs.buildcalcapi.dev
• API key: https://buildcalcapi.dev/dashboard
• Compatibility: SDK 0.2.x ↔ API 0.2.x. See compatibility matrix.
• Generator: openapi-typescript-codegen.

Installation

# Install from source (npm publish deferred until LLC formation closes)
npm install file:./path/to/sdks/typescript

# Or from a GitHub release tarball
npm install https://github.com/Nasty-Fury/buildcalc-api/releases/download/v0.2.1/buildcalcapi-sdk-0.2.1.tgz

npm install @buildcalcapi/sdk will go live once NF Nation LLC is formed and owns the package on npm.

Quickstart

import { OpenAPI, DataCodesService, DataCostsService } from "@buildcalcapi/sdk";

OpenAPI.BASE = "https://api.buildcalcapi.dev";
OpenAPI.HEADERS = { "X-API-Key": process.env.BUILDCALCAPI_API_KEY! };

// List code editions
const codes = await DataCodesService.listCodes();
console.log(codes.codes?.length, "codes available");

// Get an HVAC labor wage (Dallas MSA)
const labor = await DataCostsService.costsLaborGet({
  trade: "electrician",
  msa: "19100",
});
console.log("median:", labor.median_hourly_cents / 100, "USD/hr");

Authentication

The SDK uses a global OpenAPI config object. Set the X-API-Key header via OpenAPI.HEADERS:

OpenAPI.BASE = "https://api.buildcalcapi.dev";
OpenAPI.HEADERS = { "X-API-Key": process.env.BUILDCALCAPI_API_KEY! };

Or use OpenAPI.TOKEN + OpenAPI.USERNAME + OpenAPI.PASSWORD if you need different schemes (BuildCalc API does NOT currently support these; stick with X-API-Key).

Endpoint surface (as of 0.2.0)

107 endpoints organized into 20 services:

• DataCodesService — code sections (IRC, IBC, NEC, IECC, IPC, NEC 2026) + adoption matrix
• DataCostsService — Phase 6 costs vertical (PPI materials, OEWS+QCEW labor, BPS permits)
• DefaultService — discovery + meta + account + signup + billing + webhook
• CalcConcreteService, CalcLumberService, CalcRoofingService, CalcDrywallService, CalcPaintService, CalcFlooringService, CalcHvacService, CalcInsulationService, CalcMasonryService, CalcElectricalService, CalcPlumbingService, CalcDoorsWindowsService, CalcGuttersService, CalcStairsService, CalcSiteService, CalcMiscService, CalcMetaService — 17 per-category calculator services (16 categories + meta)

Every service method returns a CancelablePromise<T> where T is the typed response model.

Examples

See examples/:

• examples/get-codes.ts — list code editions + first 5 IRC 2021 sections

Run with:

export BUILDCALCAPI_API_KEY=your_key_here
npx ts-node examples/get-codes.ts

Build + test

npm install
npm run build  # produces dist/
npm test       # runs vitest smoke tests

Regeneration

This SDK is auto-generated. Do not edit files under src/ by hand — they will be overwritten on next regeneration. Customizations go in examples/, tests/, or this README.

Regeneration is triggered by the regenerate-sdks.yml GitHub Action whenever docs/openapi.json changes on main.

Manual local regenerate:

cd sdks/typescript
npm run regenerate

License

MIT. See LICENSE at repo root.