HVAKR SDK for TypeScript/JavaScript

A simple and easy to use client for the HVAKR API.

[!WARNING] Unstable API. HVAKR is pre-1.0 (v0). Response shapes, method arguments, and exported types may change in any release while we iterate. We do not maintain older versions in parallel — when we ship a breaking change, everyone upgrades.

Breaking changes ship in minor version bumps (0.x.0); patches (0.x.y) are backwards-compatible fixes. Pin an exact version (e.g. @hvakr/[email protected]) if you need stability, and read the CHANGELOG before upgrading.

Installation

npm install @hvakr/client

Usage

[!NOTE] You can get an access token from HVAKR with a Professional or Enterprise license at HVAKR -> Settings -> Access Tokens

Import and initialize a client using an access token.

import { HVAKRClient } from '@hvakr/client'

// Initializing a client
const hvakr = new HVAKRClient({
    accessToken: process.env.HVAKR_ACCESS_TOKEN,
    version: 'v0',
})

Make a request to any HVAKR API endpoint.

const { projects } = await hvakr.listProjects()

[!NOTE] See the complete list of endpoints in the API reference.

Each method returns a Promise that resolves the response.

console.log(projects)

;[
    {
        id: '5c6a2821-6bb1-4a7e-b6e1-c50111515c3d',
        name: 'Office Retrofit',
        number: '2024-014',
        address: 'Mansfield, TX, USA',
        status: 'inProgress',
        projectType: 'commercial',
        timestamp: 1714405200000,
        lastOpenTime: 1717084800000,
    },
    // ...
]

listProjects() is paginated. Pass limit to control the page size, and follow nextCursor while hasMore is true to page through every project.

const allProjects = []
let cursor: string | undefined

while (true) {
    const page = await hvakr.listProjects({ limit: 50, cursor })
    allProjects.push(...page.projects)
    if (!page.hasMore || !page.nextCursor) break
    cursor = page.nextCursor
}

Handling errors

If the API returns an unsuccessful response, the returned Promise rejects with a HVAKRClientError.

The error contains a message with the HTTP status code and optional metadata with additional details from the response.

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

try {
    const hvakr = new HVAKRClient({
        accessToken: process.env.HVAKR_ACCESS_TOKEN,
    })
    const project = await hvakr.getProject(projectId)
} catch (error) {
    if (error instanceof HVAKRClientError) {
        console.error('API Error:', error.message)
        console.error('Details:', error.metadata)
    } else {
        // Other error handling code
        console.error(error)
    }
}

Client options

The HVAKRClient supports the following options on initialization. These options are all keys in the single constructor parameter.

| Option | Default value | Type | Description | | ------------- | ------------------------- | -------- | -------------------------------------------------------------------------------------- | | accessToken | — | string | Required. Access token for authentication. Obtain from your HVAKR account. | | baseUrl | "https://api.hvakr.com" | string | The root URL for sending API requests. This can be changed to test with a mock server. | | version | "v0" | string | The API version to use. |

Version reporting

The client sends its version to the API on every request (X-HVAKR-Client: hvakr-client-ts/<version>). If your installed version is behind the minimum the API still supports, the response carries an X-HVAKR-Client-Warning header and the client logs a one-time console.warn telling you to upgrade — useful because breaking changes ship in minor bumps (see Versioning & stability).

API Reference

Projects

| Method | Description | | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | listProjects({ limit?, cursor?, search?, status?, projectType? }) | List a page of projects accessible to the authenticated user. Page with nextCursor while hasMore. Optional search (name/number/address), status, and projectType filters | | getProject(id, expand?) | Get a project by ID. Set expand: true for full project data, or pass an array of subcollection keys (e.g. ['spaces', 'zones', 'exports']) to expand only those | | createProject(data, opts?) | Create a new project | | updateProject(id, data, opts?) | Update an existing project | | deleteProject(id) | Delete a project | | getProjectCalculations(id, { include? }) | Run the calculator and return the requested sections (loads, register_schedule, dryside_graph, ventilation, equipment, checksums, airflows). Omit include for all. |

Project reads include every canonical project field, including server-owned state. The exported Zod schemas mark fields that normal project writes cannot change with disableUserWrite: true; fields without that metadata are writable by default. Create and patch schemas apply that policy recursively, including inside spaces, type collections, weather data, and sheet files. Exports remain job-created, and uploaded sheet-file data is read-only except for sheetFiles[id].name in project patches.

