quickstart

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21// bot.ts — Node.js 24+
const base = 'https://sometimeschat.com/api/bots/v1';
const token = process.env.SOMETIMES_BOT_TOKEN;
if (!token) throw new Error('set SOMETIMES_BOT_TOKEN');
type RequestBody = Record<string, unknown> & { installation?: string; key?: string };
async function request<T = unknown>(
  path: string, { installation, key, ...body }: RequestBody = {},
): Promise<T | null> {
  const r = await fetch(base + path, {
    method: 'POST',
    headers: {
      Authorization: `Bot ${token}`,
      'Content-Type': 'application/json',
      ...(installation ? { 'X-Sometimes-Installation': installation } : {}),
      ...(key ? { 'Idempotency-Key': key } : {}),
    },
    body: JSON.stringify(body),
  });
  if (!r.ok) throw new Error(`${r.status}: ${await r.text()}`);
  return r.status === 204 ? null : r.json();
}

1
2
3
4await request('/applications/@me/commands', {
  key: 'register-hello-v1', name: 'hello',
  description: 'say hello privately', options: [],
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45type Ticket = { url: string; ticket: string };
type GatewayFrame = {
  op: string; nonce: string; type: string; id: string; cursor: string;
  installation_id: string; data: { id: string };
};
const ticket = await request<Ticket>('/gateway/tickets');
if (!ticket) throw new Error('missing gateway ticket');
const socket = new WebSocket(ticket.url);
let work = Promise.resolve();
const fail = (error: unknown) => {
  console.error(error);
  socket.close(1000, 'restart after error');
};
socket.addEventListener('open', () => socket.send(JSON.stringify({
  op: 'identify', ticket: ticket.ticket, subscriptions: ['interaction.created'],
})));
socket.addEventListener('message', ({ data }) => {
  try {
    const event = JSON.parse(String(data)) as GatewayFrame;
    if (event.op === 'heartbeat') {
      socket.send(JSON.stringify({ op: 'heartbeat_ack', nonce: event.nonce }));
      return;
    }
    if (event.op !== 'event') return;
    const interaction = event.type === 'interaction.created';
    const id = interaction ? encodeURIComponent(event.data.id) : '';
    const installation = event.installation_id;
    // Acknowledge commands immediately, but commit gateway cursors in order.
    const acknowledged = interaction
      ? request(`/interactions/${id}/ack`, {
          installation, key: `${event.id}:ack`, ephemeral: true,
        }).then(() => null, error => error)
      : Promise.resolve(null);
    work = work.then(async () => {
      const error = await acknowledged;
      if (error) throw error;
      if (interaction) await request(`/interactions/${id}/responses`, {
        installation, key: `${event.id}:reply`, content: 'hello!', ephemeral: true,
      });
      socket.send(JSON.stringify({ op: 'ack', cursor: event.cursor }));
    });
    void work.catch(fail);
  } catch (error) { fail(error); }
});
socket.addEventListener('close', () => process.exit(1));