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 (detect it with isAllStreamOperationsFailedError(error), not instanceof). See SDK Overview for how to create a token and full client setup.

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.

Both list.itemKind and item.kind are open-vocabulary string fields. The set of known kinds may grow over time, so handle unfamiliar values defensively rather than assuming a closed repo | component | skill domain. The SDK exports isKnownHomepageFeaturedItemKind(kind) (TypeScript) to narrow a value to the currently known set before branching on it.

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.

The member status returned by client.org.addMember, client.org.changeMemberRole, and each entry of client.org.listMembers is an open-vocabulary string. active and pending are the known values today, but a newer backend may return others, so handle unfamiliar values defensively rather than treating every non-pending member as active. The SDK exports ORG_MEMBER_STATUSES and isKnownOrgMemberStatus(status) (TypeScript) / KNOWN_ORG_MEMBER_STATUSES and is_known_org_member_status(status) (Python) to narrow a value to the known set before branching on it.

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.

client.org.get(orgName) also returns orgDurableId, an opaque ID that keeps identifying the organization after a rename or after another organization takes its old name. Store it instead of the name when a reference must survive renames. client.access.resolve accepts { orgDurableId } in place of { orgName } for org targets, and returns each visible repository’s owning orgDurableId.

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 with repo:read access, or anonymously for public repos. Its subscriptions and configureStats fields are omitted unless the caller also has effective repo:configure access. PAT scopes are independent, not hierarchical. Prefer getLicense when the license is all you want.

Pass { includeHead: false } as the third argument to skip fetching sample records when you only need the description’s metadata, schema, and counts. The result then has an empty head.items array. wh repo describe uses this option.

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.

client.repo.export(orgName, repoName, options?) downloads a repository export as an async generator of rows. It runs two ways: by default the export is produced while you read it, and options.prefer: 'async' instead has the server build the export first, then downloads it — the SDK counterpart to the CLI’s --async --wait. client.repo.exportPrepare(orgName, repoName, options?) goes one step further and returns a token rather than data, so one process can start a large export and another can download it later by passing that token to export. The token is redeemable only at that repository’s URL, and only by a principal holding unrestricted repo:read plus repo:checkpoint-read there — the same gate as checkpoint access, which component tokens cannot pass at all. Resuming an interrupted download is an SDK-side flow with its own rules — see Resuming an interrupted export. The export file format and offline verification rules are documented under repository export, and the Python equivalents in repository checkpoints.

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.revise(...) accepts two call forms. The five-argument form client.shape.revise(org, repo, shapeName, fields, opts) is the full-replacement path and requires both newFields and opts. The opts-only form client.shape.revise(org, repo, shapeName, opts) omits newFields entirely, preserving the shape’s existing fields while allowing you to update description or composition metadata. Both forms require opts — ShapeReviseOptions carries the required eventRequestId and cannot be omitted. Use the opts-only form when you want to revise metadata without touching the field definitions.

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.

client.shape.get(...) and client.shape.list(...) return a composite shape’s captured closure in an optional composition array; there is no option to request it. Each entry is { wref, fields }: wref names a member shape pinned to the version the composite captured (for example wh:myorg/world/Location@v2), and fields holds that member’s field definitions at that version. Entries are in validation order and include shapes reached through a member’s own composes list. composition is absent for a non-composite shape, and for a composite whose member shapes the caller cannot all read; the composite’s own fields remain in version.data. The only read option client.shape.get(...) takes is includeRetracted. See Composite Shapes.

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 incremental change helpers and four dedicated mutations: in-place renames (rename), in-place corrections to one version’s body (rewrite), permanent deletion (remove), and redaction (redact). All other thing mutations — adding, revising, retracting, and restoring — go through client.commit or OperationBuilder; see Write Methods.

client.thing.redact(orgName, repoName, durableId, { expectedVersion, eventRequestId }) redacts one thing. Redaction irreversibly erases one thing’s canonical content and former name while preserving its durable identity, version history topology, and existing inbound references. See Redaction for the full behavior.

Target: the bare durable ID from a prior read (metadata.durableId), not a name wref. Shapes and removed things cannot be redacted.
Permission: an unrestricted things:redact grant, which repo:admin provides. A token limited with allowedMatches cannot redact.
Version guard: expectedVersion is required. It guards against a stale read of the thing’s current version; it does not select a single version to erase, because redaction applies to every version. A stale value fails with CONFLICT.
Result: every version’s body becomes {}, every current and former name becomes hub/redacted/<durableId>, and every version is certified only by the system RedactedThing shape. No new version is created. Afterwards, revise, rewrite, and rename of the thing are refused with TARGET_REDACTED.
Limits: Core redaction does not erase backups, completed exports, logs, or copies already delivered downstream.

Supply a stable, unique eventRequestId so you can look the outcome up with client.commit.getReceipt if the call fails and you cannot tell whether the redaction landed. The Python client exposes the same method as client.thing.redact(org_name, repo_name, durable_id, expected_version=..., event_request_id=...). See the generated reference for the full options and return types.