Projects can also store flat, user-writable metadata for external-system linking and application-specific context. Metadata values may be strings, numbers, or booleans; nested objects and arrays are intentionally excluded. Set an individual metadata key to null in updateProject to delete it.

Jobs

| Method | Description | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | createJob(id, body, opts?) | Create a job (export, auto-group, check, or auto-takeoff). Sync jobs return status: "completed"; async jobs return queued | | getJob(id, jobId) | Get a job's current state. Poll async jobs until status leaves queued/running |

Create PDF/CSV/ZIP output with an export job. definition accepts load-calculation, basis-of-design, ventilation-csv, or hourly-loads-csv:

let job = await hvakr.createJob(projectId, {
    type: 'export',
    definition: 'load-calculation',
    name: 'Issued Loads Export',
})

while (job.status === 'queued' || job.status === 'running') {
    await new Promise((resolve) => setTimeout(resolve, 1_000))
    job = await hvakr.getJob(projectId, job.jobId)
}

if (job.type === 'export' && job.status === 'completed') {
    console.log(job.result?.export?.downloadUrl)
}

Sheet files

| Method | Description | | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | createSheetFile(id, { file, fileName, name? }) | Upload one PDF (up to 30 MiB) and receive a multipart-only sheet-upload job. Poll it with getJob; name is display-only. |

const upload = await hvakr.createSheetFile(
    projectId,
    { file: pdfBytes, fileName: 'A-Plans.pdf', name: 'Architectural Plans' },
    { idempotencyKey: crypto.randomUUID() }
)

let job = upload
while (job.status === 'queued' || job.status === 'running') {
    await new Promise((resolve) => setTimeout(resolve, 1_000))
    job = await hvakr.getJob(projectId, job.jobId)
}

if (job.type === 'sheet-upload' && job.status === 'completed') {
    if (!job.result?.readyForTakeoff) {
        // Patch project.sheets to place an eligible page, then poll again.
    } else {
        await hvakr.createJob(projectId, { type: 'auto-takeoff' })
    }
}

auto-takeoff remains project-wide: it processes all active placed sheets and eligible maps, not only pages from this upload.

Products

| Method | Description | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | listProducts({ search?, limit?, cursor? }) | List a page of products accessible to the authenticated user (read-only). Page with nextCursor while hasMore. Filter by search | | getProduct(id) | Get a single product by ID |

Like listProjects, listProducts is paginated — it returns { products, hasMore, nextCursor }; page with nextCursor while hasMore.

Equipment modes and calculations

Since 0.6.0, projects use a shared equipmentModes registry. As of 0.10.0, central and terminal equipment live in a top-level equipment subcollection rather than under systems[id].equipmentConfig / zones[id].equipmentConfig. Each equipment document carries a required projectScope binding it to the system or zone it configures; the equipment document id is independent of the referenced system/zone id:

import {
    ComponentTypes_v0,
    DEFAULT_COOLING_MODE_ID_v0,
    OutsideAirMethods_v0,
} from '@hvakr/client'

const project = {
    systems: { 'system-1': { name: 'AHU-1', configured: true } },
    zones: {
        'zone-1': { name: 'VAV-1', configured: true, systemId: 'system-1' },
    },
    equipment: {
        'equipment-ahu-1': {
            projectScope: { type: 'system', id: 'system-1' },
            components: [
                { id: 'oa', type: ComponentTypes_v0.OUTSIDE_AIR_INTAKE },
            ],
            componentConfigsByMode: {
                [DEFAULT_COOLING_MODE_ID_v0]: {
                    oa: {
                        enabled: true,
                        configuration: {
                            componentType: ComponentTypes_v0.OUTSIDE_AIR_INTAKE,
                            method: OutsideAirMethods_v0.SUM_OF_SPACES,
                        },
                    },
                },
            },
            // Central dimensions (length/width) and terminal inlet size share
            // one `dimensionData` shape; energy config is optional.
            dimensionData: { length: 60, width: 30 },
            energyConfiguration: { efficiency: { coolingSeer: 14 } },
        },
        'equipment-vav-1': {
            projectScope: { type: 'zone', id: 'zone-1' },
            dimensionData: { inletSize: '8' },
        },
    },
}

