SDK Constants

@warmhub/sdk-ts exports a handful of named constants for use in your own code. This page collects the public ones in one place: each value, what it governs, and which surface consumes it. Every constant below imports from the package entry point:

import { DEFAULT_API_URL, MAX_CONTENT_FIELD_BYTES } from '@warmhub/sdk-ts';

Quick reference

Constant	Value	What it’s for
SDK_VERSION	semver of the installed package	Diagnostics and version gating
DEFAULT_API_URL	"https://api.warmhub.ai"	The API base URL a client uses when you pass no apiUrl
MAX_CONTENT_FIELD_BYTES	65536 (64 KiB)	The byte cap on a single content field
CONTENT_FIELD_LIMIT_ERROR	explanation string	The message appended when a content field exceeds the cap
CLI_INSTALL_REPO_HEADER	"X-WarmHub-Install-Repo"	Identifies the install on a component CLI call
CLI_SIGNATURE_HEADER	"X-WarmHub-Signature"	Carries the HMAC signature on a signed CLI call
CLI_TIMESTAMP_HEADER	"X-WarmHub-Timestamp"	Carries the signing timestamp on a signed CLI call
REPO_AUTH_SCOPES	array of repo scope strings	Known members of the repo:* scope vocabulary
ORG_AUTH_SCOPES	array of org scope strings	Known members of the org:* scope vocabulary

SDK_VERSION

export const SDK_VERSION: string;

The semantic version string of the installed @warmhub/sdk-ts package. Use it when reporting a bug or when a shared utility needs to gate behaviour on a minimum SDK version.

import { SDK_VERSION } from '@warmhub/sdk-ts';

console.log(`WarmHub SDK ${SDK_VERSION}`);

DEFAULT_API_URL

export const DEFAULT_API_URL = 'https://api.warmhub.ai';

The base URL a WarmHubClient targets when you construct it without an explicit apiUrl. The two clients below are equivalent:

import { WarmHubClient, DEFAULT_API_URL } from '@warmhub/sdk-ts';

const client = new WarmHubClient({ accessToken: '...' });
const explicit = new WarmHubClient({ accessToken: '...', apiUrl: DEFAULT_API_URL });

Pass a different apiUrl to point at a self-hosted gateway, a staging environment, or a local proxy.

MAX_CONTENT_FIELD_BYTES

export const MAX_CONTENT_FIELD_BYTES = 65_536; // 64 KiB

The maximum UTF-8 byte length of a single content field on a thing. The API enforces this cap on every write. The SDK also checks it client-side before sending when you set repository README or AGENTS content through client.repo.setReadme and client.repo.setAgents — those methods throw before the request leaves your process, so you catch oversized content one round-trip earlier.

Use the constant to pre-validate content in your own code:

import { MAX_CONTENT_FIELD_BYTES } from '@warmhub/sdk-ts';

function withinLimit(text: string): boolean {
  return new TextEncoder().encode(text).byteLength <= MAX_CONTENT_FIELD_BYTES;
}

Note

Content fields are for compact, queryable values. Keep large payloads in S3, Box, Drive, or another document system and reference them from WarmHub.

CONTENT_FIELD_LIMIT_ERROR

export const CONTENT_FIELD_LIMIT_ERROR: string;

A human-readable explanation of the MAX_CONTENT_FIELD_BYTES cap. It is the trailing segment of the validation error message — when client.repo.setReadme or client.repo.setAgents rejects oversized content, the SDK throws a WarmHubError whose code is 'VALIDATION_ERROR' and whose message is Field "<path>" is <n> bytes; <CONTENT_FIELD_LIMIT_ERROR>.

Match on the error code, and use the constant as a substring check rather than an exact comparison. eventRequestId is required; mint a fresh one per write intent, but reuse the same value when retrying an ambiguous outcome — see Streaming Write Failures.

import { CONTENT_FIELD_LIMIT_ERROR, WarmHubError } from '@warmhub/sdk-ts';

