# @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](https://docs.buildcalcapi.dev/docs/sdks/compatibility).
- **Generator**: [openapi-typescript-codegen](https://github.com/ferdikoomen/openapi-typescript-codegen).

## Installation

```bash
# 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

```typescript
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`:

```typescript
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:

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

## Build + test

```bash
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/workflows/regenerate-sdks.yml)
GitHub Action whenever `docs/openapi.json` changes on `main`.

Manual local regenerate:

```bash
cd sdks/typescript
npm run regenerate
```

## License

MIT. See [LICENSE](../../LICENSE) at repo root.