Build apps that
borrow an identity.

01 / Install

One package. Five entry points.

yarn add jolt-sdk

The SDK also ships with every Jolt release as an installable tarball, if you prefer pinning to a release directly:

yarn add https://github.com/alexanderwanyoike/jolt/releases/latest/download/jolt-sdk.tgz

02 / Beginner Chirp

Describe the app. Jolt handles the machinery.

A Schema Class is both your TypeScript type and runtime validation. App.create derives paths and access; Chirp.connect() handles compatibility, host selection, and approval.

import { App, Collection, Field, Read, Schema } from "jolt-sdk/data";

@Schema({ version: 1 })
class Post {
  @Field.string()
  text!: string;

  @Field.dateTime()
  postedAt!: Date;
}

const Posts = Collection.create(Post, {
  access: {
    read: Read.AnyIdentity,
    create: true,
    update: true,
    delete: true,
    restore: true,
  },
});

const Chirp = App.create({
  id: "chirp.example",
  name: "Chirp",
  namespace: "chirp",
  data: { posts: Posts },
});

const chirp = await Chirp.connect();
const post = await chirp.posts.create({
  text: "Hello, Jolt!",
  postedAt: new Date(),
});

Chirp.test() exposes the same typed API in memory. Follow the complete compile-checked Beginner Chirp guide.

03 / Advanced low-level client

Session in, signed content out.

This explicit session, transport, path, and decoder flow is for advanced applications. Most applications should begin with jolt-sdk/data.

An app declares who it is and exactly what it wants to do. The daemon holds the request until the user approves it in Jolt Console; the app polls until the approval carries a bearer token, then every call is checked against the granted capabilities.

import { createJoltClient } from "jolt-sdk";
import { HttpTransport } from "jolt-sdk/transport-http";

let token = "";
const jolt = createJoltClient({
  transport: new HttpTransport({ daemonUrl: "http://127.0.0.1:9862" }),
  getSessionToken: () => token,
});

// 1. Ask for a scoped session; the user approves it in Jolt Console.
const status = await jolt.getStatus();
const request = await jolt.requestSession({
  appId: "myapp.local",
  appName: "My App",
  appOrigin: window.location.origin,
  identity: status.identity_address,
  capabilities: ["publish:/myapp/*", "resolve:public", "fetch:public"],
});

// 2. Poll until approved.
for (;;) {
  const s = await jolt.getSessionRequestStatus(request.request_id);
  if (s.session_token) { token = s.session_token; break; }
  await new Promise((r) => setTimeout(r, 1000));
}

// 3. Publish signed content and read it back, versioned and decoded.
await jolt.publishJson("/myapp/profile", { name: "Alice" });
const profile = await jolt.read(
  { identity: status.identity_address, path: "/myapp/profile" },
  (v) => (typeof v === "object" && v && "name" in v ? (v as { name: string }) : null)
);

Reads are tolerant: missing, unreachable, or undecodable content returns null instead of throwing, so one bad record never poisons an app projection. Failures from publishes and sends throw JoltApiError (the daemon answered with an error) or JoltTransportError (the daemon was unreachable); every operation accepts { signal, timeoutMs }.

04 / Transports

Same client. Two ways to the daemon.

Everything above the transport (operations, client, domain types) is identical in the browser, Node.js, and Tauri. Only the last hop changes.

import { HttpTransport } from "jolt-sdk/transport-http";

const transport = new HttpTransport({
  daemonUrl: "http://127.0.0.1:9862",
});

05 / Testing

A whole daemon, faked in memory.

createFakeJolt returns a fully working JoltClient with no daemon and no network: publishes land in an in-memory store, reads resolve against it, sends are recorded, and incoming envelopes can be injected. Your tests exercise your schemas and flows, not HPKE.

import { createFakeJolt } from "jolt-sdk/testing";

const { client, sent, deliverIngress } = createFakeJolt("alice.jolt");
// client satisfies JoltClient and all of its sub-interfaces; sends are
// recorded in `sent`, and deliverIngress() injects incoming envelopes.

06 / Documentation

Where to go next.