@tangle-network/hub-sdk

Typed SDK for the Tangle Hub /v1/hub/* surface. Status, connections, tools discovery and invocation, capability tokens, policies, approvals, audit.

Install

pnpm add @tangle-network/hub-sdk

Quick start

import { HubClient } from "@tangle-network/hub-sdk";

const hub = HubClient.fromEnv();
const { principal, connections } = await hub.status();

HubClient.fromEnv() reads everything it needs from environment variables. SaaS vs on-prem flips via env only — there is no per-client default URL.

Environment variables

| Variable | Required | Meaning | | ------------------------------ | -------- | --------------------------------------------------------------------------------------------- | | TANGLE_HUB_URL | Yes | Hub root URL. Either the platform root (https://api.tangle.tools) or the full Hub URL including /v1/hub — both are accepted; the SDK normalizes. | | TANGLE_API_KEY | One of | Long-lived API key (Bearer). User / API key principal. | | TANGLE_HUB_CAPABILITY_TOKEN | One of | Short-lived capability token (Bearer). Sandbox-runtime principal. Auto-minted server-side per action. |

The two auth credentials are mutually exclusive — set exactly one. This mirrors the platform-api hubSandboxEnvironmentSchema rule (exactly-one-api-key-or-capability-token).

Examples

SaaS:

export TANGLE_HUB_URL=https://api.tangle.tools
export TANGLE_API_KEY=sk-tan-...

On-prem:

export TANGLE_HUB_URL=https://hub.acme.internal
export TANGLE_API_KEY=sk-tan-...

Inside a sandbox (capability-token principal):

export TANGLE_HUB_URL=https://api.tangle.tools/v1/hub
export TANGLE_HUB_CAPABILITY_TOKEN=hubcap_...

Fail-loud configuration

HubClient.fromEnv() (and the standalone resolvers resolveHubBaseUrl() / resolveHubAuth()) never default. Missing or malformed configuration throws HubSdkError synchronously, before any request is issued:

| Code | Cause | | --------------------- | -------------------------------------------------------------------------------- | | HUB_CONFIG_MISSING | TANGLE_HUB_URL unset/empty, or neither auth credential is set. | | HUB_CONFIG_INVALID | TANGLE_HUB_URL is not a valid URL, or both auth credentials are set. |

try {
  const hub = HubClient.fromEnv();
} catch (error) {
  if (error instanceof HubSdkError && error.code === "HUB_CONFIG_MISSING") {
    // Surface the missing env var to the operator. Do not retry, do not default.
  }
  throw error;
}

This matches the repository's "No fallbacks. Fail loud." doctrine: required config has no silent default.

Bypassing env auth resolve

Pass apiKey or authHeaders explicitly to skip the auth-env-var check (useful when credentials come from a vault, OIDC exchange, or a custom session token). TANGLE_HUB_URL is still required.

const hub = HubClient.fromEnv({
  apiKey: await vault.read("hub/api-key"),
});

const hub = HubClient.fromEnv({
  authHeaders: async () => ({ Authorization: `Bearer ${await sessionToken()}` }),
});

Constructing without env vars

new HubClient({...}) remains supported for callers that resolve config themselves (CLI flags, web app config, tests). fromEnv is sugar with a fail-loud contract on top.

const hub = new HubClient({
  baseUrl: "https://api.tangle.tools",
  apiKey: "sk-tan-...",
});

Browsers, Workers, edge runtimes

fromEnv() reads globalThis.process?.env — undefined in browsers and many edge runtimes. Pass an explicit env map there:

const hub = HubClient.fromEnv({
  env: {
    TANGLE_HUB_URL: import.meta.env.VITE_TANGLE_HUB_URL,
    TANGLE_API_KEY: await session.apiKey(),
  },
  fetch: globalThis.fetch,
});

Exports

• HubClient, HubClient.fromEnv(options?)
• HubConnectionsClient, HubPermissionsClient, HubTokensClient, HubToolsClient, HubApprovalsClient, HubAuditClient
• HubSdkError — typed code: HubErrorCode, redacted details, optional HTTP status
• HUB_URL_ENV_VAR, HUB_API_KEY_ENV_VAR, HUB_CAPABILITY_TOKEN_ENV_VAR — string constants for the env-var names (mirrored by the platform-api hub-sandbox-contract.ts z.literal(...))
• resolveHubBaseUrl(env?), resolveHubAuth(env?) — standalone resolvers with the same fail-loud contract as fromEnv
• All request/response types from the /v1/hub/* contract