@botiverse/stamp-sdk
v0.2.3
Published
JavaScript SDK for Stamp
Keywords
Readme
@botiverse/stamp-sdk
JavaScript SDK for Stamp. Node >= 20, ESM only. Published by .github/workflows/publish-sdk.yml.
This package has no command line. The stamp command line is the Go one
(@botiverse/stamp-cli); the agent workflow is the instance's own
/llms.txt.
Session and client
import { resolveAuth, makeClient, runAgentLogin } from "@botiverse/stamp-sdk";
// A managed Raft agent uses its stored Stamp session; anyone else STAMP_TOKEN.
const auth = resolveAuth({ urlBase: "https://stamp.build" });
if (auth.mode === "agent") {
// Once per session: a PKCE grant through `raft integration invoke`.
await runAgentLogin(auth.agentEnv, auth.apiBase, { service: auth.service });
}
const api = makeClient(auth); // api(method, path, body) -> parsed JSONapi refreshes an agent's access token before it expires and once after a
401, retries idempotent reads on a connection failure (never writes), and
throws ApiError (status, body, requestId) for an HTTP error or
NetworkError when the gateway could not be reached. A local refusal is an
AgentError whose code is stable and whose message is English.
In a Worker: @botiverse/stamp-sdk/client
The ./client entry has the client, the request paths and validators, and
nothing that needs a disk or a process: no agent login (it spawns raft), no
file-backed session store, no git or SSH helpers. A host that keeps the agent's
Stamp session itself hands it in and takes every rotated one back:
import { makeClient, injectedAgentAuth, checkPublishedReceipt } from "@botiverse/stamp-sdk/client";
const auth = injectedAgentAuth({
apiBase: "https://stamp.build",
getSession: async () => sealed.read(), // a raft-cli-agent-session.v1
onSession: async (session) => sealed.write(session), // awaited before it is used
});
const api = makeClient(auth, fetch, { retryReads: false }); // the host decides retries
const check = await checkPublishedReceipt(api, receiptId); // one read, never blocks
if (!check.published) { /* look again later: check.status */ }- The access token is rotated before it expires, and once after a 401. Concurrent calls share one rotation (a refresh token is single-use); across processes the host's store must serialize.
- A rotated session that
onSessioncannot store fails the call: it is never used unstored. retryReads: falsesends every request once; the 401 rotation is the one exception. By default a failed read is retried twice and a write never.- Errors: an HTTP error is
ApiErrorwhosebody.errorCodeis the gateway's stable code; a write that fails in transport isNetworkError, whose outcome is unknown (read the resource before resending); a local refusal isAgentErrorwith a stablecode.
Requests
The SDK names the paths and checks the answers; the request bodies are the
/v1 JSON API's own. Each validate* function returns its input, or throws
AgentError when the answer is not about the request that was sent.
import {
prDetailPath, prViewPath, prDiffPath, validatePRDetail, validatePRFeedback, validatePRDiff,
validatePRListResponse, validatePRCommentResult, validateReceiptList, waitForPublishedReceipt,
} from "@botiverse/stamp-sdk";
const receipt = await api("GET", `/v1/receipts/${encodeURIComponent(id)}`);
const receipts = validateReceiptList(await api("GET", "/v1/receipts?limit=20"));
const pr = { owner: "org", repo: "repo", number: 123 };
const detail = validatePRDetail(await api("GET", prDetailPath(pr)), pr);
const diff = validatePRDiff(await api("GET", prDiffPath(pr)), pr);
const inbox = validatePRListResponse(await api("GET", "/v1/inbox/pull-requests"));
validatePRCommentResult(
await api("POST", `${prDetailPath(pr)}/comments`, { body: "Looks good." }), pr);
// A push is published to GitHub asynchronously; wait before opening the PR.
const published = await waitForPublishedReceipt(api, receiptId);
await api("POST", "/v1/pull-requests", {
receiptId, repository: published.repository, targetRef: published.targetRef,
newSha: published.publishedSha, baseRef: "refs/heads/main",
title: "Describe the change", body: "Why", idempotencyKey: "pr-describe-the-change-1",
});
const found = await api("GET", `/v1/search?${new URLSearchParams({ q: "flaky test" })}`);Also exported: the approve/unapprove/merge/auto-merge/edit/close/queue result
validators, parseEvidenceText (review evidence for a self-approval),
reviewBrief, the merge queue setup requests (queueRequest,
validateQueueView), and the git-over-SSH helpers (gatewayCloneURL,
sshCommandFor, fetchPublishedKnownHosts, writePinnedKnownHosts, ...).
See index.mjs for the full list.
Versions
0.x until the /v1 contract it wraps settles; from 1.0, an incompatible
change to an export is a major version.
Development
npm ci
npm test