client.thing.remove(org, repo, wref, { expectedVersion, eventRequestId }) permanently deletes a thing. Unlike a retract operation submitted through client.commit, remove is irreversible — the thing and its full history are purged. It requires an unrestricted things:delete grant, which repo:admin provides. A token limited with allowedMatches cannot remove. Supply a stable, unique eventRequestId so you can look the outcome up with client.commit.getReceipt if the call fails and you cannot tell whether the deletion landed.

client.thing.rewrite(org, repo, wref, { version, shapes, data, eventRequestId }) corrects bad data by replacing the body of one exact version in place.

Target: wref is the thing’s name or a durable ID in this repo.
Permission: rewrite is privileged. It requires an unrestricted things:rewrite grant, which repo:admin provides. A token limited with allowedMatches cannot rewrite.
Shapes: shapes is the version’s declared shapes plus CorrectedThing, the correction marker.
Body: data is the complete replacement body, whose correctionLog keeps every earlier entry and appends one { reason }.
Result: the version number does not change and no new version is created. To record a new state, revise the thing instead.

Supply a stable, unique eventRequestId so you can look the outcome up with client.commit.getReceipt if the call fails and you cannot tell whether the rewrite landed.

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 its name as the viewRef string: "active-users" for the latest version, or "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, "active-users" or "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 five 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. Validate cannot see refusals that are only decided when the commit is flushed, such as a NAME_TAKEN collision or a lost persistence race: such an operation reports would_apply, and every validate result carries the persistence_races_not_evaluated caveat. That gap is not only races: validate also does not probe names already held by committed Things with a different Shape set, so it answers would_apply for the add and for its dependants, while the write fails with NAME_TAKEN and its dependants with CONFLICT.
client.commit.getReceipt(org, repo, eventRequestId) — reads one OperationEventReceipt back when a write’s outcome is uncertain — a dropped connection, a timeout, a 5xx.
client.commit.getReceiptMetadata(orgName, repoName, eventRequestId) — a lighter-weight alternative to getReceipt that fetches only the receipt’s header metadata (outcome, repoSeq, timestamps, and identity fields) without returning the full per-operation detail. Use this when you need to confirm whether an event landed and retrieve its sequence position, but do not need the complete operation-level breakdown. The Python client exposes the same method as client.commit.get_receipt_metadata(org_name, repo_name, event_request_id).

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.

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.

GlobalSearchResultItem.kind is an open-vocabulary string field on search results. The set of known kinds may grow over time, so handle unfamiliar values defensively rather than assuming a closed domain. The SDK exports isKnownGlobalSearchResultItemKind(kind) (TypeScript) / is_known_global_search_result_item_kind(kind) (Python) to narrow a value to the currently known set before branching on it. The same applies to client.repo.search(query) results.

Component summaries returned by client.component.list() and client.component.get() carry a state field that is an open-vocabulary string. The set of known lifecycle states may grow over time, so handle unfamiliar values defensively. The SDK exports COMPONENT_SUMMARY_STATES and isKnownComponentSummaryState(state) (TypeScript) / KNOWN_COMPONENT_SUMMARY_STATES and is_known_component_summary_state(state) (Python) to check whether a value is a currently known state before branching on it.

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. GrantCreateOptions is an exclusive union: you must supply exactly one of coverage or viewRef — providing both or neither is rejected.

Coverage-backed grants pass a coverage object with the following fields:

paths — an object with an include array of glob strings and an optional exclude array of glob strings that match thing names in the repo.
shapes — an optional array of durable shape identifiers; when present, only things of those shapes are covered. Non-durable shape identifiers are rejected at runtime.
shapesAll — an optional array of durable shape identifiers; when present, only things that carry all of the listed shapes are covered.
shapesNot — an optional array of durable shape identifiers; when present, things that carry any of the listed shapes are excluded from coverage.
shapeless — an optional boolean; when true, coverage extends to things that have no shape.
fields — an optional array of field names. Reserved: supplying it is rejected at runtime, so coverage cannot currently be narrowed to individual fields.

View-backed grants pass a viewRef instead of coverage. The viewRef must be a valid wref pointing to a stored View in the repo (for example, "active-users" or "active-users@v3"). When you read a View-backed grant back via get or list, the returned grant carries coverage: null and a populated viewRef — coverage-backed grants carry the coverage object and viewRef: null. The two shapes are mutually exclusive on both create and read. The viewRef you read back is the View’s durable identity rather than the name form you supplied — the binding is resolved once, at issuance, so that renaming the View does not change which View the grant covers.

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.

The scope field on credential sets returned by createSet, getSet, and listSets is an open-vocabulary string. org and repo are the known values today, but a newer backend may return others, so handle unfamiliar values defensively. The scope option you pass to createSet still accepts only org or repo. The SDK exports CREDENTIAL_SCOPES and isKnownCredentialScope(scope) (TypeScript) / KNOWN_CREDENTIAL_SCOPES and is_known_credential_scope(scope) (Python) to narrow a value to the known set before branching on it.

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, AddOperation, ReviseOperation, RetractOperation. 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