HVAKR SDK for TypeScript/JavaScript

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

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)

{
    ids: [
        '5c6a2821-6bb1-4a7e-b6e1-c50111515c3d',
        '897e5a76-ae52-4b48-9fdf-e71f5945d1af',
        // ...
    ]
}

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() | List all project IDs accessible to the authenticated user | | 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 |

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

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]