# orb-bot

A dependency-free client for the Orb bot API (`orb-bots-v1`). Node 18 or newer. The API is plain HTTP and JSON, so you can use any language;
this library saves you the boring parts: authentication, throttling, the event loop, the cursor, and signature checks.

```js
import { OrbBot } from 'orb-bot';          // from this repository: import from './sdk/orb-bot/index.mjs'

const bot = new OrbBot({ token: process.env.ORB_BOT_TOKEN, baseUrl: process.env.ORB_URL });

await bot.commands.sync([{ name: 'ping', description: 'Is the bot alive?' }]);

await bot.run({
  mention: ctx => ctx.reply(`Hello ${ctx.author.name}`),
  commands: { ping: ctx => ctx.reply('pong') },
});
```

## What is in it

| | |
| --- | --- |
| `new OrbBot({ token, baseUrl, maxRetries })` | `token` defaults to `ORB_BOT_TOKEN`, `baseUrl` to `ORB_URL` |
| `bot.app(server?)` | who the app is, where it was accepted, and (with `server`) the channels it may use |
| `bot.send(channel, content, { replyTo })` · `bot.history(channel, { before, limit })` · `bot.remove(messageId)` | speak, read, take back what you wrote |
| `bot.commands.sync(list)` · `.list()` · `.remove(name)` | the commands members can type |
| `bot.events({ after, wait })` · `bot.respond(eventId, text)` | fetch events and answer a typed command |
| `bot.run(handlers, { after, wait, signal, onError, store })` | the event loop |
| `bot.serve(handlers, { port, path })` | the same handlers as a signed webhook server |
| `verifySignature({ header, body, token })` | check an event really came from Orb |
| `OrbApiError` | `status`, `message`, `retryAfter` |

Handlers receive a context: `ctx.reply(text)` answers (a reply to the message for a mention; a private answer to the member for a command),
`ctx.say(text)` posts in the channel, and `ctx.event` is the raw event.

`run` moves its cursor past an event only **after** the handler has finished, reports a failing handler to `onError` and keeps going, survives network outages with backoff, and ends
only on a bad credential (401/403) or when you abort it. Pass `store: { get, set }` to resume after a restart.

Full guide: [`docs/orb-bot-developer-guide.md`](/docs/orb-bot-developer-guide.md). Runnable examples: [`examples/bots`](../examples/bots/README.md).
Test: `node scripts/test-bot-sdk.mjs`. MIT licensed.