SDK Constants

@warmhub/sdk-ts exports a handful of named constants for use in your own code. This page covers a selection of the public ones: each value, what it governs, and which surface consumes it. For every exported constant, type, and narrowing helper, see the TypeScript SDK reference landing page. 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
MAX_WREFS_PER_THING_VERSION	10000	The maximum number of wrefs allowed on a single thing version
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
GLOBAL_SEARCH_RESULT_ITEM_KINDS	tuple of kind strings	Known values for the global-search result kind field
HOMEPAGE_FEATURED_ITEM_KINDS	tuple of kind strings	Known values for the homepage featured-item kind field
COMPONENT_SUMMARY_STATES	tuple of state strings	Known values for the component summary state field

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;
  }
}

MAX_WREFS_PER_THING_VERSION

export const MAX_WREFS_PER_THING_VERSION = 10_000;

The maximum number of wrefs (write references) allowed on a single thing version. The API enforces this cap when a write is submitted. Use the constant to pre-validate the wref count in your own code before sending a write:

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

function wrefsWithinLimit(wrefs: unknown[]): boolean {
  return wrefs.length <= MAX_WREFS_PER_THING_VERSION;
}

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);
}

GLOBAL_SEARCH_RESULT_ITEM_KINDS

export const GLOBAL_SEARCH_RESULT_ITEM_KINDS: readonly ['repo', 'component'];

An as const tuple of the known values for the kind field on a global-search result item. Use it to enumerate or validate kind values in tooling that processes search results — for example, filtering results by type or asserting that a returned kind is one your code handles.

import {
  GLOBAL_SEARCH_RESULT_ITEM_KINDS,
  isKnownGlobalSearchResultItemKind,
} from '@warmhub/sdk-ts';

// Members:
// 'repo'
// 'component'

if (isKnownGlobalSearchResultItemKind(result.kind)) {
  // result.kind is narrowed to GlobalSearchResultItemKind here
}

The kind field on search results is open — the API may return values not yet present in this tuple. Treat unknown kind values gracefully rather than treating this tuple as an exhaustive allowlist; isKnownGlobalSearchResultItemKind narrows a value to GlobalSearchResultItemKind without assigning meaning to an unfamiliar one.

HOMEPAGE_FEATURED_ITEM_KINDS

export const HOMEPAGE_FEATURED_ITEM_KINDS: readonly ['repo', 'component', 'skill'];

An as const tuple of the known values for the kind field on a homepage featured item. Use it to enumerate or validate kind values in tooling that processes featured-item payloads.

import {
  HOMEPAGE_FEATURED_ITEM_KINDS,
  isKnownHomepageFeaturedItemKind,
} from '@warmhub/sdk-ts';

// Members:
// 'repo'
// 'component'
// 'skill'

if (isKnownHomepageFeaturedItemKind(item.kind)) {
  // item.kind is narrowed to HomepageFeaturedItemKind here
}

Like GLOBAL_SEARCH_RESULT_ITEM_KINDS, this tuple covers the known vocabulary at publish time. The API may return kind values not yet present here; use isKnownHomepageFeaturedItemKind to narrow a value to HomepageFeaturedItemKind and handle unknown values gracefully.

COMPONENT_SUMMARY_STATES

export const COMPONENT_SUMMARY_STATES: readonly ['initiated', 'active', 'uninstalled'];

An as const tuple of the known values for the state field on a component summary. Use it to enumerate or validate state values in tooling that processes component summaries — for example, building a status display or asserting that a returned state is one your code handles.

import {
  COMPONENT_SUMMARY_STATES,
  isKnownComponentSummaryState,
} from '@warmhub/sdk-ts';

// Members:
// 'initiated'
// 'active'
// 'uninstalled'

if (isKnownComponentSummaryState(summary.state)) {
  // summary.state is narrowed to ComponentSummaryState here
}

The state field is open — the API may return values not yet present in this tuple. Treat unknown state values gracefully rather than treating this tuple as an exhaustive allowlist; isKnownComponentSummaryState narrows a value to ComponentSummaryState without assigning meaning to an unfamiliar one.