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
const loads = await client.getProjectOutputs('project-id', 'loads')

Methods

Projects

• listProjects() — list project summaries you can access
• getProject(id) / getProject(id, expand) — fetch a project; expand: true inlines all subcollections (spaces, zones, systems, types, graph, reports, …)
• createProject(data, revitPayload?) — create a project from an ExpandedProjectPost, or from a Revit payload when revitPayload is true
• updateProject(id, data, revitPayload?) — partial update; subcollections are deep-merged and a null value deletes a field
• deleteProject(id) — soft-delete (requires the OWNER role)

Calculator outputs

• getProjectOutputs(id, 'loads') — heating and cooling loads by space, zone, and system
• getProjectOutputs(id, 'register_schedule') — register/diffuser sizing schedule
• getProjectOutputs(id, 'dryside_graph') — duct graph with flow rates, sizes, and pressure drops

Weather

• searchWeatherStations(latitude, longitude) — IDs of the 5 nearest ASHRAE weather stations
• getWeatherStation(id) — ASHRAE design weather data for a station

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')
loads = client.get_project_outputs('project-id', '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/.