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 17 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.homepage

client.homepage.featuredLists() returns the curated featured lists shown on the WarmHub homepage. Each list contains items of varying kinds — including repos, components, and skills — selected editorially. Use this surface when building a discovery UI that wants to surface the same curated items the homepage presents.

Reference: WarmHubClient.homepage. No CLI counterpart.

client.access

Access checks resolve permissions for one or more targets in a single batch resolve call. Each result is a per-target access object containing visible (whether the target is visible to the principal), scopes (the effective permission scopes), and — for repo targets — an optional allowedMatches array. Use this surface for frontend UI gating and service-side probes where you want to inspect what a principal can do without performing the protected operation itself.

Reference: WarmHubClient — access is a first-party surface and is not listed in the generated reference. 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.

client.org.create() requires an interactive browser session — a client authenticated with a personal access token can’t create organizations.

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, content documents, and repo statistics. client.repo.delete() hides the repo immediately; permanent removal happens later and there is no public SDK method to trigger it directly. Deletion can be blocked when any of the following still point into the repo: cross-repo references, cross-repo subscriptions (including paused ones), or a token whose default committer identity is tied to this repo. To unblock deletion caused by a token’s committer identity binding, revoke that token and reissue it without the committer identity tied to this repo — see Personal Access Tokens for token creation and revocation. Resolve those references before retrying. 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.

client.repo.getLicense(orgName, repoName) returns the repository’s declared license, or null when the repo has no active, visible, valid license declaration — treat null as “no usable license”, not as a failed read. Only spdxId is guaranteed on a non-null result; every other field is nullable. See RepoLicense for the full return type.

client.repo.describe() returns the same license inside the full repo description, but that response also carries subscription metadata, so a scoped token needs both repo:read and repo:configure — PAT scopes are independent, not hierarchical. getLicense needs only repo:read, and is anonymous-readable on a public repo, so prefer it when the license is all you want.

client.repo.search(query) runs a cross-org search over the repos visible to you — public repos for everyone, plus private repos your org membership or token grants read access to — distinct from client.repo.list, which enumerates the repos in a single org.

client.repo.explore(opts?) is a separate cross-org browse surface. It operates in two modes: called without a slugs array it returns a paginated browse feed of publicly visible repos; called with a slugs array it performs a batch lookup of those specific repos. Both modes resolve only live public repos — authenticated callers see the same results as anonymous callers, and private repos are not accessible through this surface. First-page responses include total and orgs metadata; passing a cursor resets those fields. This surface is anonymous-readable — no token is required for public browse.

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.

client.shape.create(...) and client.shape.revise(...) validate field-type names locally against the known vocabulary before making any network call. An unrecognized field-type name causes both methods to throw VALIDATION_ERROR immediately, without reaching the server. OperationBuilder applies the same preflight for ADD and REVISE shape operations — field-type names are checked locally before the payload reaches the server. client.commit.apply(...) does not run shape-definition preflight; field-type validation for operations submitted through it is authoritative at the server, and a mixed batch may be partially submitted even when a shape operation contains an off-vocabulary field type.

client.shape.rename requires a caller-owned eventRequestId in the options. Supply a stable, unique value per rename so that if the call fails and you cannot tell whether the rename landed, you can look the outcome up with client.commit.getReceipt(org, repo, eventRequestId). See the generated reference for the full options and return types.

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 and incremental change helpers; all other data mutations should go through client.commit or OperationBuilder.

client.thing.rename requires a caller-owned eventRequestId in the options — supply a stable, unique value per rename so you can look the outcome up with client.commit.getReceipt if the call fails and you cannot tell whether the rename landed. See the generated reference for the full options and return types.

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.

client.thing.headChanges(...) and client.thing.queryChanges(...) are convenience helpers for incremental reads over thing changes. headChanges wraps client.thing.head(...) and returns the changes at the current head of a repo, while queryChanges wraps client.thing.query(...) and runs a query-scoped variant. Both track a repoSeq-based read position so callers receive only what has changed since the last read, without re-fetching the full history. For the full repoSeq checkpoint model and filtering options, see Head Reads and Query Filtering.

Thing read results include a metadata envelope with the thing’s stable durableId and its creation timestamps. Cursor-backed reads across client.thing, repo, component, shape, action, and collection expose lazy *Iter and bounded *All companions; page methods remain available for envelope and cursor control. Read filters, iterator selection, glob match behavior, reference queries, search modes, the metadata envelope, and anonymous pagination limits are covered in Read Semantics.

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

client.collection