try {
  await client.repo.setReadme('my-org', 'my-repo', readme, {
    eventRequestId: crypto.randomUUID(),
  });
} catch (err) {
  if (
    err instanceof WarmHubError &&
    err.code === 'VALIDATION_ERROR' &&
    err.message.includes(CONTENT_FIELD_LIMIT_ERROR)
  ) {
    console.error('README is too large — trim it before writing it.');
  } else {
    throw err;
  }
}

CLI request headers

export const CLI_INSTALL_REPO_HEADER = 'X-WarmHub-Install-Repo';
export const CLI_SIGNATURE_HEADER = 'X-WarmHub-Signature';
export const CLI_TIMESTAMP_HEADER = 'X-WarmHub-Timestamp';

HTTP header names for the authenticated CLI calls the WarmHub platform dispatches to a component Worker. CLI_INSTALL_REPO_HEADER always rides along to identify the install being served; when the install configures HMAC signing — a keyed hash that lets the Worker confirm a request came from WarmHub and was not altered in transit — CLI_SIGNATURE_HEADER and CLI_TIMESTAMP_HEADER carry the signature and its timestamp.

Most Workers verify these requests with verifyCliCall, which reads the headers for you. Import the names directly only when you build middleware — a proxy or gateway — that inspects or forwards the headers itself:

import {
  CLI_INSTALL_REPO_HEADER,
  CLI_SIGNATURE_HEADER,
  CLI_TIMESTAMP_HEADER,
} from '@warmhub/sdk-ts';

REPO_AUTH_SCOPES

export const REPO_AUTH_SCOPES: readonly [
  'repo:read',
  'repo:checkpoint-read',
  'repo:checkpoint-generate',
  'repo:write',
  'repo:configure',
  'repo:admin',
  'repo:action-callback',
];

An as const tuple of every known repo:* scope string that @warmhub/sdk-ts is aware of at the time the package was published. The members correspond to the repo permissions you can assign when creating a personal access token — see Access Reference for what each scope grants.

import { REPO_AUTH_SCOPES } from '@warmhub/sdk-ts';

// Members:
// 'repo:read'
// 'repo:checkpoint-read'
// 'repo:checkpoint-generate'
// 'repo:write'
// 'repo:configure'
// 'repo:admin'
// 'repo:action-callback'

Use REPO_AUTH_SCOPES to enumerate or validate known scopes in tooling — for example, building a token-creation UI or asserting that a token carries the scopes your component requires. Note that access-check responses (see client.access) may include newer scope strings that are not yet present in this tuple; token creation and other requested-scope inputs are validated against a fixed set, so you should not infer that arbitrary future values are accepted there.

import { REPO_AUTH_SCOPES } from '@warmhub/sdk-ts';

const required = ['repo:read', 'repo:write'];
const unknown = required.filter(s => !REPO_AUTH_SCOPES.includes(s));
if (unknown.length) {
  console.warn('Scopes not in known list:', unknown);
}

ORG_AUTH_SCOPES

export const ORG_AUTH_SCOPES: readonly [
  'org:read',
  'org:configure',
  'org:admin',
  'org:action-callback',
];

An as const tuple of every known org:* scope string that @warmhub/sdk-ts is aware of at the time the package was published. The members correspond to the org permissions you can assign when creating a personal access token — see Access Reference for what each scope grants.

import { ORG_AUTH_SCOPES } from '@warmhub/sdk-ts';

// Members:
// 'org:read'
// 'org:configure'
// 'org:admin'
// 'org:action-callback'

Like REPO_AUTH_SCOPES, this tuple covers the known vocabulary at publish time. Access-check responses (see client.access) may include newer scope strings that are not yet present in this tuple; token creation and other requested-scope inputs are validated against a fixed set, so you should not infer that arbitrary future values are accepted there. Use ORG_AUTH_SCOPES for enumeration and validation in tooling, not as a runtime allowlist.

import { ORG_AUTH_SCOPES } from '@warmhub/sdk-ts';

const required = ['org:read'];
const unknown = required.filter(s => !ORG_AUTH_SCOPES.includes(s));
if (unknown.length) {
  console.warn('Scopes not in known list:', unknown);
}