WarmHubClient

Primary TypeScript client for the WarmHub API.

The client groups API calls by domain (repo, thing, shape, commit, subscription, and related surfaces), applies configured authentication to every request, and normalizes most transport and backend failures through WarmHubError. Streamed commit writes may instead throw PartialStreamSubmissionError when an append outcome is ambiguous.

See

https://docs.warmhub.ai/sdk/client/

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>

access

readonly access: object

Lightweight permission checks for UI gating and service-side authorization probes.

checkRepoPermission

checkRepoPermission: (orgName, repoName, permission) => Promise<boolean>

Check whether the caller has a repo-scoped permission.

Parameters

orgName

string

repoName

string

permission

string

Permission string such as repo:read, repo:write, repo:configure, or repo:admin.

Returns

Promise<boolean>

checkOrgPermission

checkOrgPermission: (orgName, permission) => Promise<boolean>

Check whether the caller has an org-scoped permission.

Parameters

orgName

string

permission

string

Permission string such as org:read, org:configure, or org:admin.

Returns

Promise<boolean>

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<{ componentId: string; componentName: string; version?: string; state?: string; source?: string; sourceRef?: string; resolvedSha?: string; manifestHash?: string; installedAt?: string; checkedAt?: string; active: boolean; wref: string; }>; nextCursor?: string; }>

List components installed in a repository.

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

Parameters

orgName

string

repoName

string

opts?

ComponentListOptions

Returns

Promise<{ items: Array<{ componentId: string; componentName: string; version?: string; state?: string; source?: string; sourceRef?: string; resolvedSha?: string; manifestHash?: string; installedAt?: string; checkedAt?: string; active: boolean; wref: string; }>; nextCursor?: string; }>

get

get: (orgName, repoName, componentId) => Promise<{ componentId: string; componentName: string; version?: string; state?: string; source?: string; sourceRef?: string; resolvedSha?: string; manifestHash?: string; installedAt?: string; checkedAt?: string; active: boolean; wref: string; install: { wref: string; pinnedWref?: string; name: string; kind: 'shape' | 'thing' | 'assertion' | 'collection'; shape?: string; shapeName?: string; validatedShape?: string; version: number; data?: unknown; active: boolean; aboutWref?: string; committerWref?: string; createdByWref?: string; metadata?: { durableId: string; thingCreatedAt: number; versionCreatedAt: number; }; }; ownedShapes: Array<{ name: string; kind: 'shape'; active: boolean; version: { version: number; operation: 'add' | 'revise' | 'retract'; data: unknown; dataHash: string; } | null; componentId?: string; }>; ownedThings: Array<{ wref: string; name: string; kind: 'shape' | 'thing' | 'assertion' | 'collection'; shapeName?: string; componentId?: string; version: number; createdAt: number; data?: unknown; active: boolean; aboutWref?: string; metadata?: { durableId: string; thingCreatedAt: number; versionCreatedAt: number; }; }>; }>

Fetch one installed component by component ID.

Parameters

orgName

string

repoName

string

componentId

string

Returns

Promise<{ componentId: string; componentName: string; version?: string; state?: string; source?: string; sourceRef?: string; resolvedSha?: string; manifestHash?: string; installedAt?: string; checkedAt?: string; active: boolean; wref: string; install: { wref: string; pinnedWref?: string; name: string; kind: 'shape' | 'thing' | 'assertion' | 'collection'; shape?: string; shapeName?: string; validatedShape?: string; version: number; data?: unknown; active: boolean; aboutWref?: string; committerWref?: string; createdByWref?: string; metadata?: { durableId: string; thingCreatedAt: number; versionCreatedAt: number; }; }; ownedShapes: Array<{ name: string; kind: 'shape'; active: boolean; version: { version: number; operation: 'add' | 'revise' | 'retract'; data: unknown; dataHash: string; } | null; componentId?: string; }>; ownedThings: Array<{ wref: string; name: string; kind: 'shape' | 'thing' | 'assertion' | 'collection'; shapeName?: string; componentId?: string; version: number; createdAt: number; data?: unknown; active: boolean; aboutWref?: string; metadata?: { durableId: string; thingCreatedAt: number; versionCreatedAt: number; }; }>; }>

installSystem