Collection methods manage named sets of things within a repo. The surface exposes create, members, membersIter, membersAll, contains, diff, revise, and stats. membersIter(...) is a convenience helper for paginating through collection membership incrementally; membersAll(...) materializes the full membership list in one call. Use collections when you need to track a curated subset of things — for example, a pinned set of records a component operates on — and query membership or compute diffs between collection states.

Reference: WarmHubClient.collection. CLI counterpart: wh collection.

client.commit

Commit methods are the high-level write path. client.commit.apply(...) submits add, revise, and retract operations and returns an OperationSubmitResult — the aggregate write result (operationCount, operations[], and partial plus statusCounts when any operation failed) with the ordered exact OperationEventReceiptV1 receipts nested under receipts, one immutable receipt per chunk. It supports chunking, component attribution, idempotent add behavior, and retry configuration. client.commit.getReceipt(org, repo, eventRequestId) reads one receipt back when a write’s outcome is uncertain — a dropped connection, a timeout, a 5xx.

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 and a stream ID.

allocatedTokenRanges is a retired compatibility field. Pass []; non-empty ranges are rejected.

client.stream.append(...) accepts the following identity and payload fields:

• orgName, repoName, streamId — identify the target repo and diagnostic stream.
• submissionId — caller-known UUID for the logical streamed submission.
• chunkOrdinal — zero-based non-negative chunk index; together with submissionId it determines the immutable event request ID.
• operations — the array of backend stream operations to append.
• allocatedTokenRanges — retired compatibility field. Pass [].
• message — an optional human-readable string attributed to this append (used for provenance and displayed in the write trace).

The append result carries per-operation results rows plus one exact OperationEventReceiptV1 under receipt with:

• eventRequestId, submissionId, requestDigest, and schemaVersion — immutable receipt identity and integrity metadata.
• outcome — event or no_event.
• event — committed event metadata, including decimal-text repoSeq, or null for no-event outcomes.
• operations — the existing ordered physical operation envelopes, including per-entry fields such as:
  • opIndex — the zero-based index of the operation within the submitted operations array.
  • resolvedName — the fully resolved thing name after the operation was applied.
  • retryable — whether a failed operation can be safely retried (present only on failed entries).

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

client.component

Component methods inspect and manage 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 (<org>/<name>) installs — the only install path; there is no separate bundled-system install method.

Both client.component.install and client.component.uninstall accept a caller-owned submissionId in their options. It groups the deterministic receipts for the operation’s repository-mutation phases — the eventReceipts array on the result. It is deliberately narrower than the operation as a whole: credential and subscription reconciliation, setup and uninstall callbacks, and token lifecycle work all keep their own semantics, so submissionId is not a whole-operation idempotency key.

Because of that, treat a failed install or uninstall as something to inspect rather than something to blindly resubmit. Resubmitting can return CONFLICT — for instance while an attempt is still running, or once a callback may already have reached the component — so read the error, and check the component’s own state before deciding what to do.

For most other lifecycle operations — init, view, validate, update, doctor, teardown — use the wh component CLI. Cross-org discovery is also a client method: client.component.search(query) searches the registered components visible to you across all orgs — public components plus any private ones you can read.

client.component.cli.call(orgName, componentName, method, { installRepo, args }) dispatches a CLI-style method call to a registered component. WarmHub-level failures throw WarmHubError. When the upstream component itself returns a non-2xx response, the call resolves to { ok: false, status, body, warnings } rather than throwing, so callers should check ok before consuming the result.

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

client.subscription

Subscription methods create and manage webhook subscriptions. Subscriptions can be scoped to a repository or to an organization, and the create input is discriminated by eventType.

Repo-scoped event types support delivery URLs, fallback delivery, source-repo forwarding, filter, shape, and component attribution fields. Some repo-scoped metadata event types — repo.renamed, thing.renamed, and shape.renamed — use a narrower input shape that does not carry filterJson, shapeName, or sourceRepoRef. Org-scoped event types (such as org.renamed) also use a narrower input shape without those fields.

get, list, pause, resume, and remove accept object forms that omit repoName for org-scoped subscriptions. Credential binding and unbinding work for both repo-scoped and org-scoped subscriptions.

For full details on which fields apply to each event type, see Creating Subscriptions. See Credential binding for the delivery-auth walkthrough, and Component Identity for componentRef 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. CLI counterpart: wh channel exposes live repo events from the CLI; wh thing list --live streams live thing updates.

client.diagnostics

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

client.diagnostics.assertCompatible() is a startup-time guard: it calls client.diagnostics.capabilities() and throws a clear upgrade error when the installed @warmhub/sdk-ts version is below the backend’s minSupportedSdk. Call it once after constructing the client to surface version-skew problems early rather than at the first failing API call.

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