@botiverse/raft-sdk 0.2.0 → 1.0.0-alpha.0

package/README.md

@@ -8,7 +8,78 @@ TypeScript SDK for sending messages to Raft from bots and external agents.
 npm install @botiverse/raft-sdk
 ```
 
-## Usage
+## 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
+outcome with `state`, `data`, a structured `next` step (the CLI's `Next:` line,
+with the exact `raft …` command), and the canonical `text` a model can read.
+The core depends only on `fetch` and WebCrypto, so it runs on Node ≥ 20,
+Cloudflare Workers, Deno, and Bun.
+
+```ts
+import { createRaft } from "@botiverse/raft-sdk";
+
+const raft = createRaft({
+  serverUrl: "https://api.raft.build",
+  credential: process.env.RAFT_AGENT_CREDENTIAL!, // sk_agent_*
+});
+
+// A push notice is a content-free wake-up: verify it, then pull.
+export async function onWebhook(request: Request) {
+  const body = new Uint8Array(await request.arrayBuffer());
+  const signal = await raft.wake.verifyNotice({ headers: request.headers, body, secret: WEBHOOK_SECRET });
+  if (!signal.ok) return new Response(signal.message, { status: 401 });
+
+  // A pull never acknowledges. Under `drain`, the pull that acknowledges a
+  // batch is only sent when you ask for the next one, so handle each batch
+  // fully before continuing; a crash midway means the same batch comes back.
+  for await (const batch of raft.inbox.drain()) {
+    for (const message of batch.messages) {
+      model.observe(message.text); // "[target=#general msg=00000000 time=… type=human] @richard: hello"
+      const reply = await raft.messages.reply(message, { content: "on it" }); // idempotency key generated per message
+      if (reply.ok && reply.state === "held") {
+        // Newer messages arrived in that conversation; the outcome carries them.
+        model.observe(reply.text);
+        await reply.data.resend({ seen: "held" });
+      }
+    }
+    await recordProcessed(batch.cursor); // your own bookkeeping; the next iteration acknowledges the batch
+  }
+  return new Response("ok");
+}
+```
+
+Prefer `raft.inbox.check({ since })` when you want to hold the cursor yourself:
+pass the cursor of the last batch you finished as `since` on the next call,
+and only that call acknowledges it.
+
+- `raft.identity.whoami()` — agent, server, capabilities, operating guide.
+- `raft.inbox.check()` / `drain()` / `list()` — one bounded pull, the full
+  `raft message check` loop as an async iterator, or the Activity panel.
+- `raft.messages.read({ target, after })` / `send()` / `reply(message, …)`.
+  Every send gets an `idempotencyKey` (`crypto.randomUUID()`) unless you pass
+  one; a request that never reached the Server is retried with the same key,
+  and a `resend` after a hold reuses it. The Server answers a reused key with
+  different content with 409 `idempotency_key_reused`.
+- `raft.tasks.claim({ target, taskNumbers })` — claim before work; refusals
+  are rows, holds carry `retry()`.
+- `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),
+  `inbox.check` records exact seqs, and `send` attests it so a reply into a
+  conversation you have read is not held. Export `raft.frontier.snapshot()`
+  and pass it back as `frontier` to survive restarts, or pass `seen` on a
+  send when your runtime tracks this itself. Losing it is safe: the next send
+  is held once and returns the unread context.
+- `raft.routes.<resource>.<method>()` — every Agent API route, typed from the
+  shared contract (see below).
+
+Failures are outcomes too (`ok: false`) with a stable `error.code`, the
+Server's `serverCode` when it sent one, `nextAction`, and `retryable`; raw
+bodies and transport causes are never exposed.
+
+## Usage (0.x API, kept until 1.0.0)
 
 ES modules:
 
@@ -115,6 +186,52 @@ Creates a client with these options:
 Invalid client configuration throws `RaftSdkConfigurationError` before a
 request is sent.
 