installSystem: (orgName, repoName, componentId) => Promise<{ componentId: string; componentName: string; version: string; state: 'ready' | 'unchanged'; componentInstallShapeCreated: boolean; componentInstallShapeReconciled: boolean; componentConfigShapeCreated: boolean; componentConfigShapeReconciled: boolean; componentInstallRecordCreated: boolean; componentInstallRecordReconciled: boolean; identityShapeCreated: boolean; identityShapeReconciled: boolean; }>

Install an allowlisted bundled system component into a repository.

Parameters

orgName

string

repoName

string

componentId

string

Returns

Promise<{ componentId: string; componentName: string; version: string; state: 'ready' | 'unchanged'; componentInstallShapeCreated: boolean; componentInstallShapeReconciled: boolean; componentConfigShapeCreated: boolean; componentConfigShapeReconciled: boolean; componentInstallRecordCreated: boolean; componentInstallRecordReconciled: boolean; identityShapeCreated: boolean; identityShapeReconciled: boolean; }>

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 mints an install id, downloadSource fetches the source archive through the backend, 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<{ id: string; 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; } = {}

Returns

Promise<{ id: string; 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<{ id: string; 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<{ id: string; 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

Returns

registry.resolve

resolve: (orgName, componentName, installRepo) => Promise<{ sourceUrl: string; sourceDefaultRef?: string; hasSetup: boolean; installId: string; }>

Parameters

orgName

string

componentName

string

installRepo

string

Returns

Promise<{ sourceUrl: string; sourceDefaultRef?: string; hasSetup: boolean; installId: string; }>

registry.downloadSource

downloadSource: (orgName, componentName, input) => Promise<{ archive: Uint8Array; sourceUrl: string; sourceRef?: string; resolvedSha?: string; componentRef: string; contentType: string; }>

Parameters

orgName

string

componentName

string

input

{ installRepo: string; ref?: string; }

Returns

Promise<{ archive: Uint8Array; sourceUrl: string; sourceRef?: string; resolvedSha?: string; componentRef: string; contentType: string; }>

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; ref?: string; resolvedSha?: 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 wref identifying the actor on whose behalf the write is made. Must be a full wref string like "Agent/bot-1" (a thing that already exists), or a cross-repo wref like "wh:other-org/other-repo/Agent/bot-1". Bare names such as "eval-runner" are rejected by the backend with a “Thing wref required” error — there is no implicit shape.

componentId?

string

Attribute writes to an installed component 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.

allocatedTokens?

object[]

Advanced continuation hook for $N / #N token allocation state.

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>

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; }>

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; }>

hardDelete

hardDelete: (orgName, repoName) => Promise<void>

Immediately and irreversibly purge a repository.

This owner-only operation has no grace window and uses the same inbound-reference guard as delete.

Parameters

orgName

string

repoName

string

Returns

Promise<void>

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>

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>

generateReadme

generateReadme: (orgName, repoName) => Promise<{ content: string; }>

Generate a README draft from the repository’s current shapes, things, and assertions.

This does not commit the draft. Save returned content with setReadme after review.

Parameters

orgName

string

repoName

string

Returns

Promise<{ content: string; }>

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; operations: Array<{ opIndex?: number; name: string; operation: 'add' | 'revise' | 'retract' | 'noop'; version: number; dataHash: string; status?: 'applied' | 'noop'; warnings?: { undeclaredFields: Array<string>; undeclaredFieldsTruncated?: true; totalUndeclared?: number; }; }>; }>

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; operations: Array<{ opIndex?: number; name: string; operation: 'add' | 'revise' | 'retract' | 'noop'; version: number; dataHash: string; status?: 'applied' | 'noop'; warnings?: { undeclaredFields: Array<string>; undeclaredFieldsTruncated?: true; totalUndeclared?: number; }; }>; }>

setAgents

setAgents: (orgName, repoName, content) => Promise<{ committer?: string; createdByEmail?: string; message?: string; operationCount: number; operations: Array<{ opIndex?: number; name: string; operation: 'add' | 'revise' | 'retract' | 'noop'; version: number; dataHash: string; status?: 'applied' | 'noop'; warnings?: { undeclaredFields: Array<string>; undeclaredFieldsTruncated?: true; totalUndeclared?: number; }; }>; }>

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

