WarmHubClient

HTTP client for WarmHub repository, organization, and component APIs.

Constructors

Constructor

new WarmHubClient(apiUrl?, options?): WarmHubClient

Create a WarmHub client.

Pass either an options object or the legacy (apiUrl, options) form. The options object form is preferred for new code.

Parameters

apiUrl?

string

options?

WarmHubClientOptions

Returns

WarmHubClient

Constructor

new WarmHubClient(options?): WarmHubClient

Parameters

options?

WarmHubClientOptions

Returns

WarmHubClient

Properties

apiUrl

readonly apiUrl: string

The resolved API base URL the client issues requests against. Defaults to DEFAULT_API_URL when no apiUrl is passed to the constructor.

auth

readonly auth: object

Authentication helpers for browser sign-in flows, session checks, and token diagnostics.

getClientId

getClientId: () => Promise<string>

Return the configured browser authentication client ID.

Use this in browser sign-in flows that need to initialize the configured auth provider before redirecting or opening a login UI.

Returns

Promise<string>

sync

sync: () => Promise<{ success: boolean; }>

Sync the authenticated identity with WarmHub.

Call after a browser or server session is established so WarmHub can provision or refresh the corresponding user and personal organization records.

Returns

Promise<{ success: boolean; }>

currentUser

currentUser: () => Promise<CurrentUserInfo>

Return the current authenticated WarmHub user.

Throws when the request is unauthenticated or the token cannot be resolved.

Returns

Promise<CurrentUserInfo>

whoami

whoami: () => Promise<WhoamiInfo>

Return authentication status, identity details, and token scope diagnostics for the current request.

Returns

Promise<WhoamiInfo>

homepage

readonly homepage: object

Homepage surfaces.

featuredLists

featuredLists: () => Promise<HomepageFeaturedListsResult>

Return manually curated featured homepage lists.

Returns

Promise<HomepageFeaturedListsResult>

diagnostics

readonly diagnostics: object

Connectivity and compatibility helpers for checking the configured WarmHub backend.

ping

ping: () => Promise<PingResult>

Perform a health-check request against the configured backend URL.

This uses the HTTP health endpoint rather than tRPC, so it is useful for distinguishing connection failures from procedure-level errors.

Returns

Promise<PingResult>

capabilities

capabilities: () => Promise<{ apiVersion: string; minSupportedSdk: string; features: Record<string, boolean>; }>

Return backend API version, minimum supported SDK version, and feature flags.

Returns

Promise<{ apiVersion: string; minSupportedSdk: string; features: Record<string, boolean>; }>

assertCompatible

assertCompatible: () => Promise<void>

Verify the installed SDK is at or above the backend’s advertised minimum supported version, throwing a WarmHubError with a clear “upgrade to >=X” message when it is not.

Call this once at startup (e.g. immediately after constructing the client) to fail fast on SDK version skew, rather than discovering a removed route deep in the commit pipeline as an opaque error. The result is cached on the client instance — repeated calls reuse the first network round-trip and re-throw the same error if too old.

Returns

Promise<void>

See

https://github.com/warmhub/warmhub-app/issues/3081

component

readonly component: object

Installed component inspection for packages that add shapes, subscriptions, credentials, and seed data to a repository.

The top-level methods cover per-repo installation queries, bundled system installs, and the registry-backed install pipeline used by wh component install <org/name>.

list

list: (orgName, repoName, opts?) => Promise<{ items: Array<{ ref?: string; componentName: string; version?: string; state?: 'initiated' | 'active' | 'uninstalled'; source?: string; sourceUrl?: string; sourceRef?: string; resolvedSha?: string; manifestHash?: string; installedAt?: string; active: boolean; latestVersion?: string; updateAvailable?: boolean; }>; nextCursor?: string; }>

List components installed in a repository.

Pass pagination options when a repository may have many installed components.

Cursor contract: cursors are short-lived resume tokens for the same query and result scope. If filters, visibility, or backing streams change, the backend may reject a saved cursor with VALIDATION_ERROR / Invalid cursor; restart the query without cursor instead of retrying the stale token.

Parameters

orgName

string

repoName

string

opts?

ComponentListOptions

Returns

Promise<{ items: Array<{ ref?: string; componentName: string; version?: string; state?: 'initiated' | 'active' | 'uninstalled'; source?: string; sourceUrl?: string; sourceRef?: string; resolvedSha?: string; manifestHash?: string; installedAt?: string; active: boolean; latestVersion?: string; updateAvailable?: boolean; }>; nextCursor?: string; }>

search

search: (query, opts?) => Promise<GlobalSearchResult>

Search registered components visible to the caller across all orgs (GH-4383): public components plus private components the caller can read. Distinct from listing components installed in a repo (component.list).

Parameters

query

string

opts?

GlobalSearchOptions

Returns

Promise<GlobalSearchResult>

get

get: (orgName, repoName, componentRef) => Promise<{ ref?: string; componentName: string; version?: string; state?: 'initiated' | 'active' | 'uninstalled'; source?: string; sourceUrl?: string; sourceRef?: string; resolvedSha?: string; manifestHash?: string; installedAt?: string; active: boolean; latestVersion?: string; updateAvailable?: boolean; installedManifest: unknown; installComponentId?: string; ownedShapes: Array<{ name: string; kind: 'shape'; active: boolean; version: { version: number; operation: 'add' | 'revise' | 'retract'; data: unknown; dataHash: string; } | null; componentRef?: string; }>; ownedThings: Array<{ wref: string; name: string; kind: 'shape' | 'thing' | 'assertion' | 'collection'; shapeName?: string; componentRef?: string; version: number; createdAt: number; data?: unknown; active: boolean; aboutWref?: string; roles?: Array<'from' | 'to' | 'ends' | 'first' | 'second'>; metadata?: { durableId: string; createdOn: number; revisedOn: number; }; }>; }>

Fetch one installed component by its Org/Name ref.

Parameters

orgName

string

repoName

string

componentRef

string

Returns

Promise<{ ref?: string; componentName: string; version?: string; state?: 'initiated' | 'active' | 'uninstalled'; source?: string; sourceUrl?: string; sourceRef?: string; resolvedSha?: string; manifestHash?: string; installedAt?: string; active: boolean; latestVersion?: string; updateAvailable?: boolean; installedManifest: unknown; installComponentId?: string; ownedShapes: Array<{ name: string; kind: 'shape'; active: boolean; version: { version: number; operation: 'add' | 'revise' | 'retract'; data: unknown; dataHash: string; } | null; componentRef?: string; }>; ownedThings: Array<{ wref: string; name: string; kind: 'shape' | 'thing' | 'assertion' | 'collection'; shapeName?: string; componentRef?: string; version: number; createdAt: number; data?: unknown; active: boolean; aboutWref?: string; roles?: Array<'from' | 'to' | 'ends' | 'first' | 'second'>; metadata?: { durableId: string; createdOn: number; revisedOn: number; }; }>; }>

history

history: (orgName, repoName, opts?) => Promise<{ items: Array<{ ref: string; kind: string; version: string | null; createdAt: number; }>; }>

Install lifecycle timeline from the durable install-events log (GH-4690). Omit componentRef for the repo-wide activity feed; pass Org/Name for a single component’s history.

Parameters

orgName

string

repoName

string

opts?

ComponentHistoryOptions

Returns

Promise<{ items: Array<{ ref: string; kind: string; version: string | null; createdAt: number; }>; }>

install

install: (orgName, repoName, componentRef) => Promise<ComponentInstallResult>

Install a registered component into a repository (GH-4610).

Backend-driven: the server resolves the registration and its latest published manifest, reconciles the shapes/subscriptions/credentials/seeds into the target repo, and runs the component’s optional setup callback — the same pipeline wh component install <org/name> drives. orgName / repoName identify the INSTALL repo; componentRef is the <org>/<name> of the component to install. Requires things:write on the install repo; private registrations require owner-org membership.

Reinstall is idempotent: the install identity (installId) is reused so runtime tokens keyed on it survive teardown/reinstall.

Parameters

orgName

string

repoName

string

componentRef

string

Returns

Promise<ComponentInstallResult>

uninstall

uninstall: (orgName, repoName, componentRef) => Promise<ComponentUninstallResult>

Uninstall a registered component from a repository (GH-4677).

Backend-driven terminal teardown — the sibling of install: the server pauses the install’s subscriptions per the manifest teardown policy, revokes its tokens in place, dispatches the component’s optional uninstall callback, and marks the repo-local ComponentInstall record uninstalled. The same pipeline wh component teardown <org/name> drives. orgName / repoName identify the INSTALL repo; componentRef is the <org>/<name> of the component. Requires things:write on the install repo; private registrations require owner-org membership.