Patch semantics apply to equipment documents: send a partial document to update fields, set a nested optional field to null to clear it, and set equipment[id] = null to delete an entire document. Requesting equipment through getProject(id, ['equipment']) expands the subcollection.

Space design overrides live under designAirflowsByMode; ventilation and infiltration requirements live under airflowRequirementsByLoadCondition. Calculation sections remain selectable with include, while airflow, checksum, and equipment results are keyed by the project's mode ids.

See the 0.10.0 migration notes for the equipmentConfig → equipment mapping. The API path remains /v0.

Account

| Method | Description | | ------ | ------------------------------------------------------------------------------------------------------------------------------------ | | me() | Return the authenticated caller's identity, organization memberships, plan, and rate-limit budget. A good first call to confirm auth |

Write methods (createProject, updateProject, createJob, createSheetFile) accept an optional opts argument with an idempotencyKey — retrying a request with the same key returns the original result instead of performing the action twice.

Receiving webhooks

HVAKR can deliver real-time event notifications to an HTTPS endpoint you control. Each request includes an X-HVAKR-Event header and is signed with HMAC-SHA256 in the X-HVAKR-Signature header using a secret you receive when the webhook is created. Use constructWebhookEvent to verify the signature and parse the event in one step.

import { constructWebhookEvent, HVAKRWebhookError } from '@hvakr/client'

// Express example. Use a raw-body parser so the signature still matches —
// re-stringifying a parsed object will change the bytes.
app.post(
    '/webhooks/hvakr',
    express.raw({ type: 'application/json' }),
    (req, res) => {
        try {
            const event = constructWebhookEvent({
                payload: req.body, // Buffer of the raw bytes
                signature: req.header('X-HVAKR-Signature')!,
                secret: process.env.HVAKR_WEBHOOK_SECRET!,
            })

            switch (event.event) {
                case 'project.created':
                    console.log('New project:', event.data.id)
                    break
                case 'opportunity.created':
                    console.log('New opportunity:', event.data.email)
                    break
            }

            res.status(204).end()
        } catch (err) {
            if (err instanceof HVAKRWebhookError) {
                return res.status(400).send(err.message)
            }
            throw err
        }
    }
)

By default, constructWebhookEvent only accepts event types and payload shapes that this SDK version knows about, so TypeScript can narrow event.data safely inside each case. If you need forward compatibility with newer event types, pass allowUnknownEvents: true and validate event.data yourself for unknown events.

constructWebhookEvent throws HVAKRWebhookError when the signature is invalid, the payload is malformed, the event payload does not match the expected schema, or the timestamp is outside a 300-second tolerance window (configurable via the tolerance option).

See the API reference for the current API documentation.

TypeScript

This SDK is written in TypeScript and includes full type definitions. All API responses are typed using Zod schemas.

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

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

// TypeScript knows this is ExpandedProject_v0
const project = await hvakr.getProject('project-id', true)

See Also

• hvakr-python - HVAKR SDK for Python

Versioning & stability

This SDK is pre-1.0 and the API it wraps is still evolving. We deliberately stay on 0.x so we can move quickly, and we follow the SemVer 0.x convention:

| Bump | Example | Meaning | | ----------------- | ------------------- | --------------------------------------------------------------------------- | | Minor 0.x.0 | 0.1.16 → 0.2.0 | Breaking change — response shapes, arguments, or exported types changed | | Patch 0.x.y | 0.1.16 → 0.1.17 | Backwards-compatible fix or addition |

We do not version the API path beyond v0 or run multiple API versions in parallel. There is one current version; breaking changes apply to everyone. When the API surface stabilizes, we will cut a 1.0.0 release and adopt standard SemVer guarantees.

What this means for you:

• Every breaking change is documented under its version in the CHANGELOG.
• If you depend on stability, pin an exact version (@hvakr/[email protected]) rather than a range, and upgrade deliberately after reading the changelog.
• A default caret range (^0.1.0) will not auto-upgrade you across a breaking minor bump, so you stay on a compatible line until you opt in.

Contributing

See CONTRIBUTING.md for development setup and contribution guidelines.

Getting help

If you want to submit a feature request or are experiencing any issues with the API, please contact HVAKR support at [email protected]