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 the client’s surfaces and their methods inline, and it is long. 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 the methods of each surface it covers. client.access is the one surface the generated reference does not cover — see client.access on this page and Permission Checks.

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.

client.org.list() is the only org method that fills the rollup fields on OrgInfo: repoCount, errorCount (repos with a failing subscription), and lastActivityAt. client.org.get() and the update methods return that same OrgInfo type with all three absent, because they never compute them. The fields are optional on the type, so an undefined repoCount means “not computed on this path” — never “zero repos”. Archived organizations are omitted from list unless includeArchived is set.

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.view

View methods evaluate stored Views against the current state of a repo. A View is a named, versioned query definition stored in the repo itself; evaluating it runs the query and returns typed results without the caller needing to reconstruct the query parameters.

Views are created and managed as things in the repo, using the built-in View shape. The viewRef you pass is a wref — WarmHub’s reference format for addressing a thing, optionally pinned to a version. Once a View exists, you reference it by passing a viewRef string with the View/ shape prefix: "View/active-users" for the latest version, or "View/active-users@v3" to pin a specific version. The backend rejects any viewRef that does not follow this form.

All three methods share the same required inputs: org and repo identify the repository, and viewRef is the versioned wref of the View to evaluate (for example, "View/active-users" or "View/active-users@v3"). The optional opts accepts limit and cursor for page control on all three; evaluateAll additionally accepts max to bound how many results it will materialize.

• client.view.evaluate(org, repo, viewRef, opts?) — evaluates a single View and returns one paginated result page. Accepts limit and cursor options for page control.
• client.view.evaluateIter(org, repo, viewRef, opts?) — lazy iterator variant; yields individual ThingItem results one at a time, paginating automatically for large result sets.
• client.view.evaluateAll(org, repo, viewRef, opts?) — materializes the complete result set in one call. Pass max to cap the number of results collected; without it, a large View is materialized in full. Every *All helper accepts max for the same reason — see Read Semantics.

Use evaluate when you want envelope and cursor control. Use evaluateIter or evaluateAll when you want the same convenience as the *Iter/*All companions on other read surfaces.

Reference: WarmHubClient.view. CLI counterpart: wh view.

client.collection

Collection methods manage named sets of things within a repo. The surface exposes create, members, membersIter, membersAll, contains, diff, revise, and stats. revise(...) updates an existing collection’s membership; it is the SDK counterpart to wh collection revise. 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 operation path. There are four methods to choose from:

• client.commit.apply(...) — submits an operation array or iterable and returns an OperationSubmitResult: the aggregate write result (operationCount, operations[], and partial plus statusCounts when any operation failed) with ordered exact receipts nested under receipts, one immutable OperationEventReceipt per chunk.
• client.commit.applyStreaming(...) — returns a lazy async-iterator handle and yields result/group/terminal rows without aggregating them. Its retryIdentity is available synchronously for outcome-unknown recovery. Supports native Bun and Node.js 22.2+ request streaming.
• client.commit.validate(org, repo, operations, options) — evaluates one bounded complete batch with the same server evaluator but creates no durable state or receipt. Its result contains ordered would_apply / noop / error rows, an authorization-safe baseline, counts, and caveats.
• client.commit.getReceipt(org, repo, eventRequestId) — reads one OperationEventReceipt 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 OperationEventReceipt under receipt. The following fields on the receipt are stable to use regardless of deployment version:

• 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.

The per-operation fields nested under operations vary by receipt schema version. On a v2 receipt (schemaVersion === 2), each entry carries:

• opIndex — the zero-based index of the operation within the submitted operations array.
• resolvedName — the fully resolved thing name after the operation was applied.
• status — applied, noop, or error.
• errors[] — present on error-status entries; each error object carries retryability information and error detail for that operation.

On a v1 receipt, operation rows use status?: 'success' | 'noop' | 'failed', a singular error field, and a retryable boolean instead. Check schemaVersion before reading per-operation fields if your code may run against multiple deployment versions.

Note

This is a low-level surface. If you are working directly with client.stream.append(...) rather than through client.commit, feature-detect optional fields on the receipt rather than assuming they are always present — the receipt type may vary across deployment versions.

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.grant

Grant methods create and administer repository Grants. A Grant permits a specific member, personal access token, or component to perform named operations against a scoped subset of a repo’s data — narrower than the role-and-scope model that governs the caller’s own access. The grantable operations are things:read, commits:read, shapes:read, notifications:read, subscriptions:read, and subscriptions:create. That last one is deliberate: it lets you delegate subscription setup. Writes, admin operations, and grant or credential minting are never grantable, so a grantee cannot re-share what it was given.

The surface exposes create, get, list, and revoke. A Grant’s coverage comes from exactly one source: an inline glob set, or a stored View that defines the covered rows. Grants are immutable — to change one, revoke it and create a replacement.

grant.create is enabled per repo and off by default: until grant issuance is turned on for the target repo, it fails with FORBIDDEN even on a well-formed request. get, list, and revoke are not gated. Only a signed-in member can create a grant — a PAT or component can receive one but cannot issue it.

Use this surface when you are delegating scoped access to someone else. For what the caller themselves can do, see client.access and the Access reference.

Reference: WarmHubClient.grant. CLI counterpart: wh grant.

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, feature flags, and the set of client-declared flags the deployment honors.

client.diagnostics.capabilities() returns a response that includes an honoredClientFlags field — the list of client-declared flags that the deployment recognizes and acts on. A client-declared flag is a hint your code passes to the server to opt into specific behavior; the server only acts on flags it knows about, and honoredClientFlags tells you which ones that is. Use this field to discover at runtime whether a given deployment will honor a particular flag before relying on it.

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