Non-destructive: manifest shapes and seeded data are left intact (only repo deletion removes those) and reinstall revives the install.

Parameters

orgName

string

repoName

string

componentRef

string

Returns

Promise<ComponentUninstallResult>

registry

registry: object

Registered-component identity and install-pipeline operations.

This sub-surface drives the backend-mediated install flow that powers wh component install <org/name>. It manages registered component identities (register, unregister, list, view, update) and the install pipeline (resolve returns the latest published manifest plus an install id, setupCall dispatches the optional setup callback). Use these when building a custom installer; most callers should run the CLI instead.

registry.register

register: (orgName, componentName, input) => Promise<{ ownerOrgName: string; componentName: string; ref: string; isPrivate: boolean; mintedTokens: boolean; sourceUrl?: string; sourceDefaultRef?: string; setupUrl?: string; uninstallUrl?: string; allowedCallbackDomains: string[]; credentialSetId?: string; credentialSetName?: string; description?: string; createdAt: number; updatedAt: number; }>

Parameters

orgName

string

componentName

string

input

unknown

Returns

Promise<{ ownerOrgName: string; componentName: string; ref: string; isPrivate: boolean; mintedTokens: boolean; sourceUrl?: string; sourceDefaultRef?: string; setupUrl?: string; uninstallUrl?: string; allowedCallbackDomains: string[]; credentialSetId?: string; credentialSetName?: string; description?: string; createdAt: number; updatedAt: number; }>

registry.unregister

unregister: (orgName, componentName) => Promise<{ unregistered: true; }>

Parameters

orgName

string

componentName

string

Returns

Promise<{ unregistered: true; }>

registry.list

list: (orgName) => Promise<unknown>

Parameters

orgName

string

Returns

Promise<unknown>

registry.view

view: (orgName, componentName) => Promise<{ ownerOrgName: string; componentName: string; ref: string; isPrivate: boolean; mintedTokens: boolean; sourceUrl?: string; sourceDefaultRef?: string; setupUrl?: string; uninstallUrl?: string; allowedCallbackDomains: string[]; credentialSetId?: string; credentialSetName?: string; description?: string; createdAt: number; updatedAt: number; }>

Parameters

orgName

string

componentName

string

Returns

registry.update

update: (orgName, componentName, input) => Promise<{ ownerOrgName: string; componentName: string; ref: string; isPrivate: boolean; mintedTokens: boolean; sourceUrl?: string; sourceDefaultRef?: string; setupUrl?: string; uninstallUrl?: string; allowedCallbackDomains: string[]; credentialSetId?: string; credentialSetName?: string; description?: string; createdAt: number; updatedAt: number; }>

Parameters

orgName

string

componentName

string

input

{ isPrivate?: boolean; mintedTokens?: boolean; sourceUrl?: string; sourceDefaultRef?: string; setupUrl?: string; uninstallUrl?: string; allowedCallbackDomains?: string[]; credentialSetName?: string; description?: string; manifest?: Record<string, unknown>; }

Returns

registry.resolve

resolve: (orgName, componentName, installRepo) => Promise<{ manifest: Record<string, unknown>; manifestHash: string; hasSetup: boolean; }>

Parameters

orgName

string

componentName

string

installRepo

string

Returns

Promise<{ manifest: Record<string, unknown>; manifestHash: string; hasSetup: boolean; }>

registry.setupCall

setupCall: (orgName, componentName, input) => Promise<{ ok: boolean; status: number; body?: string; warnings: string[]; }>

Parameters

orgName

string

componentName

string

input

{ installId: string; installRepo: string; expectedManifestHash: string; }

Returns

Promise<{ ok: boolean; status: number; body?: string; warnings: string[]; }>

cli

cli: object

Operator-invoked CLI methods (GH-3193).

cli.call(orgName, componentName, method, { installRepo, args }) dispatches a component-declared method via the backend. The backend loads the install’s manifest snapshot, verifies the method exists, authorizes the operator, signs the request with the install-repo credential set (HMAC over ${timestamp}.${body} by default), and proxies the component service’s JSON response back as the envelope’s body.

WarmHub-level failures (component not installed, method not in snapshot, ComponentConfig.cliBaseUrl missing, credentials missing, operator lacks requiresPermission) come back as a thrown WarmHubError. Upstream non-2xx responses do not throw — they arrive inside the envelope as { ok: false, status, body } so the CLI can pretty-print the component’s own error payload.

cli.call

call: (orgName, componentName, method, input) => Promise<{ ok: boolean; status: number; body?: string; warnings: string[]; }>

Parameters

orgName

string

componentName

string

method

string

input

{ installRepo: string; args?: Record<string, unknown>; }

Returns

Promise<{ ok: boolean; status: number; body?: string; warnings: string[]; }>

commit

readonly commit: object

High-level write surface for submitting WarmHub operations through the commit pipeline.

apply

apply: (orgName, repoName, message, operations, opts?) => Promise<OperationSubmitResult>

Submit one or more operations through WarmHub’s commit pipeline.

This is the primary write path for SDK callers. It streams operations to the backend, preserves server-side per-operation results, supports chunking for large submissions, and can attribute writes to a committer wref or installed component.

Simple first-chunk transport failures are retried by default. Ambiguous failures surface as PartialStreamSubmissionError, including the case where an ambiguous attempt is followed by an all-failed retry; inspect error.cause for the underlying AllStreamOperationsFailedError or backend error. Deterministic all-failed submissions without prior ambiguity throw AllStreamOperationsFailedError directly so callers can inspect per-operation failure rows. Validation, auth, conflict, rate-limit, and other definite backend failures surface as WarmHubError. See Transient Retry for the full retry and partial-submission rules.

Writing to an archived organization or repository fails with an ARCHIVED error before any operations are applied.

Parameters

orgName

string

repoName

string

message

string | undefined

Optional commit message stored with the submitted operations.

operations

Operation[]

Add, revise, or retract operations to submit in order.

opts?

committer?

string

Optional untyped wref identifying the actor on whose behalf the write is made. It may target an existing shape ("Agent") or shaped thing ("Agent/bot-1"), locally or canonically ("wh:other-org/other-repo/Agent" or "wh:other-org/other-repo/Agent/bot-1"). A one-segment value is a shape wref, not a free-form label, and succeeds only when that shape exists. On success, OperationSubmitResult.committer echoes the supplied wref string; version reads expose the resolved target as committerWref.

componentRef?

string

Attribute writes to an installed component, identified by its Org/Name ref, when the caller is allowed to claim it.

chunkSize?

number

Maximum operations per stream append. Values are clamped by the SDK.

skipExisting?

boolean

Return noop for add operations whose target already exists.

streamId?

string

Advanced continuation hook for caller-managed streams.

returnRepoSeq?

boolean

Return the sequence allocated to the writer’s own commit acknowledgement. This does not disclose a reader-facing repository head. Multi-chunk submissions return the last sequence actually allocated; a later no-op or failed chunk does not erase it.

retry?

false | RetryPolicyOptions

Retry policy for transient first-chunk failures, or false to disable automatic retry.

Returns

Promise<OperationSubmitResult>

See

https://docs.warmhub.ai/sdk/write-methods/

org

readonly org: object

Organization management surface for namespaces, membership, roles, and scoped member permissions.

get

get: (orgName) => Promise<{ name: string; displayName: string; description?: string; tier: 'free' | 'pro' | 'enterprise'; archivedAt?: number; createdAt: number; repoCount?: number; errorCount?: number; lastActivityAt?: number; }>

Get an organization by name.

Parameters

orgName

string

Returns

Promise<{ name: string; displayName: string; description?: string; tier: 'free' | 'pro' | 'enterprise'; archivedAt?: number; createdAt: number; repoCount?: number; errorCount?: number; lastActivityAt?: number; }>

getCallerRole

getCallerRole: (orgName) => Promise<OrgRole | null>

Return the caller’s role in an organization, or null when the caller is not a member.

Useful for UI gating before showing organization-level controls.

Parameters

orgName

string

Returns

Promise<OrgRole | null>

list

list: (opts?) => Promise<Page<{ name: string; displayName: string; description?: string; tier: 'free' | 'pro' | 'enterprise'; archivedAt?: number; createdAt: number; repoCount?: number; errorCount?: number; lastActivityAt?: number; }>>

List organizations visible to the caller.

Archived organizations are hidden unless includeArchived is set.

Parameters

opts?

OrgListOptions

Returns

Promise<Page<{ name: string; displayName: string; description?: string; tier: 'free' | 'pro' | 'enterprise'; archivedAt?: number; createdAt: number; repoCount?: number; errorCount?: number; lastActivityAt?: number; }>>