Parameters

orgName

string

repoName

string

content

string

Returns

generateAgents

generateAgents: (orgName, repoName) => Promise<{ content: string; }>

Generate an AGENTS.md draft from the repository’s current content and schema.

This does not commit the draft. Save returned content with setAgents after review.

Parameters

orgName

string

repoName

string

Returns

Promise<{ content: string; }>

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; componentId?: 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; componentId?: 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; componentId?: 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; componentId?: string; }>

create

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

revise

revise: (orgName, repoName, shapeName, newFields, opts?) => Promise<{ name: string; operation: 'add' | 'revise' | 'retract'; 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'; 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 and cron subscription management surface scoped to a repository.

create

create: (input) => Promise<SubscriptionInfo>

Create a webhook or cron subscription.

Both subscription kinds require a delivery URL. Webhook subscriptions can also forward events from another repository, allow trace reentry, bind fallback delivery, and opt into success notifications. Component identity is set at creation time and follows the same authority rules as commit writes.

Webhook subscriptions must specify a shape filter via shapeName or filterJson.shape, except shape-lifecycle subscriptions which omit both and rely on a { kind: 'shape', ... } filter.

Parameters

input

SubscriptionCompatCreateInput

Returns

Promise<SubscriptionInfo>

get

get: (orgName, repoName, name) => Promise<SubscriptionInfo>

Get one subscription by name.

Parameters

orgName

string

repoName

string

name

string

Returns

Promise<SubscriptionInfo>

list

list: (orgName, repoName) => Promise<SubscriptionList>

List subscriptions attached to a repository.

Parameters

orgName

string

repoName

string

Returns

Promise<SubscriptionList>

update

update: (input) => Promise<SubscriptionInfo>

Update an existing webhook or cron subscription.

Use null for nullable fields such as fallback webhook URL when you need to clear an existing value.

Parameters

input

SubscriptionCompatUpdateInput

Returns

Promise<SubscriptionInfo>

pause

pause: (orgName, repoName, name) => Promise<{ name: string; active: boolean; }>

Pause a subscription.

Parameters

orgName

string

repoName

string

name

string

Returns

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

resume

resume: (orgName, repoName, name) => Promise<{ name: string; active: boolean; }>

Resume a paused subscription.

Parameters

orgName

string

repoName

string

name

string

Returns

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

remove

remove: (orgName, repoName, name) => Promise<{ ok: true; }>

Delete a subscription.

Parameters

orgName

string

repoName

string

name

string

Returns

Promise<{ ok: true; }>

bindCredentials

bindCredentials: (orgName, repoName, subscriptionName, credentialSetName) => Promise<SubscriptionBindCredentialsResult>

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

Parameters

orgName

string

repoName

string

subscriptionName

string

credentialSetName

string

Returns

Promise<SubscriptionBindCredentialsResult>

unbindCredentials

unbindCredentials: (orgName, repoName, subscriptionName) => Promise<SubscriptionUnbindCredentialsResult>

Remove the credential set currently bound to a subscription.

Parameters

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

"cli" | "sdk"

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, runId, holderId) => Promise<ActionLeaseOp>

Claim one action delivery run for processing.

Parameters

orgName

string

repoName

string

runId

string

holderId

string

Returns

Promise<ActionLeaseOp>

completeDelivery

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

Mark one claimed action delivery run as complete.

Parameters

orgName

string

repoName

string

runId

string

holderId

string

Returns

Promise<ActionLeaseOp>

liveFeed

liveFeed: (orgName, repoName, subscriptionName, opts?) => Promise<{ items: Array<{ subscriptionName: 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; 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<{ 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 for a repository.

The result can be filtered by subscription name, status, and start time.

Parameters

orgName

string

repoName

string

opts?

ActionListRunsOptions

Returns

Promise<{ 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; }[]>

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; }[]>

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.

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>

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

FilterOptions

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?: "shape" | "thing" | "assertion" | "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?: "shape" | "thing" | "assertion" | "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: () => Promise<TokenInfo[]>

List personal access tokens for the authenticated user.

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 stream operations, a stream ID, and any allocated $N / #N token state you need to continue.

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?

"repo" | "org"

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

Hit a problem or have a question? Get in touch.