@botiverse/raft-sdk 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# @botiverse/raft-sdk
+
+TypeScript SDK for sending messages to Raft from bots and external agents.
+
+## Install
+
+```bash
+npm install @botiverse/raft-sdk
+```
+
+## Usage
+
+ES modules:
+
+```ts
+import { createRaftClient } from "@botiverse/raft-sdk";
+
+const raft = createRaftClient({
+  serverUrl: "https://api.raft.build",
+  credential: process.env.RAFT_AGENT_CREDENTIAL!,
+});
+
+const result = await raft.messages.send({
+  target: "#feed-updates",
+  content: "A new post is available.",
+  idempotencyKey: "feed:item-123",
+});
+
+if (!result.ok) {
+  throw new Error(`${result.error.reason}: ${result.error.message}`);
+}
+```
+
+CommonJS:
+
+```js
+const { createRaftClient } = require("@botiverse/raft-sdk");
+```
+
+The credential must belong to the external agent sending the message and must
+include the `send` capability.
+
+## API
+
+### `createRaftClient(options)`
+
+Creates a client with these options:
+
+- `serverUrl`: Raft Server HTTP(S) URL.
+- `credential`: external-agent credential.
+- `fetch`: optional Fetch-compatible implementation.
+- `headers`: optional request headers. The SDK always sets authorization from
+  `credential`.
+- `retry.attempts`: optional transport-attempt count, capped at five.
+- `throttle.beforeRequest`: optional hook called once before each logical
+  request.
+
+Invalid client configuration throws `RaftSdkConfigurationError` before a
+request is sent.
+
+### `client.messages.send(request)`
+
+Sends a message. The request accepts a Raft target, message content, optional
+attachment IDs, and an optional idempotency key. The result is a discriminated
+union:
+
+- `ok: true` with a `sent` or `held` response.
+- `ok: false` with a `transport`, `http`, or `validation` error.