create

create: (name, displayName?, description?) => Promise<{ name: string; displayName: string; description?: string; tier: 'free' | 'pro' | 'enterprise'; archivedAt?: number; createdAt: number; repoCount?: number; errorCount?: number; lastActivityAt?: number; }>

Create a new organization.

The description is trimmed and empty strings are ignored. Organization names must avoid reserved public slugs such as docs, api, login, and warmhub.

Parameters

name

string

displayName?

string

Optional display label. Defaults to the organization name when omitted.

description?

string

Returns

setDescription

setDescription: (orgName, description?) => Promise<{ name: string; displayName: string; description?: string; tier: 'free' | 'pro' | 'enterprise'; archivedAt?: number; createdAt: number; repoCount?: number; errorCount?: number; lastActivityAt?: number; }>

Set or clear an organization description.

Descriptions are trimmed; empty strings clear the stored value.

Parameters

orgName

string

description?

string

Returns

setDisplayName

setDisplayName: (orgName, displayName) => Promise<{ name: string; displayName: string; description?: string; tier: 'free' | 'pro' | 'enterprise'; archivedAt?: number; createdAt: number; repoCount?: number; errorCount?: number; lastActivityAt?: number; }>

Update an organization’s display name.

Display names are trimmed; empty or whitespace-only values are rejected.

Parameters

orgName

string

displayName

string

Returns

rename

rename: (orgName, newName) => Promise<{ name: string; displayName: string; description?: string; tier: 'free' | 'pro' | 'enterprise'; archivedAt?: number; createdAt: number; repoCount?: number; errorCount?: number; lastActivityAt?: number; }>

Rename an organization in place.

The new slug must satisfy the same naming and reserved-name rules as organization creation.

Parameters

orgName

string

newName

string

Returns

update

update: (input) => Promise<{ name: string; displayName: string; description?: string; tier: 'free' | 'pro' | 'enterprise'; archivedAt?: number; createdAt: number; repoCount?: number; errorCount?: number; lastActivityAt?: number; }>

Atomic combined update of an organization’s display name and/or slug.

Both writes run in a single backend transaction so a slug conflict cannot leave a partial display-name change behind. Pass at least one of displayName or newName.

Parameters

input

orgName

string

displayName?

string

newName?

string

Returns

addMember

addMember: (orgName, email, role) => Promise<{ email: string; firstName?: string; lastName?: string; role: 'owner' | 'admin' | 'editor' | 'viewer'; status: 'active' | 'pending'; invitedBy?: string; createdAt: number; }>

Add a member to an organization or create a pending invite.

The role defaults to editor. If the email address does not belong to an existing WarmHub user, WarmHub creates a pending invite and attempts to send the invite email asynchronously. Only owners can assign the owner role.

Parameters

orgName

string

email

string

role?

"owner" | "admin" | "editor" | "viewer"

Organization role to assign. Defaults to editor.

Returns

Promise<{ email: string; firstName?: string; lastName?: string; role: 'owner' | 'admin' | 'editor' | 'viewer'; status: 'active' | 'pending'; invitedBy?: string; createdAt: number; }>

removeMember

removeMember: (orgName, email) => Promise<void>

Remove an active member or revoke a pending invite by email address.

Parameters

orgName

string

email

string

Returns

Promise<void>

leave

leave: (orgName) => Promise<void>

Leave an organization the caller is a member of (self-service).

Session-only: requires an interactive user session, so personal access tokens are rejected. You cannot leave your personal organization, and an owner can only leave when the organization retains another active owner.

Parameters

orgName

string

Returns

Promise<void>

changeMemberRole

changeMemberRole: (orgName, email, role) => Promise<{ email: string; firstName?: string; lastName?: string; role: 'owner' | 'admin' | 'editor' | 'viewer'; status: 'active' | 'pending'; invitedBy?: string; createdAt: number; }>

Change a member’s organization role.

Only owners can promote another member to owner or demote an existing owner. WarmHub rejects attempts to remove the final owner.

Parameters

orgName

string

email

string

role

"owner" | "admin" | "editor" | "viewer"

Returns

Promise<{ email: string; firstName?: string; lastName?: string; role: 'owner' | 'admin' | 'editor' | 'viewer'; status: 'active' | 'pending'; invitedBy?: string; createdAt: number; }>

setMemberScopes

setMemberScopes: (orgName, email, scopes) => Promise<void>

Replace a member’s scoped permission entries.

Each entry targets either the organization (acme) or one repository (acme/world) and carries the full desired permission set for that resource. Matching entries replace the role-derived permission set for that resource; include every permission the member should retain.

Member scope entries share the same wire shape as personal access token scopes, but allowedMatches is enforced for PATs only. Member scopes cannot restrict access by thing-name glob.

Parameters

orgName

string

email

string

scopes

WireScopeEntry[]

Scoped permission entries with resource and permissions fields.

Returns

Promise<void>

clearMemberScopes

clearMemberScopes: (orgName, email) => Promise<void>

Remove all scoped permission entries from a member.

After clearing, the member’s effective access comes from their organization role only.

Parameters

orgName

string

email

string

Returns

Promise<void>

listMembers

listMembers: (orgName, opts?) => Promise<OrgMemberList>

List organization members and pending invites.

The response includes the caller’s current organization role so frontend settings pages can gate owner/admin-only controls without making a second request.

Parameters

orgName

string

opts?

OrgListMembersOptions

Returns

Promise<OrgMemberList>

unarchive

unarchive: (orgName) => Promise<{ name: string; displayName: string; description?: string; tier: 'free' | 'pro' | 'enterprise'; archivedAt?: number; createdAt: number; repoCount?: number; errorCount?: number; lastActivityAt?: number; }>

Unarchive an organization.

Parameters

orgName

string

Returns

repo

readonly repo: object

Repository management surface for lifecycle operations, metadata, statistics, and content documents.

get

get: (orgName, repoName) => Promise<RepoInfo>

Get a repository by organization and repository name.

Parameters

orgName

string

repoName

string

Returns

Promise<RepoInfo>

getStats

getStats: (orgName, repoName) => Promise<{ total: number; byKind: { shape: number; thing: number; assertion: number; }; byShape: Record<string, number>; }>

Return authoritative active-item totals for a single repository.

The returned total is the sum of active shapes, things, and assertions. Use this when billing, quota checks, health reports, or per-shape breakdowns need single-repo stats.

The per-shape breakdown counts active things and assertions by shape.

Parameters

orgName

string

repoName

string

Returns

Promise<{ total: number; byKind: { shape: number; thing: number; assertion: number; }; byShape: Record<string, number>; }>

getStatsBatch

getStatsBatch: (orgName, repoNames) => Promise<RepoStatsBatchResult>

Return active-item totals for up to 100 repositories in one request.

Use this instead of issuing one getStats request per repository when building organization dashboards. Batch entries include the exact total for visible repositories; call getStats for an individual repository when you need the per-shape map.

Parameters

orgName

string

repoNames

string[]

Returns

Promise<RepoStatsBatchResult>

getConfigureStats

getConfigureStats: (orgName, repoName) => Promise<{ subscriptionCount: number; }>

Return configuration-surface counts for a repository.

Currently this reports the number of subscriptions attached to the repository, which is useful before delete or visibility-change flows.

Parameters

orgName

string

repoName

string

Returns

Promise<{ subscriptionCount: number; }>

getShapeInstanceCounts

getShapeInstanceCounts: (orgName, repoName) => Promise<Record<string, { things: number; assertions: number; }>>

Return per-shape thing and assertion counts for a repository.

The server computes the totals directly, so callers do not need to page through repository contents to build shape summary UI.

Parameters

orgName

string

repoName

string

Returns

Promise<Record<string, { things: number; assertions: number; }>>

list

list: (orgName, opts?) => Promise<{ items: Array<{ orgName: string; name: string; displayName: string; description?: string; visibility: 'public' | 'private'; archivedAt?: number; createdAt: number; }>; nextCursor?: string; }>

List repositories in an organization.

Archived repositories are hidden by default. Search and sort options are applied before pagination.

Parameters

orgName

string

opts?

RepoListOptions

Returns

Promise<{ items: Array<{ orgName: string; name: string; displayName: string; description?: string; visibility: 'public' | 'private'; archivedAt?: number; createdAt: number; }>; nextCursor?: string; }>

search

search: (query, opts?) => Promise<GlobalSearchResult>

Search repos visible to the caller across all orgs (GH-4383): public repos plus private repos the caller can read. BM25 over name/description/shape vocabulary/README.

Parameters

query

string

opts?

GlobalSearchOptions

Returns

Promise<GlobalSearchResult>

