Client SDKs

HVAKR provides official client SDKs that wrap the v0 REST API so you don’t have to construct requests by hand.

Available SDKs

TypeScript / JavaScript

For Node.js and browser applications.

npm install @hvakr/client

Repository: https://github.com/flowcircuits/hvakr-client

Python

For Python applications and scripts.

pip install hvakr

Repository: https://github.com/flowcircuits/hvakr-python

TypeScript SDK

Basic usage

The client is constructed with an access token (created in Settings → Developer). All methods live directly on the client instance.

import { HVAKRClient } from '@hvakr/client'

const client = new HVAKRClient({ accessToken: process.env.HVAKR_ACCESS_TOKEN! })

// List the projects you can access
const { projects } = await client.listProjects()

// Fetch a single project (pass true to include all subcollections)
const project = await client.getProject('project-id')
const fullProject = await client.getProject('project-id', true)

// Run the calculator (one run; select sections with `include`)
const { loads } = await client.getProjectCalculations('project-id', {
    include: ['loads'],
})

Methods

Account

• me() — the authenticated caller: identity, organization memberships, plan, and per-minute rate-limit budget. A good first call to confirm the token and see what it can do.

Projects

• listProjects({ limit?, cursor?, search?, status?, projectType? }) — paginated project summaries; page with nextCursor while hasMore is true. search filters case-insensitively over name/number/address; status and projectType are exact filters
• getProject(id) / getProject(id, expand) — fetch a project; expand is true (all subcollections), or an array like ['spaces','zones','exports']. Expanded exports come back in the public export shape (id, status, downloadUrl when completed)
• createProject(data, opts?) — create a project from an ExpandedProjectPost
• updateProject(id, data, opts?) — partial update; subcollections are deep-merged and a null value deletes a field
• deleteProject(id) — soft-delete (requires the Admin or Owner role)

createProject, updateProject, createJob, and createSheetFile accept opts.idempotencyKey, sent as the Idempotency-Key header. The API only enforces it on the create methods, so those are the ones safe to retry — a repeated request with the same key replays the original response instead of repeating the action. updateProject’s key is accepted and sent but not yet enforced by the API, so retries there aren’t deduplicated. deleteProject has no opts parameter.

Calculations

• getProjectCalculations(id, { include? }) — run the calculator once and return the requested sections. include is any of loads, register_schedule, graph, ventilation, equipment, checksums, airflows; omit it for every section (the response can be large). Each requested section appears as a field on the result alongside errors and flags.

Jobs

• createJob(id, body, opts?) — create a job. body.type is auto-group, check, export, auto-takeoff, or auto-route. Export jobs also require body.definition (load-calculation, basis-of-design, ventilation-csv, or hourly-loads-csv). auto-group/check run synchronously and return status: "completed" with a result; export/auto-takeoff/auto-route return status: "queued".
• createSheetFile(id, { file, fileName, name? }, opts?) — upload one PDF (maximum 30 MiB) and receive a sheet-upload job. The upload filename remains the source identity; name is display-only.
• getJob(id, jobId) — poll a job; export/auto-takeoff/auto-route/sheet-upload jobs settle from queued/running to completed/failed. A completed sheet-upload job contains pages and readyForTakeoff; patch sheets if placement is needed, then run project-wide auto-takeoff.

Products

• searchProducts({ search?, type?, limit?, cursor? }) — search accessible catalog products (organization + public). Returns slim cards (id, name, manufacturer, model, type), paginated like listProjects (default limit 20, max 100; page with nextCursor while hasMore). Optional case-insensitive search over name/manufacturer/model; optional exact type (e.g. AIR_CLEANER) can be used alone to browse.
• getProduct(id) — a single catalog product (full specs)

Webhooks

The SDK ships a helper to verify and parse webhook payloads:

import { constructWebhookEvent } from '@hvakr/client'

const event = constructWebhookEvent({
    payload: rawRequestBody,
    signature: req.headers['x-hvakr-signature'] as string,
    secret: process.env.HVAKR_WEBHOOK_SECRET!,
})

Error handling

Failed requests throw an HVAKRClientError:

import { HVAKRClient, HVAKRClientError } from '@hvakr/client'

try {
    const project = await client.getProject('id')
} catch (error) {
    if (error instanceof HVAKRClientError) {
        // error.message describes the API response
    }
}

Python SDK

The Python client mirrors the same set of operations as the TypeScript client (in snake_case). See the repository for exact signatures.

import os
from hvakr import HVAKRClient

client = HVAKRClient(access_token=os.environ['HVAKR_ACCESS_TOKEN'])

projects = client.list_projects()
project = client.get_project('project-id')
calculations = client.get_project_calculations('project-id', include=['loads'])

Notes

• The SDK request/response types are the same *_v0 Zod schemas the API validates against, so the TypeScript client cannot drift from server-side validation.
• For the authoritative request/response shapes, see the live OpenAPI reference at https://api.hvakr.com/v0/docs/.