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. |

API Reference

Projects

| Method | Description | | ---------------------------------------- | ------------------------------------------------------------------------- | | listProjects({ limit?, cursor? }) | List a page of projects accessible to the authenticated user. Page with nextCursor while hasMore | | getProject(id, expand?) | Get a project by ID. Set expand: true for full project data | | createProject(data, revitPayload?) | Create a new project | | updateProject(id, data, revitPayload?) | Update an existing project | | deleteProject(id) | Delete a project | | getProjectOutputs(id, type) | Get calculated outputs (loads, dryside_graph, or register_schedule) |

Weather Stations

| Method | Description | | --------------------------------- | ------------------------------------- | | searchWeatherStations(lat, lng) | Find weather stations near a location | | getWeatherStation(id) | Get detailed weather station data |

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]