TypeScript — @hesohq/sdk

init()function#

Resolve and install the engine runtime config: the project root holding heso.toml and heso-local-data/, the default workflow/account stamped on each action, an optional pinned clock, and the blocking/observe-only switch. Resolution order for each setting: explicit option, then environment (HESO_*), then discovery, then default.

init(options?: InitOptions): HesoRuntimeConfig

Parameters

options.projectRootstring

Directory holding heso.toml. Defaults to $HESO_PROJECT_ROOT, then the nearest ancestor with a heso.toml, then the cwd.

options.workflowstring= "default"

Workflow id stamped on actions (env HESO_WORKFLOW).

options.accountstring= "default"

Account/tenant stamped on actions (env HESO_ACCOUNT).

options.clockOverridestring

An RFC-3339 instant pinned into every action for reproducible runs (env HESO_CLOCK).

options.blockingboolean= true

When true a blocked/suspended action throws; false is observe-only (env HESO_BLOCKING).

ReturnsHesoRuntimeConfig

The resolved HesoRuntimeConfig. Read it back any time with currentConfig().

Example

import { init } from "@hesohq/sdk"

// Call once at startup, before you gate anything. It finds heso.toml and
// heso-local-data/ (operator key, audit log) from the project root and stamps a
// default workflow/account on every captured action.
init({ workflow: "vendor-payouts", account: "acct_19" })

configure()function#

Set the cloud credentials once at startup. Stores config the cloud client reads on every request. Call it before pullPolicy, pushReceipt, or any approval call.

configure(apiKey: string, endpoint: string): void

Parameters

apiKeystringrequired

Your org’s API key, sent as the x-api-key header. The org is resolved from it server-side.

endpointstringrequired

The base URL of your control plane.

Returns

Nothing. It stores module-level config in place.

Example

import { configure } from "@hesohq/sdk"

configure(process.env.HESO_API_KEY!, process.env.HESO_ENDPOINT!)

gate()function#

Verify a receipt and return a result. Never throws on a failed verdict — it reports it. Use this when you want to branch on the outcome.

gate(receiptBytes: Buffer | string, minTrust?: TrustLevel = "L0"): GateResult

Parameters

receiptBytesBuffer | stringrequired

The receipt JSON, as a string or buffer.

minTrustTrustLevel= "L0"

The minimum re-derived trust level required to allow.

ReturnsGateResult

A GateResult of { allowed: boolean; trustLevel: TrustLevel | null; verdict: string }. verdict is the engine verdict tag (e.g. Valid, HashMismatch); trustLevel is null when verification fails before trust is re-derived.

Example

import { gate } from "@hesohq/sdk"
import { readFile } from "node:fs/promises"

const bytes = await readFile("receipt.json", "utf8")
const result = gate(bytes, "L1")

if (!result.allowed) {
  // result.verdict is the engine tag, e.g. "HashMismatch"
  console.error("rejected:", result.verdict, result.trustLevel)
}

assertGate()function#

The throwing form of gate. Returns normally when the receipt verifies and meets minTrust; throws otherwise. Use it as a guard before a sensitive code path.

assertGate(receiptBytes: Buffer | string, minTrust?: TrustLevel = "L0"): void

Parameters

receiptBytesBuffer | stringrequired

The receipt JSON, as a string or buffer.

minTrustTrustLevel= "L0"

The minimum trust level required to pass.

Returns

Nothing on success; throws when the receipt is not allowed.

Throws

An error carrying the resolved verdict when verification fails or the trust level is below minTrust.

Example

import { assertGate } from "@hesohq/sdk"

// Throws unless the receipt verifies AND meets the minimum trust level.
assertGate(receiptBytes, "L1")

// Past this line the action is authorized and human-approved.
fulfillOrder(order)

isDecisionAllowed()function#

Check whether a receipt’s recorded decision path is one you accept. This reads the policy outcome already embedded in the receipt; it does not re-verify signatures. Pair it with gate when authenticity matters.

isDecisionAllowed(receipt: ActionReceipt, allowedPaths: DecisionPath[]): boolean

Parameters

receiptActionReceiptrequired

A parsed receipt object.

allowedPathsDecisionPath[]required

The decision paths you treat as acceptable, e.g. ["allow", "redact"].

Returnsboolean

true when the receipt’s decision path is in allowedPaths.

Example

import { isDecisionAllowed } from "@hesohq/sdk"
import type { ActionReceipt } from "@hesohq/sdk"

const receipt: ActionReceipt = JSON.parse(receiptBytes)

if (isDecisionAllowed(receipt, ["allow", "redact"])) {
  // The policy let this action through (possibly after redaction).
}

