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','reports']. Expanded reports come back in the public report 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 OWNER role)

All write methods accept opts.idempotencyKey, sent as the Idempotency-Key header.

Revit ingestion

• createProjectFromRevit(revitData, opts?) — create a project from a Revit plugin payload
• updateProjectFromRevit(id, revitData, opts?) — merge a Revit payload into a project (imports new Revit spaces)

Calculations

• getProjectCalculations(id, { include? }) — run the calculator once and return the requested sections. include is any of loads, register_schedule, dryside_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, report, or auto-takeoff. auto-group/check run synchronously and return status: "completed" with a result; report/auto-takeoff return status: "queued".
• getJob(id, jobId) — poll a job; report/auto-takeoff jobs settle from queued/running to completed/failed. A report job’s result carries the linked report (with downloadUrl once complete).

Products

• listProducts({ search?, limit?, cursor? }) — accessible catalog products (organization + public), paginated like listProjects (page with nextCursor while hasMore); optional case-insensitive search over name/manufacturer/model
• getProduct(id) — a single catalog product

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'],
    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/.