create

create: (orgName, repoName, description?, visibility?, displayName?) => Promise<RepoInfo>

Create a repository inside an organization.

Repositories are private by default. Descriptions are trimmed and capped by the backend.

Parameters

orgName

string

repoName

string

description?

string

visibility?

'public' | 'private'

public or private; defaults to private.

displayName?

string

Returns

Promise<RepoInfo>

setDescription

setDescription: (orgName, repoName, description?) => Promise<RepoInfo>

Set or clear a repository description.

Descriptions are trimmed; empty strings clear the stored value.

Parameters

orgName

string

repoName

string

description?

string

Returns

Promise<RepoInfo>

setDisplayName

setDisplayName: (orgName, repoName, displayName) => Promise<RepoInfo>

Set a repository display name.

displayName is required and non-empty (trimmed); slug fallback is a creation-time behavior only and there is no clear-to-slug flow.

Parameters

orgName

string

repoName

string

displayName

string

Returns

Promise<RepoInfo>

setVisibility

setVisibility: (orgName, repoName, visibility) => Promise<RepoInfo>

Set a repository’s visibility to public or private.

Parameters

orgName

string

repoName

string

visibility

'public' | 'private'

Returns

Promise<RepoInfo>

rename

rename: (orgName, repoName, newName) => Promise<RepoInfo>

Rename a repository within its organization.

The new name must be unused in the organization and follow the same path-segment rules as repository creation.

Parameters

orgName

string

repoName

string

newName

string

Returns

Promise<RepoInfo>

update

update: (input) => Promise<RepoInfo>

Atomic combined update of a repository’s display name and/or slug.

Both writes run in a single backend transaction so a slug conflict cannot leave a partial display-name change behind. Pass at least one of displayName or newName. displayName is rejected when empty — slug fallback is a creation-time behavior only.

Parameters

input

orgName

string

repoName

string

displayName?

string

newName?

string

Returns

Promise<RepoInfo>

unarchive

unarchive: (orgName, repoName) => Promise<RepoInfo>

Unarchive a repository.

Parameters

orgName

string

repoName

string

Returns

Promise<RepoInfo>

delete

delete: (orgName, repoName) => Promise<{ graceExpiresAt: Date; }>

Soft-delete a repository.

The repository is hidden immediately and scheduled for permanent purge after a 30-day grace window. WarmHub blocks deletion when another repository still has inbound cross-repo references, active subscriptions, or active credential grants that depend on the repository.

Parameters

orgName

string

repoName

string

Returns

Promise<{ graceExpiresAt: Date; }>

listPage

listPage: (orgName, opts?) => Promise<RepoListPageResult>

List repositories with dashboard-oriented per-repository metadata.

Each item includes exact active counts, an activity-oriented lastWriteAt, and a hasErrors flag for terminal action failures.

Search and sort are applied before pagination, so cursors remain stable across the filtered and ordered list.

Parameters

orgName

string

opts?

RepoListPageOptions

Returns

Promise<RepoListPageResult>

listForCaller

listForCaller: (opts?) => Promise<{ orgName: string; name: string; displayName: string; createdAt: number; lastWriteAt?: number; }[]>

List the caller’s repositories across every org they belong to, ordered for recency by default (most recently written first), capped at limit.

Unlike listPage, this is user-level and resolves the caller’s orgs server-side, so you don’t fan out one request per org to build an account-wide view. Membership is the access filter and per-token allowedMatches narrowing is not applied, so this requires an interactive session — PAT and component-token callers are rejected. Use the org-scoped listPage from token-authenticated contexts.

Parameters

opts?

RepoListForCallerOptions

Returns

Promise<{ orgName: string; name: string; displayName: string; createdAt: number; lastWriteAt?: number; }[]>

explore

explore: (opts?) => Promise<RepoExploreResult>

Browse the public “Explore” directory: every visibility='public' live repository across all orgs, with search, org/activity/subscription/thing filters, and sort. No auth required — anonymous callers see the same public-only listing.

Two mutually-exclusive modes. Browse mode paginates a filtered, sorted listing (search/org/activity/hasSubscriptions/minThings/sort/ limit/cursor). Slugs mode is an exact-match batch lookup: pass up to 12 org/repo slugs to resolve just those live public repos in input order, ignoring every browse field. Combining slugs with any browse/ search/sort/filter field is a hard input error, not a silently-filtered list.

total and orgs (the org-filter facet) are returned on the first page only — i.e. when cursor is absent.

Parameters

opts?

{ search?: string; org?: string; activity?: 'week' | 'month'; hasSubscriptions?: true; minThings?: number; sort?: 'recentlyUpdated' | 'mostSubscribed' | 'mostThings' | 'nameAsc' | 'newest'; limit?: number; cursor?: string; slugs?: Array<string>; }

Returns

Promise<RepoExploreResult>

getReadme

getReadme: (orgName, repoName) => Promise<ThingDetail | null>

Fetch a repository’s Content/Readme markdown record.

The SDK contract allows null; current backend behavior returns a synthesized empty stub for repositories that have not committed README content yet. Callers should still null-check defensively.

Parameters

orgName

string

repoName

string

Returns

Promise<ThingDetail | null>

getAgents

getAgents: (orgName, repoName) => Promise<ThingDetail | null>

Fetch a repository’s Content/Agents markdown record.

The SDK contract allows null; current backend behavior mirrors getReadme and returns a synthesized empty stub when no AGENTS.md content has been committed yet.

Parameters

orgName

string

repoName

string

Returns

Promise<ThingDetail | null>

setReadme

setReadme: (orgName, repoName, content) => Promise<{ committer?: string; createdByEmail?: string; message?: string; operationCount: number; repoSeq?: number; operations: Array<{ opIndex?: number; name: string; operation: 'add' | 'revise' | 'retract' | 'rename' | 'noop'; version: number; dataHash: string; status?: 'applied' | 'noop'; warnings?: { undeclaredFields?: Array<string>; undeclaredFieldsTruncated?: true; totalUndeclared?: number; coalescedWrefs?: Array<{ fieldPath: string; wref: string; reason: string; }>; coalescedWrefsTruncated?: true; totalCoalescedWrefs?: number; deprecations?: Array<{ shape: string; message: string; removalMilestone: string; }>; }; }>; }>

Commit a new Content/Readme value.

The backend adds or revises the content record through the normal commit pipeline.

Parameters

orgName

string

repoName

string

content

string

Returns

Promise<{ committer?: string; createdByEmail?: string; message?: string; operationCount: number; repoSeq?: number; operations: Array<{ opIndex?: number; name: string; operation: 'add' | 'revise' | 'retract' | 'rename' | 'noop'; version: number; dataHash: string; status?: 'applied' | 'noop'; warnings?: { undeclaredFields?: Array<string>; undeclaredFieldsTruncated?: true; totalUndeclared?: number; coalescedWrefs?: Array<{ fieldPath: string; wref: string; reason: string; }>; coalescedWrefsTruncated?: true; totalCoalescedWrefs?: number; deprecations?: Array<{ shape: string; message: string; removalMilestone: string; }>; }; }>; }>

setAgents

setAgents: (orgName, repoName, content) => Promise<{ committer?: string; createdByEmail?: string; message?: string; operationCount: number; repoSeq?: number; operations: Array<{ opIndex?: number; name: string; operation: 'add' | 'revise' | 'retract' | 'rename' | 'noop'; version: number; dataHash: string; status?: 'applied' | 'noop'; warnings?: { undeclaredFields?: Array<string>; undeclaredFieldsTruncated?: true; totalUndeclared?: number; coalescedWrefs?: Array<{ fieldPath: string; wref: string; reason: string; }>; coalescedWrefsTruncated?: true; totalCoalescedWrefs?: number; deprecations?: Array<{ shape: string; message: string; removalMilestone: string; }>; }; }>; }>

Commit a new Content/Agents value through the normal commit pipeline.

Parameters

orgName

string

repoName

string

content

string

Returns

getLlmsTxt

getLlmsTxt: (orgName, repoName) => Promise<SynthesizedRepoContent>

Fetch the synthesized Content/LlmsTxt sitemap for a repository.

The returned markdown follows the llms.txt convention. Authenticated callers also receive structured reference metadata partitioned by readable outbound and inbound references; cross-org references the caller cannot read are omitted.

Parameters

orgName

string

repoName

string

Returns

Promise<SynthesizedRepoContent>

index

index: object

Field-index diagnostics.

index.describe

describe: (orgName, repoName) => Promise<IndexedFieldsReport>

Describe all indexed fields for a repo, grouped by state.

Returns ready, building, failed, and other buckets (read-only diagnostics). Use wh repo describe --indexed-fields --repo <org/repo>.

