SDK

Hubfly space SDKs

Two official client libraries — one for TypeScript, one for Go — that wrap a useful subset of the Hubfly space REST API in typed methods. Use the REST API directly for endpoints that are not exposed by the current SDK release.

The Dashboard OpenAPI document is the complete platform contract. The SDK repository exposes selected modules for projects, containers, load balancers, networking, ports, registry credentials, volumes, hibernation, organizations, domains, templates and basic GPU listing. The SDK surface is not a complete one-to-one mirror of the API.

Which SDK should I use?

Pick the one that matches the language you are already writing. If you need a newly added or specialized endpoint, use the API endpoint explorer to confirm the current path and request schema before adding a direct call.

TypeScript SDKTypeScript

@hubfly/sdk — full type definitions, promise-based, runs on Node.js, Bun, Deno, Cloudflare Workers and the browser.

Go SDKGo

hubfly-sdk/go — idiomatic client struct, context-aware requests, typed responses, standard library only.

Install

Both packages are dependency-free, so installing one adds exactly one entry to your lockfile.

TypeScript

npm install @hubfly/sdk
# or: bun add @hubfly/sdk
# or: pnpm add @hubfly/sdk

go get github.com/hubfly/hubfly-sdk/go

Your first call

Both clients read the HUBFLY_TOKEN environment variable when you do not pass a token explicitly. Create a personal access token in the console underSettings → Access tokens, export it, then list your projects:

TypeScript

import { HubflyClient } from '@hubfly/sdk';

const client = new HubflyClient();          // reads HUBFLY_TOKEN
const { data: projects } = await client.projects.list();

for (const project of projects) {
  console.log(project.id, project.name);
}

package main

import (
	"context"
	"fmt"
	"log"

	hubfly "github.com/hubfly/hubfly-sdk/go"
)

func main() {
	client := hubfly.NewClient() // reads HUBFLY_TOKEN

	projects, err := client.Projects.List(context.Background())
	if err != nil {
		log.Fatal(err)
	}

	for _, project := range projects.Data {
		fmt.Println(project.ID, project.Name)
	}
}

What the SDKs cover

These are the main areas represented by the current SDK packages. Themodule explorer shows selected helpers next to the REST endpoints they call, with copyable examples in either language where both packages expose the operation.

Area	What you can do
Projects	Create, list, inspect and delete projects; read and update environment variables.
Containers	List, inspect, create, delete and restart image-backed containers.
Load balancers	Create and delete balancers in both SDKs; the TypeScript package also exposes target and domain helpers.
Networking	TypeScript can inspect access, issue keys, manage firewall rules and read logs; Go currently exposes inspection helpers.
Ports	Reserve and remove ports in both SDKs; TypeScript also exposes map and unmap helpers.
Registry	TypeScript exposes registry credential, image and scan helpers; use the API directly for registry operations from Go.
Volumes	Provision persistent block storage and attach it to containers.
Hibernation	Preview the savings, hibernate a project and restore it.
GPU	List account-level GPU instances. GPU provisioning and project GPU operations are available through the API contract, not the current SDK convenience surface.

Feature parity

The two SDKs share response conventions, but their exposed method sets are not identical. Check the package source or the module explorer before assuming a TypeScript method has a Go equivalent.

Concern	TypeScript	Go
Authentication	`token` option, or `HUBFLY_TOKEN`	`WithToken()` option, or `HUBFLY_TOKEN`
Async model	Promises with `async`/`await`	Blocking calls that take a `context.Context`
Cancellation	Per-client timeout; no per-call signal option in the current public method signatures	`context.WithTimeout` and `context.WithCancel`
Errors	Throws `HubflyApiError`	Returns `*hubfly.APIError`
Runtimes	Node.js 18+, Bun, Deno, Cloudflare Workers, browsers	Go 1.20+
Dependencies	None — uses the built-in `fetch`	None — uses `net/http`

Versioning and spec drift

The API is versioned as v1. The SDK packages have their own package versions, but a package release does not guarantee that every current API operation has a typed helper.

The SDK repository includes a spec-diff verification script. Treat the generated Dashboard OpenAPI document as authoritative when a helper and an endpoint path disagree, and test a real request before putting a new helper into production.

make verify-spec   # run inside the hubfly-sdk repository

Tokens are as powerful as the account that issued them

A personal access token inherits the issuing user's access and can be further restricted by project and permission. Scope tokens to the narrowest set of permissions the job needs, keep them out of source control, and rotate them when someone leaves the team. SeeAPI authentication for how scopes and rotation work.