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

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.

Thing read results include a metadata envelope with the thing’s stable durableId and its creation timestamps. Read filters, 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 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 and a stream ID.

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

client.stream.append(...) accepts the following input fields:

• orgName, repoName, streamId — identify the target stream.
• 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).
• returnRepoSeq — optional boolean. When true, the response includes the repo-level sequence number assigned to this append.

The append result includes:

• allocatedTokenRanges — always [].
• createdByEmail — the email address of the principal whose token was used to submit the append.
• repoSeq — the repo-level sequence number for this append, present only when returnRepoSeq was true in the request.
• Per-entry fields on each operation result:
  • 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.

Most component lifecycle operations — init, install, view, validate, update, doctor, teardown — are managed through 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 the Subscriptions guide. 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