Parameters

orgName

string

repoName

string

Returns

Promise<IndexedFieldsReport>

See

https://docs.warmhub.ai/sdk/repo-stats/

shape

readonly shape: object

Shape management surface for schema definitions that validate things and assertions.

list

list: (orgName, repoName, opts?) => Promise<{ items: Array<{ name: string; kind: 'shape'; active: boolean; version: { version: number; operation: 'add' | 'revise' | 'retract'; data: unknown; dataHash: string; } | null; componentRef?: string; }>; }>

List shape definitions in a repository.

Options can include retracted shapes, filter by component ownership, or hide component-owned shapes.

Parameters

orgName

string

repoName

string

opts?

ShapeListOptions

Returns

Promise<{ items: Array<{ name: string; kind: 'shape'; active: boolean; version: { version: number; operation: 'add' | 'revise' | 'retract'; data: unknown; dataHash: string; } | null; componentRef?: string; }>; }>

get

get: (orgName, repoName, shapeName, opts?) => Promise<{ name: string; kind: 'shape'; active: boolean; version: { version: number; operation: 'add' | 'revise' | 'retract'; data: unknown; dataHash: string; } | null; componentRef?: string; }>

Get one shape definition by name.

Returns the full shape thing record, with name, kind: "shape", active, and a nested version: { version, operation, data, dataHash } | null. This is not the same shape as the shape returned by create and revise: the change result is flat (name, operation, version: number, dataHash) and does not carry data. To read shape fields, call get and read result.version?.data — the change result alone is not enough.

Parameters

orgName

string

repoName

string

shapeName

string

opts?

ShapeGetOptions

Returns

Promise<{ name: string; kind: 'shape'; active: boolean; version: { version: number; operation: 'add' | 'revise' | 'retract'; data: unknown; dataHash: string; } | null; componentRef?: string; }>

create

create: (orgName, repoName, shapeName, fields, opts?) => Promise<{ name: string; operation: 'add' | 'revise' | 'retract' | 'noop'; version: number; dataHash: string; }>

Create a shape definition.

Shape data should describe the fields used to validate things and assertions with that shape.

Returns { name, operation, version, dataHash }. The result confirms the write and exposes the new version number, but it does not include the shape data — call client.shape.get for the full shape record (with kind, active, and nested version.data).

Parameters

orgName

string

repoName

string

shapeName

string

fields

Record<string, unknown>

opts?

ShapeCreateOptions

Returns

Promise<{ name: string; operation: 'add' | 'revise' | 'retract' | 'noop'; version: number; dataHash: string; }>

revise

revise: (orgName, repoName, shapeName, newFields, opts?) => Promise<{ name: string; operation: 'add' | 'revise' | 'retract' | 'noop'; version: number; dataHash: string; }>

Revise a shape definition, creating a new shape version.

Returns { name, operation, version, dataHash }, the same flat shape as create. To read the revised fields back, call client.shape.get for the full shape record.

Parameters

orgName

string

repoName

string

shapeName

string

newFields

Record<string, unknown>

opts?

ShapeReviseOptions

Returns

Promise<{ name: string; operation: 'add' | 'revise' | 'retract' | 'noop'; version: number; dataHash: string; }>

remove

remove: (orgName, repoName, shapeName) => Promise<ShapeRemove>

Retract a shape definition.

Parameters

orgName

string

repoName

string

shapeName

string

Returns

Promise<ShapeRemove>

rename

rename: (orgName, repoName, oldName, newName) => Promise<RenameResult>

Rename a shape within a repository.

The rename is applied in place: the existing shape history is preserved and no new version is created.

Parameters

orgName

string

repoName

string

oldName

string

newName

string

Returns

Promise<RenameResult>

history

history: (orgName, repoName, name, opts) => Promise<HistoryResult>

Return add, revise, retract, and rename history for a shape.

Use pagination options for long-lived shapes with many revisions.

Parameters

orgName

string

repoName

string

name

string

opts?

ShapeHistoryOptions = {}

Returns

Promise<HistoryResult>

subscription

readonly subscription: object

Webhook subscription management surface scoped to a repository.

create

create: (input) => Promise<SubscriptionInfo>

Create a webhook subscription.

Webhook subscriptions require a delivery URL. Commit subscriptions are repo-scoped and require a shape/filter; repo and org metadata subscriptions omit commit-only fields. Org-scoped events also omit repoName.

Delivery can use a fallback URL and allow trace reentry. Commit subscriptions can additionally forward events from another repository.

Parameters

input

SubscriptionCompatCreateInput

Returns

Promise<SubscriptionInfo>

get

get: (…args) => Promise<SubscriptionInfo>

Get one subscription by name.

Repo-scoped subscriptions are addressed by (orgName, repoName, name); org-scoped subscriptions omit repoName via the object form: get({ orgName, name }).

Parameters

args

…[ orgName: string, repoName: string, name: string ] | [ ref: { orgName: string; repoName?: string; name: string; } ]

Returns

Promise<SubscriptionInfo>

reveal

reveal: (…args) => Promise<{ webhookUrl?: string; fallbackWebhookUrl?: string; }>

Reveal the raw webhook URL(s) for a subscription.