shortHash()function#

Render a long hex hash in short form: the first eight characters, optionally namespaced with a prefix. For logs and UI.

shortHash(hex: string, prefix?: string): string

Parameters

hexstringrequired

A hex string such as an action_hash or a chain hash.

prefixstring

An optional label rendered as prefix:first8.

Returnsstring

The short form: first8, or prefix:first8 when a prefix is given.

Example

import { shortHash } from "@hesohq/sdk"

shortHash("9f2c4e7a1b08d3f6…")            // "9f2c4e7a"
shortHash("9f2c4e7a1b08d3f6…", "action")  // "action:9f2c4e7a"

wrap()function#

Wrap a client so it verifies every method result carrying a __heso_receipt. The returned object has the same type as the original, so you can swap it in with no other changes.

wrap<T extends object>(client: T, options?: WrapOptions): T

Parameters

clientTrequired

The object to wrap. Each method is intercepted; results without a __heso_receipt pass through unchanged.

optionsWrapOptions

Per-wrap configuration; documented below.

ReturnsT

A proxy of the same type T as the wrapped client.

Example

import { wrap, configure, pushReceipt } from "@hesohq/sdk"

configure(process.env.HESO_API_KEY!, process.env.HESO_ENDPOINT!)

const gated = wrap(paymentsClient, {
  minTrust: "L1",
  onGateFail: (method, verdict) => {
    console.error(`${method} blocked by gate: ${verdict}`)
    return false // do not let the result through
  },
  onReceipt: (method, receiptJson) => {
    void pushReceipt(JSON.parse(receiptJson))
  },
})

// Each method result is checked by reading its __heso_receipt field.
await gated.createTransfer({ amountUsd: 4200, payee: "Globex LLC" })

WrapOptions controls the trust floor and the two hooks fired around gating:

pullPolicy()function#

Pull the org’s current pinned policy bundle. Maps to GET /v1/policy/pull.

pullPolicy(): Promise<PolicyPullResult>

ReturnsPromise<PolicyPullResult>

A PolicyPullResult of { status: "policy" | "up_to_date"; policyId: string; policyHash: string; toml: string }. An empty toml is the fail-safe deny pin: the engine routes every action to a human when the org has no resolvable policy. See policy files for the format.

Example

import { pullPolicy } from "@hesohq/sdk"

// The org is resolved from your api-key — there is no team id.
const bundle = await pullPolicy()
console.log(bundle.status, bundle.policyId, bundle.toml.length)

pushReceipt()function#

Push one receipt to the cloud outbox. Maps to POST /v1/receipts; the server re-verifies before mirroring.

pushReceipt(receipt: ActionReceipt, supersedesActionHash?: string): Promise<ReceiptPushResult>

Parameters

receiptActionReceiptrequired

The signed receipt to mirror.

supersedesActionHashstring

Set only when finalizing an approval: the freshly assembled L1 supersedes the suspended L0 entry’s action_hash it was built from.

ReturnsPromise<ReceiptPushResult>

A ReceiptPushResult of { status: "appended" | "duplicate" | "quota_exceeded"; entryHash: string; seq: number }. entryHash echoes the receipt’s own action_hash.

Example

import { pushReceipt } from "@hesohq/sdk"
import type { ActionReceipt } from "@hesohq/sdk"

const receipt: ActionReceipt = JSON.parse(receiptBytes)
const result = await pushReceipt(receipt) // server re-verifies before mirroring

if (result.status === "quota_exceeded") {
  console.warn("monthly mirror cap hit — local chain is unaffected")
}

pushReceipts()function#

Push a batch of receipts. There is no server-side batch route — this loops over POST /v1/receipts in order.

pushReceipts(receipts: ActionReceipt[]): Promise<ReceiptPushResult[]>

Parameters

receiptsActionReceipt[]required

The receipts to push, in order.

ReturnsPromise<ReceiptPushResult[]>

A ReceiptPushResult[]: one result per receipt, in order.

Example

import { pushReceipts } from "@hesohq/sdk"

// Loops POST /v1/receipts in order (there is no server-side batch route).
const results = await pushReceipts(pending)
const appended = results.filter((r) => r.status === "appended")

pollApproval()function#

Read the current state of an approval once, keyed by the action it gates. Maps to GET /v1/approvals/{action_hash}.

pollApproval(actionHash: string): Promise<ApprovalView>

Parameters

actionHashstringrequired

The action_hash of the suspended action.

ReturnsPromise<ApprovalView>

