Add @weftsh/sdk: the TypeScript SDK for Weft

[hkd987]

What

The first release (0.1.0) of @weftsh/sdk, a small TypeScript client for the Weft Repos API. It's shaped after the code.storage SDK: a Weft client, a Repo handle, and one method per action.

const weft = new Weft({ token: process.env.WEFT_TOKEN!, org: 'acme' });
const repo = await weft.createRepo();
await repo.createCommit({ message: 'step 1' }).put('src/app.ts', src).delete('old.txt').send();
await repo.readFile('src/app.ts');
await repo.getRemoteURL(); // https://x:weft_…@api.weft.sh/acme/….git

• Repositories: create (the name is generated if you don't give one), find, get a handle without a request, list and iterate, batch create/delete, update, delete, fork, mirrors.
• Commits: a builder (createCommit().put().delete().send()). Strings are sent as put and bytes as put_base64. expectedParent covers the server's three cases: omitted, a SHA, or null (the branch must not exist yet). A 409 throws WeftConflictError, and its currentTip is read from either conflict shape the server returns (current_tip for commits, current for reset/revert).
• Reads: files, with ETag round trips and the X-Weft-* headers; trees; flat file lists; paginated history, optionally filtered by path; diffs.
• Refs and undo: branches, tags, reset, revert.
• Other: tokens, webhooks, bundle export.
• getRemoteURL(): each call creates a short-lived token bound to that one repository and puts it in the URL. A sandbox can clone and push without the client's own token. If the mint is refused (400/403/404), it throws a WeftError that names the scopes needed rather than passing on the server's masked 404.
• verifyWebhook(): checks X-Weft-Signature-256 using Web Crypto.
• Packaging: no dependencies, ESM and CommonJS with type definitions, Node 20+ (also runs on Bun, Deno and edge runtimes).
• Docs and CI: README with a Quickstart, a full guide and an API reference; CHANGELOG; examples/quickstart.mts and examples/agent-session.ts; and a CI workflow that runs typecheck, tests and build on Node 20/22/24 and checks that both module formats load.

readFile and getFile return null only for a missing path or revision. A missing (or invisible) repository throws a 404, because the server answers that case with a bare not found rather than a JSON error. Without this, a typo in a repository name looked like a missing file.

Quickstart

The README opens with a Quickstart:

1. Get a token.
2. Install.
3. Run examples/quickstart.mts, which creates a repository, commits, reads the file back and clones it with the real git CLI.
4. Compare with the expected output.

The README embeds the script verbatim. A unit test fails if the two differ, and the e2e suite runs the script as a subprocess against a live server.

Writing it surfaced a wrong claim. The README said a personal token "whose owner can write" can call getRemoteURL(), but minting also needs org:read. I checked with real personal tokens: org:read + repo:write runs the whole quickstart; repo:write alone fails at the clone step. The README is corrected, and that failure now explains itself.

Testing

• Unit tests (32) pin what goes on the wire, using a fake fetch. They also check that the README quickstart matches the example file; a one-character drift turns that test red.
• End-to-end tests (18) run against a real Weft server built from stratum-core. They are skipped unless WEFT_E2E_URL, WEFT_E2E_TOKEN and WEFT_E2E_ORG are set. Among other things they:
  • clone and push with the real git CLI through getRemoteURL, and run git fsck --full --strict on the clone;
  • check that a read-only URL can't push, and that a repo-scoped token can't reach a sibling repository;
  • verify a webhook delivery the server itself signed;
  • check that a missing repository throws while a missing branch reads as null;
  • run the README quickstart as written.
• Deliberately breaking the expected_parent mapping turned 4 end-to-end tests and 2 unit tests red.

npm run check (typecheck, tests, build) passes. All 50 tests pass against a local server, and with no server set, 32 pass and 18 skip.

Before publishing

• The package isn't on npm yet, and the @weftsh npm scope needs to belong to us.
• The license is MIT, matching code.storage. Change it if that's not what we want.
• The weft.sh docs and marketing for the SDKs are in hkd987/stratum-core#106.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SYuyBuroUvxh32x9SCbx13