Reads return only webhookOrigin/fallbackWebhookOrigin (scheme://host); the raw URL path is a bearer secret. This break-glass call returns the raw URL(s) and is audit-logged server-side. Requires repo:configure. Because it returns the secret, a name-scoped principal (e.g. a component setup token) may reveal only the subscriptions it is scoped to — a stricter contract than the redacted get/list, which are unscoped.

Parameters

args

…[ orgName: string, repoName: string, name: string ] | [ ref: { orgName: string; repoName?: string; name: string; } ]

Returns

Promise<{ webhookUrl?: string; fallbackWebhookUrl?: string; }>

list

list: (…args) => Promise<SubscriptionList>

List subscriptions in a scope.

Pass (orgName, repoName) to list a repository’s subscriptions, or omit repoName — list(orgName) or list({ orgName }) — to list the org-scoped subscriptions.

Parameters

args

…[ orgName: string, repoName?: string ] | [ ref: { orgName: string; repoName?: string; } ]

Returns

Promise<SubscriptionList>

update

update: (input) => Promise<SubscriptionInfo>

Update an existing webhook subscription.

Use null for nullable fields such as fallback webhook URL when you need to clear an existing value. Legacy cron subscriptions cannot be updated — delete them instead.

Parameters

input

SubscriptionCompatUpdateInput

Returns

Promise<SubscriptionInfo>

pause

pause: (…args) => Promise<{ name: string; active: boolean; }>

Pause a subscription.

Omit repoName (object form) to pause an org-scoped subscription.

Parameters

args

…[ orgName: string, repoName: string, name: string ] | [ ref: { orgName: string; repoName?: string; name: string; } ]

Returns

Promise<{ name: string; active: boolean; }>

resume

resume: (…args) => Promise<{ name: string; active: boolean; }>

Resume a paused subscription.

Omit repoName (object form) to resume an org-scoped subscription.

Parameters

args

…[ orgName: string, repoName: string, name: string ] | [ ref: { orgName: string; repoName?: string; name: string; } ]

Returns

Promise<{ name: string; active: boolean; }>

remove

remove: (…args) => Promise<{ ok: true; }>

Delete a subscription.

Omit repoName (object form) to delete an org-scoped subscription.

Parameters

args

…[ orgName: string, repoName: string, name: string ] | [ ref: { orgName: string; repoName?: string; name: string; } ]

Returns

Promise<{ ok: true; }>

bindCredentials

bindCredentials: (…args) => Promise<SubscriptionBindCredentialsResult>

Bind a credential set to a subscription for outbound webhook authentication.

Omit repoName (object form) to bind an org-scoped subscription to one of the org’s org-scoped credential sets.

Parameters

args

…[ orgName: string, repoName: string, subscriptionName: string, credentialSetName: string ] | [ ref: { orgName: string; repoName?: string; subscriptionName: string; credentialSetName: string; } ]

Returns

Promise<SubscriptionBindCredentialsResult>

unbindCredentials

unbindCredentials: (…args) => Promise<SubscriptionUnbindCredentialsResult>

Remove the credential set currently bound to a subscription.

Omit repoName (object form) for an org-scoped subscription.

Parameters

args

…[ orgName: string, repoName: string, subscriptionName: string ] | [ ref: { orgName: string; repoName?: string; subscriptionName: string; } ]

Returns

Promise<SubscriptionUnbindCredentialsResult>

See

https://docs.warmhub.ai/sdk/component-identity/#subscriptions

action

readonly action: object

Low-level action lease, delivery, run, and notification primitives for subscription consumers.

acquireLease

acquireLease: (orgName, repoName, subscriptionName, holderId, holderType, opts?) => Promise<ActionLeaseAcquire>

Acquire an exclusive processing lease for a subscription consumer.

Parameters

orgName

string

repoName

string

subscriptionName

string

holderId

string

Stable identifier for the process claiming the lease.

holderType

"sdk" | "cli"

Kind of consumer claiming the lease.

opts?

graceMs?

number

ttlMs?

number

Returns

Promise<ActionLeaseAcquire>

heartbeatLease

heartbeatLease: (orgName, repoName, subscriptionName, holderId, ttlMs?) => Promise<ActionLeaseOp>

Extend the TTL for an existing processing lease.

Parameters

orgName

string

repoName

string

subscriptionName

string

holderId

string

ttlMs?

number

Returns

Promise<ActionLeaseOp>

releaseLease

releaseLease: (orgName, repoName, subscriptionName, holderId) => Promise<ActionLeaseOp>

Release an existing processing lease.

Parameters

orgName

string

repoName

string

subscriptionName

string

holderId

string

Returns

Promise<ActionLeaseOp>

claimDelivery

claimDelivery: (orgName, repoName, target, holderId) => Promise<ActionLeaseOp>

Claim one action delivery for processing.

Parameters

orgName

string

repoName

string

target

ActionDeliveryTarget

holderId

string

Returns

Promise<ActionLeaseOp>

completeDelivery

completeDelivery: (orgName, repoName, target, holderId) => Promise<ActionLeaseOp>

Mark one claimed action delivery as complete.

Parameters

orgName

string

repoName

string

target

ActionDeliveryTarget

holderId

string

Returns

Promise<ActionLeaseOp>

liveFeed

liveFeed: (orgName, repoName, subscriptionName, opts?) => Promise<{ items: Array<{ subscriptionName: string; deliveryId: string; runId?: string; status: string; matchedOperationIndexes: Array<number>; matchedOperations: Array<{ index: number; operation?: unknown; }>; createdAt: number; updatedAt?: number; runStatus?: string; attemptCount?: number; maxAttempts?: number; lastErrorCode?: string; lastErrorMessage?: string; lastResponseSnippet?: string; traceId?: string; causationId?: string; hopCount?: number; originRunId?: string; originRepoId?: string; actionContainer?: string; }>; nextCursor?: string; }>

Query the live delivery feed for a subscription.

Use this for polling or live-log views that need recent delivery status entries.

Parameters

orgName

string

repoName

string

subscriptionName

string

opts?

ActionLiveFeedOptions

Returns

Promise<{ items: Array<{ subscriptionName: string; deliveryId: string; runId?: string; status: string; matchedOperationIndexes: Array<number>; matchedOperations: Array<{ index: number; operation?: unknown; }>; createdAt: number; updatedAt?: number; runStatus?: string; attemptCount?: number; maxAttempts?: number; lastErrorCode?: string; lastErrorMessage?: string; lastResponseSnippet?: string; traceId?: string; causationId?: string; hopCount?: number; originRunId?: string; originRepoId?: string; actionContainer?: string; }>; nextCursor?: string; }>

listRuns

listRuns: (orgName, repoName, opts?) => Promise<Page<{ runId: string; subscriptionName?: string; status: string; matchedOperationIndexes: Array<number>; attemptCount: number; maxAttempts: number; lastErrorCode?: string; lastErrorMessage?: string; traceId?: string; causationId?: string; hopCount?: number; originRunId?: string; originRepoId?: string; createdAt: number; updatedAt: number; }>>

List subscription action runs as a Page<ActionRunInfo> (items + optional nextCursor), newest-first, capped at 200 runs per page.

status and outcome are mutually exclusive. since and cursor are mutually exclusive; pass cursor alone on later pages — the since window rides in the cursor. Cursors are opaque, short-lived resume tokens; on VALIDATION_ERROR restart the query without cursor. See docs/dev/warmhub-actions-api.md for the full contract.

Parameters

orgName

string

repoName

string

opts?

ActionListRunsOptions

Returns

Promise<Page<{ runId: string; subscriptionName?: string; status: string; matchedOperationIndexes: Array<number>; attemptCount: number; maxAttempts: number; lastErrorCode?: string; lastErrorMessage?: string; traceId?: string; causationId?: string; hopCount?: number; originRunId?: string; originRepoId?: string; createdAt: number; updatedAt: number; }>>

runStats

runStats: (orgName, repoName, opts?) => Promise<{ total: number; byStatus: { pending: number; running: number; processing: number; retry_wait: number; succeeded: number; suppressed: number; failed_terminal: number; dead_letter: number; }; }>

Aggregate run counts (total + per-status) for a repo or one subscription.

Computed server-side over an optional since window as a window aggregate — it counts every run in the window, whereas listRuns returns only a page sample of that pageable history. Use runStats for totals and listRuns to walk the individual runs page by page.

Parameters

orgName

string

repoName

string

opts?

ActionRunStatsOptions

Returns

Promise<{ total: number; byStatus: { pending: number; running: number; processing: number; retry_wait: number; succeeded: number; suppressed: number; failed_terminal: number; dead_letter: number; }; }>

getRunAttempts

getRunAttempts: (orgName, repoName, runId) => Promise<{ attempt: number; status: string; startedAt: number; finishedAt?: number; httpStatus?: number; errorCode?: string; errorMessage?: string; responseSnippet?: string; }[]>

List delivery attempts for one action run.

Parameters

orgName

string

repoName

string

runId

string

Returns

Promise<{ attempt: number; status: string; startedAt: number; finishedAt?: number; httpStatus?: number; errorCode?: string; errorMessage?: string; responseSnippet?: string; }[]>

listNotifications

listNotifications: (orgName, repoName, opts?) => Promise<{ subscriptionName?: string; attempt: number; channel: string; status: string; eventType?: string; errorCode?: string; errorMessage?: string; createdAt: number; }[]>

List repo-scoped action notifications.

Use since or limit to bound notification-center style reads.

Parameters

orgName

string

repoName

string

opts?

ActionListNotificationsOptions

Returns

Promise<{ subscriptionName?: string; attempt: number; channel: string; status: string; eventType?: string; errorCode?: string; errorMessage?: string; createdAt: number; }[]>

collection

readonly collection: object

create

create: (orgName, repoName, opts) => Promise<CollectionMutationResult>

Parameters

orgName

string

repoName

string

opts

CollectionCreateOptions

Returns

Promise<CollectionMutationResult>

members

members: (orgName, repoName, wref, opts?) => Promise<CollectionMembersPage>

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

opts?

CollectionMembersOptions

Returns

Promise<CollectionMembersPage>

membersIter

membersIter: (orgName, repoName, wref, opts?) => AsyncIterableIterator<CollectionMember>

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

opts?

CollectionMembersOptions

Returns

AsyncIterableIterator<CollectionMember>

membersAll

membersAll: (orgName, repoName, wref, opts?) => Promise<CollectionMember[]>

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

opts?

CollectionMembersOptions & object

Returns

Promise<CollectionMember[]>

contains

contains: (orgName, repoName, wref, members, opts?) => Promise<CollectionContainsResult>

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

members

string[]

opts?

CollectionContainsOptions

Returns

Promise<CollectionContainsResult>

diff

diff: (orgName, repoName, leftWref, rightWref, opts?) => Promise<CollectionDiffResult>

Parameters

orgName

string | undefined

repoName

string | undefined

leftWref

string

rightWref

string

opts?

CollectionDiffOptions

Returns

Promise<CollectionDiffResult>

revise

revise: (orgName, repoName, wref, opts) => Promise<CollectionMutationResult>

Parameters

orgName

string

repoName

string

wref

string

opts

CollectionReviseOptions

Returns

Promise<CollectionMutationResult>

stats

stats: (orgName, repoName, wref, opts?) => Promise<CollectionStatsResult>

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

opts?

CollectionStatsOptions

Returns

Promise<CollectionStatsResult>

thing

readonly thing: object

Read surface for things, assertions, histories, references, search, and in-place thing renames.

head

head: (orgName, repoName, opts?) => Promise<HeadResult>

Return the current HEAD snapshot for repository contents.

Filter by shape, kind, assertion target, or glob match pattern, and choose the data mode appropriate for the payload size. Component filters can narrow results to component-owned records or hide component infrastructure records.

Tokenless reads of public repositories have stricter page-size and page-count limits than authenticated reads.

Parameters

orgName

string

repoName

string

opts?

ThingHeadOptions

Returns

Promise<HeadResult>

headIter

headIter: (orgName, repoName, opts?) => AsyncIterableIterator<ThingItem>

Iterate every current HEAD row matching the supplied filters.

Prefer this over hand-written cursor loops when scanning all matching records. Pass opts.cursor to resume from a saved cursor; the iterator advances the cursor automatically after the first request. Pass limit to control page size.

Parameters

orgName

string

repoName

string

opts?

ThingHeadOptions

Returns

AsyncIterableIterator<ThingItem>

headAll

headAll: (orgName, repoName, opts?) => Promise<ThingItem[]>

Materialize every current HEAD row matching the supplied filters.

Use max to guard memory usage; throws a WarmHubError with kind VALIDATION_ERROR once more than max items have actually been observed across pages.

Parameters

orgName

string

repoName

string

opts?

ThingHeadOptions & object

Returns

Promise<ThingItem[]>

get

get: (orgName, repoName, wref, version?, opts?) => Promise<ThingDetail>

Get one thing, assertion, shape, or collection by wref.

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

version?

number

Optional exact version to pin when the wref is not already version-qualified.

opts?

ThingGetOptions

Returns

Promise<ThingDetail>

getWithLease

getWithLease: (orgName, repoName, wref, opts?) => Promise<ThingGetWithLease>

Acquire a short, bounded, exclusive lease on a thing AND read it in one atomic round trip (#3625).

Returns everything WarmHub.thing.get returns plus a lease block; the holder echoes lease.id back as leaseId on the subsequent revise/retract (auto-releasing the lease) or calls WarmHub.thing.releaseLease to return it early. Requires things:write — never anonymous.

Fail-fast: if another holder already holds an active lease, throws a WarmHubError with kind === 'LEASE_UNAVAILABLE' and error.details?.reason === 'lease_held' (read leaseExpiresAt to back off until expiry). ttlMs out of the backend’s bounds (default 5s / min 1s / max 30s) is rejected, never clamped.

Parameters

orgName

string

repoName

string

wref

string

opts?

ttlMs?

number

Returns

Promise<ThingGetWithLease>

releaseLease

releaseLease: (orgName, repoName, wref, leaseId) => Promise<void>

Release a lease early (#3625), closing the acquire↔release loop without waiting out the TTL.

Idempotent and owner-gated: releasing an absent, already-released, expired, or non-matching lease is a benign no-op (no error). A successful revise/retract carrying the leaseId already auto-releases the lease, so this is only needed when the holder decides not to mutate. Requires things:write.

Parameters

orgName

string

repoName

string

wref

string

leaseId

string

Returns

Promise<void>

graph

graph: (orgName, repoName, wref, opts?) => Promise<ThingGraphResult>

Get one record and its embedded assertion, about, and wref graph.

Depth and limit options bound traversal size. References the caller cannot read remain string wrefs in the returned graph.

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

opts?

ThingGraphOptions

Returns

Promise<ThingGraphResult>

getMany

getMany: (orgName, repoName, wrefs, version?, opts?) => Promise<ThingGetManyResult>

Batch-fetch wrefs, auto-chunking above the backend’s 500-wref transport cap.

The result preserves duplicate requested wrefs and reports inaccessible or missing refs in missing rather than throwing per item. A top-level version pins every unqualified wref; per-wref version pins remain intact.

Parameters

orgName

string | undefined

repoName

string | undefined

wrefs

string[]

version?

number

Optional exact version to apply to unqualified wrefs.

opts?

includeRetracted?

boolean

Include retracted records in items instead of reporting them in missing.

dataMode?

CollectionReadDataMode

chunkSize?

number

Maximum wrefs per backend request. Defaults to 500 and is clamped to the backend cap.

chunkConcurrency?

number

Maximum concurrent chunk requests. Defaults to 1 and is clamped to 8.

Returns

Promise<ThingGetManyResult>

headVersions

headVersions: (orgName, repoName, wrefs, opts?) => Promise<ThingHeadVersionsResult>

Batched lightweight per-thing change probe — returns { wref, durableId, version, active, revisedOn } per wref with NO payload. Use it to check whether locally-cached copies are still fresh without pulling data: a value is stale if durableId differs (the wref now points to a different thing), version/active differ (the same thing changed/was retracted), or the wref appears in missing.

Auto-chunks above the backend’s 500-wref transport cap; preserves duplicate requested wrefs and reports inaccessible/unknown refs in missing rather than throwing per item.

Parameters

orgName

string | undefined

repoName

string | undefined

wrefs

string[]

opts?

chunkSize?

number

Maximum wrefs per backend request. Defaults to 500 and is clamped to the backend cap.

chunkConcurrency?

number

Maximum concurrent chunk requests. Defaults to 1 and is clamped to 8.

Returns

Promise<ThingHeadVersionsResult>

history

history: (orgName, repoName, opts) => Promise<HistoryResult>

Return version history and timeline metadata for repository records.

Provide at least one selector: a concrete wref, a shape filter, or an assertion target. Shape- and target-filtered histories support pagination and optional collection resolution.

Parameters

orgName

string | undefined

repoName

string | undefined

opts

ThingHistoryOptions

Returns

Promise<HistoryResult>

rename

rename: (orgName, repoName, shapeName, oldName, newName) => Promise<RenameResult>

Rename a thing within its shape namespace.

The rename is applied in place: the thing’s existing history is preserved and no new version is created.

Parameters

orgName

string

repoName

string

shapeName

string

oldName

string

newName

string

Returns

Promise<RenameResult>

resolve

resolve: (orgName, repoName, wref) => Promise<ThingDetail>

Resolve a wref to its current projected record.

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

Returns

Promise<ThingDetail>

about

about: (orgName, repoName, wref, opts?) => Promise<AboutResult>

Return assertions about a shape, shaped thing, or collection target.

Filter by assertion shape or glob match pattern, optionally resolve collection targets, and page through large assertion sets with limit and cursor.

Returns { target?, assertions, nextCursor? }. The array is named assertions, not items. This breaks the repo-wide items convention used by HeadResult, FilterResult, SearchResult, RefsResult, and LogResult; destructure explicitly to avoid the trap:

const { target, assertions } = await client.thing.about(org, repo, "Location/cave");
for (const a of assertions) console.log(a.wref);

Any returned subjective-logic opinion tuple (b, d, u, α) is a binomial opinion — well-formed only when the underlying assertion expresses a binary proposition. See Opinions as Separate Assertions.

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

opts?

AboutOptions

Returns

Promise<AboutResult>

aboutIter

aboutIter: (orgName, repoName, wref, opts?) => AsyncIterableIterator<Assertion>

Iterate every assertion about a shape, shaped thing, or collection target.

Prefer this over hand-written cursor loops when scanning all matching assertions. The iterator reads the assertions envelope field and advances the cursor automatically; pass opts.cursor to resume from a saved cursor and limit to control page size.

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

opts?

AboutOptions

Returns

AsyncIterableIterator<Assertion>

aboutAll

aboutAll: (orgName, repoName, wref, opts?) => Promise<Assertion[]>

Materialize every assertion about a shape, shaped thing, or collection target.

Use max to guard memory usage; throws a WarmHubError with kind VALIDATION_ERROR once more than max assertions have actually been observed across pages.

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

opts?

AboutOptions & object

Returns

Promise<Assertion[]>

query

query: (orgName, repoName, opts?) => Promise<HeadResult>

Query repository records by shape, kind, assertion target, text filters, or glob match pattern.

Use this for structured reads where the caller controls filters. For ranked text or vector search, use thing.search. For count-only reads, use thing.count.

Parameters

orgName

string

repoName

string

opts?

FilterOptions

Returns

Promise<HeadResult>

queryIter

queryIter: (orgName, repoName, opts?) => AsyncIterableIterator<ThingItem>

Iterate every repository record matching the supplied filters.

Parameters

orgName

string

repoName

string

opts?

FilterOptions

Returns

AsyncIterableIterator<ThingItem>

queryAll

queryAll: (orgName, repoName, opts?) => Promise<ThingItem[]>

Materialize every repository record matching the supplied filters.

Use max to guard memory usage; throws a WarmHubError with kind VALIDATION_ERROR once more than max items have actually been observed across pages.

Parameters

orgName

string

repoName

string

opts?

FilterOptions & object

Returns

Promise<ThingItem[]>

search

search: (orgName, repoName, query, opts?) => Promise<HeadResult>

Search repository records with text, vector, or hybrid mode.

When searching with an assertion target or collection resolution, pages may be sparse; keep paginating until nextCursor is absent.

Parameters

orgName

string

repoName

string

query

string

opts?

SearchOptions

Returns

Promise<HeadResult>

count

count: (orgName, repoName, opts?) => Promise<CountResult>

Count matching repository records without returning record data.

Parameters

orgName

string

repoName

string

opts?

CountOptions

Returns

Promise<CountResult>

refs

refs: (orgName, repoName, wref, opts?) => Promise<RefsResult>

Query wref-typed field references for a record.

Inbound mode finds records whose wref fields point at the supplied wref. Outbound mode finds records that the supplied record points to. Inbound queries can be narrowed to a field path.

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

opts?

RefsOptions

Returns

Promise<RefsResult>

refsIter

refsIter: (orgName, repoName, wref, opts?) => AsyncIterableIterator<{ wref: string; kind?: "assertion" | "thing" | "shape" | "collection"; shapeName?: string; version?: number; fieldPath?: string; }>

Iterate every wref-typed field reference for a record.

Prefer this over hand-written cursor loops when scanning all matching references. Pass opts.cursor to resume from a saved cursor; the iterator advances the cursor automatically after the first request. Pass limit to control page size.

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

opts?

RefsOptions

Returns

AsyncIterableIterator<{ wref: string; kind?: "assertion" | "thing" | "shape" | "collection"; shapeName?: string; version?: number; fieldPath?: string; }>

refsAll

refsAll: (orgName, repoName, wref, opts?) => Promise<object[]>

Materialize every wref-typed field reference for a record.

Use max to guard memory usage; throws a WarmHubError with kind VALIDATION_ERROR once more than max refs have actually been observed across pages.

Parameters

orgName

string | undefined

repoName

string | undefined

wref

string

opts?

RefsOptions & object

Returns

Promise<object[]>

live

readonly live: object

Live repository update surface backed by server-sent events.

thingHead

thingHead: (orgName, repoName, opts, onUpdate) => Promise<LiveHandle>

Stream refreshed thing.head results whenever the repository changes.

The SDK re-runs the underlying thing.head query after each invalidation and passes the latest snapshot to onUpdate.

Parameters

orgName

string

repoName

string

opts

LiveThingHeadOptions | undefined

onUpdate

(result) => void | Promise<void>

Returns

Promise<LiveHandle>

thingHistory

thingHistory: (orgName, repoName, opts, onUpdate) => Promise<LiveHandle>

Stream refreshed history results for a single wref whenever the repository changes.

Parameters

orgName

string

repoName

string

opts

LiveThingHistoryOptions

onUpdate

(result) => void | Promise<void>

Returns

Promise<LiveHandle>

subscriptionLog

subscriptionLog: (orgName, repoName, subscriptionName, opts, onUpdate) => Promise<LiveHandle>

Stream refreshed action live-feed entries for a subscription.

Parameters

orgName

string

repoName

string

subscriptionName

string

opts

LiveSubscriptionLogOptions | undefined

onUpdate

(result) => void | Promise<void>

Returns

Promise<LiveHandle>

subscribe: (orgName, repoName, opts, onEvent) => Promise<LiveHandle>

Subscribe to raw repository invalidation events.

Unlike the higher-level live helpers, this method does not re-query. It forwards invalidation metadata such as affected shapes, affected things, affected assertion targets, and whether the event corresponds to a new commit.

Parameters

orgName

string

repoName

string

opts

{ signal?: AbortSignal; } | undefined

Type Literal

{ signal?: AbortSignal; }

signal?

AbortSignal

Optional abort signal used to close the SSE stream.

undefined

onEvent

(event) => void | Promise<void>

Callback invoked for each repository invalidation event.

Returns

Promise<LiveHandle>

token

readonly token: object

Personal access token management for the authenticated user.

create

create: (input) => Promise<{ token: string; name: string; scopes?: Array<{ resource?: string; permissions: Array<string>; allowedMatches?: Array<string>; }>; warnings?: Array<string>; expiresAt: number; createdAt: number; }>

Create a personal access token for the authenticated user.

Omit scopes to mint a token with the same authority as the calling principal. PATs cannot create or revoke other PATs — token-management permissions are excluded from the grantable set. Server enforces a maximum lifetime; pass an expiresAt unix-millis value to clamp earlier.

See Personal Access Tokens for scope grammar (resource format, permission strings, allowedMatches), rotation, and CI usage.

Parameters

input

{ name: string; scopes?: Array<{ resource?: string; permissions: Array<string>; allowedMatches?: Array<string>; }>; structured?: boolean; description?: string; expiresAt?: number; committerIdentityWref?: string; }

Returns

Promise<{ token: string; name: string; scopes?: Array<{ resource?: string; permissions: Array<string>; allowedMatches?: Array<string>; }>; warnings?: Array<string>; expiresAt: number; createdAt: number; }>

list

list: (opts?) => Promise<TokenInfo[]>

List personal access tokens for the authenticated user.

By default only active tokens are returned. Pass { includeInactive: true } to also include expired and revoked tokens.

Parameters

opts?

includeInactive?

boolean

Returns

Promise<TokenInfo[]>

get

get: (name) => Promise<TokenInfo | null>

Get one personal access token by name.

Parameters

name

string

Returns

Promise<TokenInfo | null>

revoke

revoke: (name) => Promise<{ ok: boolean; }>

Revoke a personal access token by name.

Parameters

name

string

Returns

Promise<{ ok: boolean; }>

stream

readonly stream: object

Low-level stream append surface for callers that already have backend stream operations.

append

append: (input) => Promise<StreamAppendResult>

Append one non-empty chunk of stream operations to a repository.

Most callers should prefer commit.apply or OperationBuilder. Use this low-level surface only when you already have backend-shaped stream operations and a caller-managed stream ID.

Parameters

input

StreamAppendInput

Returns

Promise<StreamAppendResult>

credential

readonly credential: object

Credential set management for subscription webhook authentication and component integrations.

Sets are scoped at creation time. Repo-scoped sets are visible only to the owning repo; org-scoped sets can be granted to multiple repositories in the same organization. Methods that operate on a specific set accept repoName: string | undefined — pass the owning repo name for repo-scoped sets or undefined for org-scoped sets.

createSet

createSet: (orgName, repoName, name, opts?) => Promise<CredentialInfo>

Create a credential set.

Credential sets are repo-scoped by default. Org-scoped sets can be granted to multiple repositories in the same organization.

Parameters

orgName

string

repoName

string | undefined

name

string

opts?

scope?

"org" | "repo"

description?

string

Returns

Promise<CredentialInfo>

listSets

listSets: (orgName, repoName?) => Promise<CredentialInfo[]>

List credential sets visible from a repository.

Parameters

orgName

string

repoName?

string

Returns

Promise<CredentialInfo[]>

getSet

getSet: (orgName, repoName, name) => Promise<CredentialInfo>

Get credential set metadata without secret values.

Parameters

orgName

string

repoName

string | undefined

name

string

Returns

Promise<CredentialInfo>

setKey

setKey: (orgName, repoName, setName, keyName, value) => Promise<CredentialKeyMutationResult>

Set or replace one secret key in a credential set.

Parameters

orgName

string

repoName

string | undefined

setName

string

keyName

string

value

string

Returns

Promise<CredentialKeyMutationResult>

setKeys

setKeys: (orgName, repoName, setName, secrets) => Promise<CredentialKeyMutationResult>

Set or replace multiple secret keys in one request.

Parameters

orgName

string

repoName

string | undefined

setName

string

secrets

Record<string, string>

Returns

Promise<CredentialKeyMutationResult>

unsetKey

unsetKey: (orgName, repoName, setName, keyName) => Promise<CredentialKeyMutationResult>

Remove one secret key from a credential set.

Parameters

orgName

string

repoName

string | undefined

setName

string

keyName

string

Returns

Promise<CredentialKeyMutationResult>

deleteSet

deleteSet: (orgName, repoName, setName) => Promise<CredentialDeleteResult>

Delete a credential set and its stored secrets.

Parameters

orgName

string

repoName

string | undefined

setName

string

Returns

Promise<CredentialDeleteResult>

listAuditLog

listAuditLog: (orgName, repoName, setName, opts?) => Promise<CredentialAuditEntry[]>

List audit entries for a credential set.

Parameters

orgName

string

repoName

string | undefined

setName

string

opts?

limit?

number

Returns

Promise<CredentialAuditEntry[]>

revokeSet

revokeSet: (orgName, repoName, setName, opts?) => Promise<CredentialRevokeResult>

Revoke a credential set so it can no longer be exported or bound.

Parameters

orgName

string

repoName

string | undefined

setName

string

opts?

reason?

string

Returns

Promise<CredentialRevokeResult>

Methods

withAccessToken()

withAccessToken(accessToken): WarmHubClient

Return a new client that shares this client’s backend URL and fetch implementation but uses a different access-token provider.

Parameters

accessToken

AccessTokenProvider

Returns

WarmHubClient