An ApprovalView of { approvalId; actionHash; status: "pending" | "approved" | "rejected"; threshold; approvedCount; resolvedAt }.

Example

import { pollApproval } from "@hesohq/sdk"

// Approvals are keyed by the action_hash they gate, not an opaque approval id.
const view = await pollApproval(actionHash)

if (view.status === "approved") {
  console.log(`${view.approvedCount}/${view.threshold} approvers signed`)
}

waitForApproval()function#

Poll an approval until it resolves, then return it. On approved it makes one extra call to getL1Parts so you can finalize without re-polling.

waitForApproval(actionHash: string, options?: { pollIntervalMs?: number; timeoutMs?: number }): Promise<ResolvedApproval>

Parameters

actionHashstringrequired

The action to wait on.

options.pollIntervalMsnumber= 2000

How often to poll, in milliseconds.

options.timeoutMsnumber= 300000

How long to wait before giving up, in milliseconds.

ReturnsPromise<ResolvedApproval>

A ResolvedApproval: the ApprovalView plus parts (the L1 relay parts on approved; null on rejected).

Throws

An error when the timeout elapses before the approval resolves.

Example

import { waitForApproval } from "@hesohq/sdk"

// Polls every 2s, throws after 5min by default. On "approved" it fetches the L1
// relay parts once so you can finalize without re-polling.
const resolved = await waitForApproval(actionHash, {
  pollIntervalMs: 3000,
  timeoutMs: 120000,
})

getL1Parts()function#

Fetch the parts the cloud relays for finalizing an approved gate into an L1 receipt. Reads GET /v1/approvals/{action_hash}/assembly and takes the single approver leg.

getL1Parts(actionHash: string): Promise<L1Parts>

Parameters

actionHashstringrequired

The approved action’s action_hash.

ReturnsPromise<L1Parts>

An L1Parts of { record; approverPubkeyB64; coSigB64; suspendedContent }: the approver’s verbatim signed record and co-signature plus the byte-exact suspended content the L1 is reassembled from. Pass it to finalizeL1.

Example

import { getL1Parts } from "@hesohq/sdk"

// The approver's verbatim signed record + co-signature + the byte-exact
// suspended content the L1 is reassembled from. Fetch once, after "approved".
const parts = await getL1Parts(actionHash)

finalizeQuorum() / getQuorumParts()function#

The k-of-n sibling of finalizeL1. getQuorumParts(actionHash) fetches every approver leg plus the threshold, roster, and suspended content; finalizeQuorum assembles, re-verifies, and pushes the L1 receipt with a multi_approval block. A single non-approval anywhere throws ApprovalRejectedError.

finalizeQuorum(suspendedContent: ActionContent, relayedParts: QuorumParts, options?): Promise<ActionReceipt>

Parameters

suspendedContentActionContentrequired

The operator-stamped suspended content the legs were co-signed against (read it off parts.suspendedContent).

relayedPartsQuorumPartsrequired

The QuorumParts from getQuorumParts: the approver legs, threshold, and roster.

options{ keyPassphrase?; loadedOperatorPubkeyB64?; onKeyRotation? }

Optional passphrase and key-rotation recovery hooks.

ReturnsPromise<ActionReceipt>

The signed quorum ActionReceipt (L1 with a multi_approval block), already mirror-pushed.

Example

import { getQuorumParts, finalizeQuorum } from "@hesohq/sdk"

// A k-of-n gate. getQuorumParts returns every approver leg plus the threshold,
// roster, and suspended content; finalizeQuorum assembles the L1 receipt from them.
const parts = await getQuorumParts(actionHash)
const receipt = await finalizeQuorum(parts.suspendedContent, parts)

submitApprovalToken()function#

Submit a human-signed approval token for an open approval, keyed by the action it gates. Maps to POST /v1/approvals/{action_hash}/submit-token. The cloud verifies the token against the org’s registered approver keys and records it as a vote.

submitApprovalToken(actionHash: string, input: SubmitTokenInput): Promise<ApprovalView>

Parameters

actionHashstringrequired

The action being approved.

inputSubmitTokenInputrequired

{ tokenB64; actionContent; requiredScope?; decision?; reason?; … }: the base64 token, the receipt content it signs over, and the human’s decision.

ReturnsPromise<ApprovalView>

The updated ApprovalView.

Example

import { submitApprovalToken } from "@hesohq/sdk"

// Redeem the token a reviewer signed with their device-held key. Keyed by the
// action_hash; the cloud verifies it against the org's registered approver keys.
const view = await submitApprovalToken(actionHash, {
  tokenB64,
  actionContent: receipt.content,
  decision: "approved",
})