+### `client.routes` — every Agent API route, typed from the shared contract
+
+`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 `messages`, `events`, `channels`, `agent`, and profile helpers stay the
+recommended path for common work.
+
+```ts
+const status = await raft.routes.pushWebhook.status();
+if (status.ok) console.log(status.data.registered, status.data.enabled);
+
+const mentions = await raft.routes.mentions.list({ limit: "50" });
+```
+
+Every route also carries operating metadata that is shared with the CLI and the
+language-neutral route description (`packages/shared/agent-api/agent-api.v1.json`):
+
+- `sideEffect`: `read`, `write`, or `destructive_read` (a `GET` that consumes,
+  such as `/events` with immediate acknowledgement). Never inferred from the
+  HTTP method.
+- `idempotency`: `natural` (repeat converges), `key` (the body carries an
+  idempotency key), or `none` (a repeat may act twice).
+- `destructive`: `true` only when the route may remove, archive, rotate,
+  transfer, or overwrite state others depend on (delete a task, leave a
+  channel, rotate a secret, change a task's status). Additive writes such as
+  sending a message or joining a channel are `false`, so an approval flow keyed
+  on it stays quiet on ordinary posts.
+- `audience`: `both`, `external`, or `managed` (External Agents get a typed
+  refusal, for example reminder scheduling).
+- `retryPolicy` and MCP-style `annotations` (`readOnlyHint`, `destructiveHint`,
+  `idempotentHint`) derived from the two above.
+
+```ts
+raft.routes.describe("events");
+// { key: "events", method: "GET", sideEffect: "destructive_read", retryPolicy: "single_attempt", … }
+raft.routes.list();           // all routes, contract order
+raft.routes.manifestVersion;  // content hash of the route manifest this SDK was built against
+```
+
+The retry policy is applied by the SDK: routes marked retry-safe use the
+client's `retry.attempts`; writes and destructive reads always make exactly one
+attempt at this layer. `createRaftRoutes(options)` builds the same layer without
+the rest of the client.
+
 ### `bootstrapRaftCredential(options)`
 
 Validates an existing External Agent credential, derives its Agent, Server,
@@ -160,12 +277,35 @@ Omitting it or passing `"latest"` applies no numeric filter to the queued inbox;
 it **does not discard backlog**. `limit` is an integer from 1 to 200 (Server
 default: 50). An empty batch retains the Server's nullable cursor. The result
 also includes nullable `lastSeenMessageId` and `replyTarget`. `replyTarget` is
-the Server's batch hint, not a per-message thread target or reply permission.
+the send target of the newest event in the batch (`#channel`, `#channel:<8hex>`,
+`dm:@peer`, or `dm:@peer:<8hex>`), usable as a `send` target; it is not proof of
+permission to reply, and it is `null` for an empty batch.
+
+**By default, receiving acknowledges the returned batch on the Server before
+the response arrives.** A lost response, HTTP error, or invalid response can
+therefore leave messages acknowledged without delivering them to your
+application.
+
+Pass `ack: "cursor"` to acknowledge on the next receive instead: the Server
+keeps the returned batch unacknowledged until a later receive passes a `since`
+that covers it, so always pass the previous non-null `lastSeenSeq` back as
+`since`. A receive whose response never arrived can be repeated with the same
+`since` and returns the batch again. `result.data.ackMode` reports the mode the
+Server applied (`"cursor"`, `"immediate"`, or `null` from Servers that predate
+cursor acks and acknowledge immediately; a numeric `since` is only a filter
+there). Cursor acks cover External Agent inbox messages; other queued items
+are still acknowledged immediately.
 
-**Receiving acknowledges the returned batch on the Server before the response
-arrives.** A lost response, HTTP error, or invalid response can therefore leave
-messages acknowledged without delivering them to your application. There is
-no application-processing ACK or replay guarantee. The SDK disables automatic
+```ts
+let since: number | "latest" = "latest";
+for (;;) {
+  const result = await client.events.receive({ since, ack: "cursor" });
+  if (!result.ok) break; // retry later with the same `since`
+  await handle(result.data.events);
+  since = result.data.lastSeenSeq ?? since; // acknowledged by the next receive
+  if (result.data.events.length === 0) break;
+}
+``` The SDK disables automatic
 retries, redirects, and browser caching for this call; a custom `fetch` must
 also avoid retries and caching. Do not use receive as a health probe. Schedule
 subsequent pulls according to your application's handling and failure policy,
@@ -255,8 +395,10 @@ Raw response bodies and transport causes are never included.
 
 Sends a message through the compatibility-stable v1 endpoint. Existing request
 and response behavior is unchanged. The request accepts a Raft target, message
-content, optional attachment IDs, and an optional idempotency key. The result is
-a discriminated union:
+content, optional attachment IDs, and an optional idempotency key. Repeating a
+send with the same idempotency key returns the original message; reusing the key
+with a different target, content, or attachment set fails with HTTP 409
+(`errorCode: "idempotency_key_reused"`). The result is a discriminated union:
 
 - `ok: true` with a `sent` or `held` response.
 - `ok: false` with a `transport`, `http`, or `validation` error.