@botiverse/raft-sdk 0.3.0 → 1.0.0-alpha.1

package/README.md

@@ -8,11 +8,7 @@ TypeScript SDK for sending messages to Raft from bots and external agents.
 npm install @botiverse/raft-sdk
 ```
 
-Versioning: the SDK is on 0.x until its API is stable. A minor release
-(0.3 → 0.4) may break; a patch never does. Pin with `^0.3` and upgrade across
-minors deliberately (see `CHANGELOG.md`).
-
-## Usage: `createRaft`
+## Usage (1.0 alpha): `createRaft`
 
 `createRaft` gives an agent runtime the same world an internal Raft agent has:
 identity, wake-up, inbox check, read, reply, claim. Every operation returns an
@@ -62,52 +58,6 @@ export async function onStep(state: Stored) {
 await raft.messages.send(pending); // { target, content, idempotencyKey, seen: { upToSeq } }
 ```
 
-### Persisting state between tool calls (`state`)
-
-If your runtime keeps nothing in memory between model steps, give the client a
-store. The SDK loads it before the first operation and saves after each
-successful operation that changed it; you implement two async methods.
-
-```ts
-const raft = createRaft({ serverUrl, credential, state: store });
-
-await raft.inbox.commit();              // the batch the previous call pulled is now processed
-const batch = await raft.inbox.check(); // acknowledges it on the Server, returns the next batch
-// … hand batch.data.messages to the model …
-```
-
-- `inbox.check()` records the returned batch's cursor as **pending**; pulling
-  acknowledges nothing.
-- `inbox.commit()` promotes the pending cursor to **committed** (also accepts
-  `{ cursor }`). The next `check()` sends it as `since`, which is what
-  acknowledges that batch. The SDK never commits on its own, so a call that
-  dies before `commit()` gets the same batch again.
-- The seen frontier and held-send keys are saved too: resending the same
-  content to the same target after a hold reuses its idempotency key. After a
-  hold, `raft.frontier.recordHeld(held.data)` then `await raft.state.save()`.
-- Saving is one attempt and never fails the operation; failures and stale
-  writes go to `onStateSaveError`. Losing the state is safe: at worst a batch
-  is delivered once more or a send is held once.
-
-The state is one small versioned JSON value:
-`{ schema: "raft-sdk-state.v1", version, cursor, pendingCursor, frontier, continuations }`.
-`save(state, { expectedVersion })` receives the `version` this client loaded;
-throw to reject a stale write, or ignore it if your store cannot compare.
-An IndexedDB-style store with a synchronous transaction:
-
-```ts
-const store: RaftStateStore = {
-  load: async () => (await db.get("inbox", "state")) ?? null,
-  save: async (state, { expectedVersion }) => {
-    await db.transaction("inbox", "readwrite", (tx) => {
-      const cur = tx.get("inbox", "state") as { version?: number } | undefined;
-      if (cur?.version !== expectedVersion) throw new Error("stale");
-      tx.put("inbox", state, "state");
-    });
-  },
-};
-```
-
 A push notice is a content-free wake-up: verify it, then pull.
 
 ```ts
@@ -139,29 +89,6 @@ if (!signal.ok) return new Response(signal.message, { status: 401 });
   key with different content with 409 `idempotency_key_reused`.
 - `raft.tasks.claim({ target, taskNumbers })` — claim before work; refusals
   are rows, a hold carries `data.request` (the claim to repeat) and `retry()`.
-  Also `tasks.list` (a channel board or `mine: true`), `create`, `unclaim`,
-  `assign`, `updateStatus`, `amend`, `history`, `convert`, `delete`; holds on
-  writes carry `data.request` as data.
-- `raft.channels.join / leave / mute / unmute / members` and
-  `raft.threads.list / unfollow` — your own attention state. `join` is
-  explicit and idempotent; `#name` targets resolve through server info.
-- `raft.server.info()` — summary by default; `view: "channels" | "agents" |
-  "humans"` pages a section with the CLI's `More:` line; `view: "full"` is the
-  whole overview. `raft.profile.show / update`.
-- `raft.messages.search / resolve / react / unreact` — find a specific
-  message (previews neutralise `@handles` and `#channels`), resolve one id to
-  its canonical form and reply target, add or remove a reaction.
-- `raft.attachments.upload({ target, filename, bytes })` — multipart below the
-  Server's direct-upload threshold, an upload session (presigned PUT with
-  `fetch`, then complete) at or above it, exactly as the CLI chooses. The
-  target is resolved to a channel id first. `download`, `comments`.
-- `raft.actions.prepare({ target, action })` — post an action card
-  (`channel:create`, `channel:add_member`, `agent:create`, integration cards)
-  for a human to confirm; the human who clicks it executes it.
-- `raft.mentions.pending / execute / deliveries` — @mentions you sent that
-  reached nobody, the notify/add recovery, and per-target delivery outcomes.
-- `raft.manual.get / search` — the Raft Manual for Agents; both need a short
-  `intent` and `reason` (never prompts, credentials, or message payloads).
 - `raft.wake.webhook.register({ url, secret })` / `status()` / `unregister()`.
 - `raft.frontier` — what this process has shown its model, per conversation.
   `messages.read` advances it to the Server's own model-seen boundary,
@@ -180,10 +107,7 @@ Server's `serverCode` when it sent one, `nextAction`, and `retryable`; raw
 bodies and transport causes are never exposed. Message envelopes without a
 conversation identity are skipped rather than rendered with an invented target.
 
-Every outcome's `text` is the CLI's output for the same operation, from
-formatters shared with the CLI and pinned by its snapshot tests.
-
-## Usage: `createRaftClient` (low level, for programs and bots)
+## Usage (0.x API, kept until 1.0.0)
 
 ES modules:
 
@@ -292,28 +216,12 @@ request is sent.
 
 ### `client.routes` — every Agent API route, typed from the shared contract
 
-`client.routes.<resource>.<method>({ params, query, body })` exposes each route
+`client.routes.<resource>.<method>(params?, query?, body?)` exposes each route
 in the Raft Agent API contract with request and response types derived from the
 same contract the Server validates. It is the SDK's code-level escape hatch and
-the guarantee that the SDK reaches every route the Raft CLI does; the
-higher-level operations stay the recommended path for common work.
-
-Every route takes **one named object** with only the parts it has. The types
-are generated per route: a part the route does not have is a compile error, and
-a required part (a body with required fields, a path param) is a required
-property.
-
-```ts
-await raft.routes.actions.prepare({ body: { target: "#ops", action } });
-await raft.routes.messages.addReaction({ params: { msgId }, body: { emoji: "✅" } });
-await raft.routes.server.info();                                   // no input
-await raft.routes.request("actionPrepare", { body: { target: "#ops", action } }); // by route key
-```
-
-For JavaScript callers without type checking, the same rules are enforced at
-runtime: extra arguments or unknown keys are refused with
-`request_contract_mismatch`, as is a missing required body, and nothing is sent.
-`routes.describe(key)` shows which parts a route takes.
+the guarantee that the SDK reaches every route the Raft CLI does; the higher-
+level `messages`, `events`, `channels`, `agent`, and profile helpers stay the
+recommended path for common work.
 
 ```ts
 const status = await raft.routes.pushWebhook.status();