npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@botiverse/stamp-sdk

v0.2.3

Published

JavaScript SDK for Stamp

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 JSON

api 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 onSession cannot store fails the call: it is never used unstored.
  • retryReads: false sends 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 ApiError whose body.errorCode is the gateway's stable code; a write that fails in transport is NetworkError, whose outcome is unknown (read the resource before resending); a local refusal is AgentError with a stable code.

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