Client Surfaces

The WarmHubClient organizes API calls into typed surfaces accessed as properties on the client instance. This page explains what each surface is for. The generated WarmHubClient API reference is the reference for method signatures and per-method descriptions.

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

const client = new WarmHubClient({
  auth: { getToken: async () => process.env.WH_TOKEN },
})

const orgs = await client.org.list()
const head = await client.thing.head('acme', 'world')

All methods return promises. Most methods throw WarmHubError on failure. Methods that submit operations through the streaming write pipeline (client.commit.apply() and OperationBuilder.commit()) may instead throw PartialStreamSubmissionError for ambiguous append outcomes or AllStreamOperationsFailedError when every submitted operation is rejected with per-op failure data. See SDK Overview for how to create a token and full client setup.

Navigating the reference

The generated WarmHubClient page renders all 15 surfaces and ~100 methods inline (~3,400 lines). Jump straight to a surface anchor (#auth, #commit, #thing, …) rather than scrolling. Agents fetching the markdown can also use /sdk-reference/classes/warmhubclient.md and grep for the surface name; /llms.txt lists every method by surface.

Constructor Options

Most callers construct the client with an auth.getToken provider or an accessToken value. apiUrl is only needed for non-default deployments, and fetch is mainly for custom runtimes or tests.

See WarmHubClientOptions for the exact option type.

client.auth

Authentication helpers support browser sign-in flows, session sync, current-user lookup, and token diagnostics. Use this surface when an app needs to initialize browser auth or inspect the identity behind the current request.

Reference: WarmHubClient.auth. CLI counterpart: wh auth.

client.access

Access checks return booleans for repo- and org-scoped permissions. They are useful for frontend UI gating and service-side probes where the caller wants to ask “can this principal do this?” without performing the protected operation itself.

Reference: WarmHubClient.access. No CLI counterpart — access checks are a frontend-gating utility.

client.org

Organization methods manage the top-level namespace for repositories, including creation, description changes, renames, archive state, membership, roles, and scoped member permissions. Member scope overrides replace the effective permission set for a matching resource, so include every permission the member should retain.

Personal organizations linked to a GitHub login cannot be renamed. Organization names are also checked against reserved public slugs such as docs, api, login, and warmhub.

Reference: WarmHubClient.org. CLI counterpart: wh org.

client.repo

Repository methods cover lifecycle operations, metadata, visibility, soft delete, hard delete, content documents, and repo statistics. Use the repo statistics guide when choosing between dashboard list metadata, exact single-repo counts, and batch stats.

The content helpers read and write the well-known Content/Readme and Content/Agents records described in Content Shape. The synthesized Content/LlmsTxt sitemap is read-only — getLlmsTxt returns the rendered markdown plus reference metadata, and there is no setLlmsTxt/generateLlmsTxt companion.

Reference: WarmHubClient.repo. CLI counterpart: wh repo.

client.shape

Shape methods manage schema definitions used to validate things and assertions. Shape create and revise calls are schema writes, while shape rename is applied in place: existing shape history is preserved and no new version is created.

Reference: WarmHubClient.shape. CLI counterpart: wh shape.

client.thing

Thing methods read repository records, histories, assertion targets, references, and search results. This surface also owns in-place thing renames; all other data mutations should go through client.commit or OperationBuilder.

For read-modify-write cycles, client.thing.getWithLease(org, repo, wref, { ttlMs? }) takes a short read lease on a thing so another caller’s revise or retract of it is rejected with LEASE_UNAVAILABLE while you hold it:

• Requires write access — unlike a plain read, a leased read is never anonymous.
• Fails fast if already leased — if another caller holds an active lease, getWithLease itself throws LEASE_UNAVAILABLE (with leaseExpiresAt for backoff) rather than waiting.
• Returns the leased version plus lease.id and lease.expiresAt; the lease also expires automatically at that deadline.
• Write under the lease by passing lease.id as the leaseId on the subsequent revise/retract; it auto-releases on a successful or no-op write.
• Release early with client.thing.releaseLease(org, repo, wref, leaseId) if you decide not to write.

See Write Methods for the leaseId operation field.

Read filters, glob match behavior, reference queries, search modes, and anonymous pagination limits are covered in Read Semantics.

Reference: WarmHubClient.thing. CLI counterpart: wh thing.

client.commit

Commit methods are the high-level write path. client.commit.apply(...) submits add, revise, and retract operations as a single WarmHub commit, returns per-operation results, and supports chunking, component attribution, idempotent add behavior, and retry configuration.

Use Write Methods to choose between raw operation arrays and the builder API. Use Transient Retry for retry and partial-submission behavior.

Reference: WarmHubClient.commit. CLI counterpart: wh commit.

client.stream

The stream surface is the low-level append API. Most SDK users should prefer client.commit.apply(...) or OperationBuilder; use client.stream.append(...) only when you already have backend stream operations, a stream ID, and continuation token state.

Reference: WarmHubClient.stream. No CLI counterpart — use wh commit for normal writes.

client.component

Component methods inspect installed WarmHub components: packages that add shapes, subscriptions, credentials, and seed data to a repository. The nested client.component.registry sub-surface drives the backend-mediated install flow that powers registered installs, and client.component.installSystem(...) installs allowlisted bundled system components such as com.warmhub.identity into an existing repo.

Most component lifecycle commands — init, local/GitHub install, search, view, validate, update, doctor, teardown — are managed through the wh component CLI.

Reference: WarmHubClient.component. CLI counterpart: wh component (broader surface; see note above).

client.subscription

Subscription methods create and manage webhook or cron subscriptions scoped to a repository. The create input covers delivery URLs, fallback delivery, success notifications, source-repo forwarding, trace reentry, and component attribution; update covers a narrower mutable subset (see the API reference for the exact fields).

Credential binding attaches a named credential set to outbound webhook delivery. See Credential binding for the delivery-auth walkthrough, and Component Identity for componentId rules shared with commit writes.

Reference: WarmHubClient.subscription. CLI counterpart: wh sub.

client.action

Action methods are low-level primitives for subscription consumers: leases, live delivery feeds, run listings, attempt listings, and repo-scoped notifications. Webhook handlers and custom consumers use this surface to coordinate processing. The client.actions property is an alias for this surface.

Reference: WarmHubClient.action. CLI counterpart: wh sub log covers action.liveFeed; lease and lifecycle primitives have no CLI surface.

client.token

Token methods create, list, inspect, and revoke personal access tokens for the authenticated user. For scope syntax, rotation, and CI usage, see Personal Access Tokens.

Reference: WarmHubClient.token. CLI counterpart: wh token.

client.credential

Credential methods manage named secret sets used by subscription webhooks and component integrations. Sets are scoped at creation: org-scoped sets can be granted across repos in an organization, repo-scoped sets stay with one repo. The client.credentials property is an alias for this surface.

Reference: WarmHubClient.credential. CLI counterpart: wh credential.

client.live

Live methods open server-sent event streams for repository invalidations. Higher-level helpers re-run their underlying queries after invalidation and pass refreshed results to the callback. The raw subscribe method forwards invalidation metadata without re-querying.

Reference: WarmHubClient.live. No CLI counterpart — SSE streams are SDK-only.

client.diagnostics

Diagnostic methods check backend health and retrieve compatibility information such as API version, minimum supported SDK version, and feature flags.

Reference: WarmHubClient.diagnostics. CLI counterpart: wh doctor covers similar health and capability probes.

OperationBuilder

OperationBuilder builds commit operation batches incrementally, runs local validation, optionally checks data against known shapes, and submits through the same stream path as client.commit.apply(...). After a successful commit, the builder is sealed and cannot be reused.

Reference: OperationBuilder, AddOp, ReviseOp, RetractOp. CLI counterpart: wh commit submit (file-driven equivalent of the builder pattern).

Linking to methods

Surface anchors on the generated reference page (#auth, #commit, #thing, …) are stable. Per-method anchors (#list, #list-1, #list-2, …) are TypeDoc reflection-order dedup — they shift if WarmHubClient properties are reordered or new methods land between existing ones. Link to surface anchors and let readers scroll to the method, or fetch the .md and search by method name.

Next Steps

• WarmHubClient API reference - generated reference for the main client class
• Write Methods - choose the write API that fits the call site
• Read Semantics - filters, match patterns, search, refs, and pagination behavior
• Repo Statistics - exact counts vs dashboard metadata