Readme

@syncopate/sdk

Syncopate SDK — TypeScript

Build bots for Syncopate with a decorator-based API.

Example

import { Bot, OnEvent, Command, Message, Context } from '@syncopate/sdk';

class MyBot extends Bot {
  @OnEvent('ready')
  async onReady() {
    console.log(`Logged in as ${this.user.displayName}`);
  }

  @OnEvent('messageCreate')
  async onMessage(message: Message) {
    if (message.author.bot) return;
    await message.channel.send('Hello!');
  }

  @Command('ping')
  async ping(ctx: Context) {
    await ctx.reply('Pong!');
  }
}

const bot = new MyBot({ token: 'bot_xxxx' });
bot.run();

Classes

Bot

Defined in: sdk/typescript/src/client.ts:58

Main entry point for building Syncopate bots.

Subclass Bot and use @OnEvent() and @Command() decorators to register event and command handlers.

Example

import { Bot, OnEvent, Command, Message, Context } from '@syncopate/sdk';

class MyBot extends Bot {
  @OnEvent('ready')
  async onReady() {
    console.log(`Logged in as ${this.user.displayName}`);
  }

  @OnEvent('messageCreate')
  async onMessage(message: Message) {
    if (message.author?.bot) return;
  }

  @Command('ping')
  async ping(ctx: Context) {
    await ctx.reply('Pong!');
  }
}

const bot = new MyBot({ token: 'bot_xxx' });
bot.run();

Constructors

Constructor

new Bot(options): Bot

Defined in: sdk/typescript/src/client.ts:82

Parameters

options

BotOptions

Returns

Bot

Properties

channels

readonly channels: Map<string, Channel>

Defined in: sdk/typescript/src/client.ts:69

Channel cache: id → Channel

commandPrefix

readonly commandPrefix: string

Defined in: sdk/typescript/src/client.ts:66

Command prefix (default: !).

rest

readonly rest: RestClient

Defined in: sdk/typescript/src/client.ts:63

REST client for API calls.

user

user: User

Defined in: sdk/typescript/src/client.ts:60

The authenticated bot user. Available after ready event.

Methods

disconnect()

disconnect(): void

Defined in: sdk/typescript/src/client.ts:144

Disconnect the bot.

Returns

void

fetchUser()

fetchUser(userId): Promise<User>

Defined in: sdk/typescript/src/client.ts:158

Fetch a specific user by ID.

Parameters

userId

string

Returns

Promise<User>

fetchWorkspaces()

fetchWorkspaces(): Promise<Workspace[]>

Defined in: sdk/typescript/src/client.ts:152

Fetch all workspaces the bot is a member of.

Returns

Promise<Workspace[]>

getChannel()

getChannel(channelId): Promise<Channel>

Defined in: sdk/typescript/src/client.ts:164

Get a cached channel, or fetch it.

Parameters

channelId

string

Returns

Promise<Channel>

run()

run(): Promise<void>

Defined in: sdk/typescript/src/client.ts:99

Start the bot: authenticate, cache channels, connect to SSE.

This method blocks until the bot is disconnected.

Returns

Promise<void>

Channel

Defined in: sdk/typescript/src/models/channel.ts:8

Model representing a Syncopate channel.

Constructors

Constructor

new Channel(data): Channel

Defined in: sdk/typescript/src/models/channel.ts:20

Parameters

data

ChannelData

Returns

Channel

Properties

_rest

_rest: RestClient | null = null

Defined in: sdk/typescript/src/models/channel.ts:18

Internal

id

readonly id: string

Defined in: sdk/typescript/src/models/channel.ts:9

insertedAt

readonly insertedAt: string

Defined in: sdk/typescript/src/models/channel.ts:14

name

readonly name: string | null

Defined in: sdk/typescript/src/models/channel.ts:11

topic

readonly topic: string | null

Defined in: sdk/typescript/src/models/channel.ts:13

type

readonly type: string

Defined in: sdk/typescript/src/models/channel.ts:12

updatedAt

readonly updatedAt: string

Defined in: sdk/typescript/src/models/channel.ts:15

workspaceId

readonly workspaceId: string

Defined in: sdk/typescript/src/models/channel.ts:10

Methods

_bind()

_bind(rest): this

Defined in: sdk/typescript/src/models/channel.ts:31

Internal

Inject the REST client for API calls.

Parameters

rest

RestClient

Returns

this

fetchMembers()

fetchMembers(): Promise<ChannelMemberData[]>

Defined in: sdk/typescript/src/models/channel.ts:78

Fetch members of this channel.

Returns

Promise<ChannelMemberData[]>

fetchMessages()

fetchMessages(options?): Promise<Message[]>

Defined in: sdk/typescript/src/models/channel.ts:60

Fetch messages from this channel.

Parameters

options?

afterSequence?

number

beforeSequence?

number

limit?

number

Returns

Promise<Message[]>

fetchPresence()

fetchPresence(): Promise<string[]>

Defined in: sdk/typescript/src/models/channel.ts:87

Fetch online user IDs in this channel.

Returns

Promise<string[]>

send()

send(content, options?): Promise<Message>

Defined in: sdk/typescript/src/models/channel.ts:37

Send a message to this channel.

Parameters

content

string

options?

idempotencyKey?

string

parentId?

string

type?

string

Returns

Promise<Message>

toString()

toString(): string

Defined in: sdk/typescript/src/models/channel.ts:109

Returns

string

triggerTyping()

triggerTyping(): Promise<void>

Defined in: sdk/typescript/src/models/channel.ts:96

Send a typing indicator.

Returns

Promise<void>

ChannelMember

Defined in: sdk/typescript/src/models/member.ts:6

Model representing a channel member.

Constructors

Constructor

new ChannelMember(data): ChannelMember

Defined in: sdk/typescript/src/models/member.ts:14

Parameters

data

ChannelMemberData

Returns

ChannelMember

Properties

channelId

readonly channelId: string

Defined in: sdk/typescript/src/models/member.ts:8

id

readonly id: string

Defined in: sdk/typescript/src/models/member.ts:7

insertedAt

readonly insertedAt: string

Defined in: sdk/typescript/src/models/member.ts:12

role

readonly role: string

Defined in: sdk/typescript/src/models/member.ts:10

user

readonly user: User

Defined in: sdk/typescript/src/models/member.ts:11

userId

readonly userId: string

Defined in: sdk/typescript/src/models/member.ts:9

Context

Defined in: sdk/typescript/src/commands/context.ts:11

Command execution context.

Passed to @Command() handlers with the triggering message, parsed arguments, and convenience methods for replying.

Constructors

Constructor

new Context(options): Context

Defined in: sdk/typescript/src/commands/context.ts:30

Parameters

options

args

string[]

author

User

channel

Channel

command

string

message

Message

Returns

Context

Properties

args

readonly args: string[]

Defined in: sdk/typescript/src/commands/context.ts:25

Arguments after the command name, split by whitespace.

author

readonly author: User

Defined in: sdk/typescript/src/commands/context.ts:19

The user who invoked the command.

channel

readonly channel: Channel

Defined in: sdk/typescript/src/commands/context.ts:16

The channel the command was invoked in.

command

readonly command: string

Defined in: sdk/typescript/src/commands/context.ts:22

The command name (without prefix).

content

readonly content: string

Defined in: sdk/typescript/src/commands/context.ts:28

The full raw content of the message.

message

readonly message: Message

Defined in: sdk/typescript/src/commands/context.ts:13

The message that triggered the command.

Methods

reply()

reply(content): Promise<Message>

Defined in: sdk/typescript/src/commands/context.ts:51

Reply to the triggering message (threaded).

Parameters

content

string

Returns

Promise<Message>

send()

send(content): Promise<Message>

Defined in: sdk/typescript/src/commands/context.ts:46

Send a message to the same channel.

Parameters

content

string

Returns

Promise<Message>

GatewayError

Defined in: sdk/typescript/src/errors.ts:27

Raised when the SSE gateway connection fails.

Extends

SyncopateError

Constructors

Constructor

new GatewayError(message): GatewayError

Defined in: sdk/typescript/src/errors.ts:28

Parameters

message

string

Returns

GatewayError

Overrides

SyncopateError.constructor

Properties

cause?

optional cause: unknown

Defined in: web/node_modules/typescript/lib/lib.es2022.error.d.ts:26

Inherited from

SyncopateError.cause

message

message: string

Defined in: web/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

SyncopateError.message

name

name: string

Defined in: web/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

SyncopateError.name

stack?

optional stack: string

Defined in: web/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

SyncopateError.stack

HTTPError

Defined in: sdk/typescript/src/errors.ts:14

Raised when an HTTP request fails.

Extends

SyncopateError

Constructors

Constructor

new HTTPError(status, body, message?): HTTPError

Defined in: sdk/typescript/src/errors.ts:18

Parameters

status

number

body

unknown

message?

string

Returns

HTTPError

Overrides

SyncopateError.constructor

Properties

body

readonly body: unknown

Defined in: sdk/typescript/src/errors.ts:16

cause?

optional cause: unknown

Defined in: web/node_modules/typescript/lib/lib.es2022.error.d.ts:26

Inherited from

SyncopateError.cause

message

message: string

Defined in: web/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

SyncopateError.message

name

name: string

Defined in: web/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

SyncopateError.name

stack?

optional stack: string

Defined in: web/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

SyncopateError.stack

status

readonly status: number

Defined in: sdk/typescript/src/errors.ts:15

Message

Defined in: sdk/typescript/src/models/message.ts:8

Model representing a Syncopate message.

Constructors

Constructor

new Message(data): Message

Defined in: sdk/typescript/src/models/message.ts:28

Parameters

data

MessageData

Returns

Message

Properties

_rest

_rest: RestClient | null = null

Defined in: sdk/typescript/src/models/message.ts:26

Internal

author

author: User | null = null

Defined in: sdk/typescript/src/models/message.ts:20

The author as a User object, if available from the event payload.

channel

channel: Channel | null = null

Defined in: sdk/typescript/src/models/message.ts:23

The channel this message belongs to, if resolved.

channelId

readonly channelId: string

Defined in: sdk/typescript/src/models/message.ts:10

content

readonly content: string

Defined in: sdk/typescript/src/models/message.ts:12

editedAt

readonly editedAt: string | null

Defined in: sdk/typescript/src/models/message.ts:16

id

readonly id: string

Defined in: sdk/typescript/src/models/message.ts:9

insertedAt

readonly insertedAt: string

Defined in: sdk/typescript/src/models/message.ts:17

parentId

readonly parentId: string | null

Defined in: sdk/typescript/src/models/message.ts:15

sequence

readonly sequence: number

Defined in: sdk/typescript/src/models/message.ts:14

type

readonly type: string

Defined in: sdk/typescript/src/models/message.ts:13

userId

readonly userId: string

Defined in: sdk/typescript/src/models/message.ts:11

Methods

_bind()

_bind(rest): this

Defined in: sdk/typescript/src/models/message.ts:46

Internal

Inject the REST client.

Parameters

rest

RestClient

Returns

this

delete()

delete(): Promise<void>

Defined in: sdk/typescript/src/models/message.ts:59

Delete this message.

Returns

Promise<void>

edit()

edit(content): Promise<Message>

Defined in: sdk/typescript/src/models/message.ts:52

Edit this message.

Parameters

content

string

Returns

Promise<Message>

reply()

reply(content): Promise<Message>

Defined in: sdk/typescript/src/models/message.ts:65

Reply to this message (creates a threaded message).

Parameters

content

string

Returns

Promise<Message>

toString()

toString(): string

Defined in: sdk/typescript/src/models/message.ts:80

Returns

string

SyncopateError

Defined in: sdk/typescript/src/errors.ts:6

Base error for all SDK errors.

Extends

Error

Constructors

Constructor

new SyncopateError(message): SyncopateError

Defined in: sdk/typescript/src/errors.ts:7

Parameters

message

string

Returns

SyncopateError

Overrides

Error.constructor

Properties

cause?

optional cause: unknown

Defined in: web/node_modules/typescript/lib/lib.es2022.error.d.ts:26

Inherited from

Error.cause

message

message: string

Defined in: web/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

Error.message

name

name: string

Defined in: web/node_modules/typescript/lib/lib.es5.d.ts:1076

Inherited from

Error.name

stack?

optional stack: string

Defined in: web/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

Error.stack

User

Defined in: sdk/typescript/src/models/user.ts:4

Model representing a Syncopate user.

Constructors

Constructor

new User(data): User

Defined in: sdk/typescript/src/models/user.ts:10

Parameters

data

UserData

Returns

User

Properties

avatarUrl

readonly avatarUrl: string | null

Defined in: sdk/typescript/src/models/user.ts:7

bot

readonly bot: boolean

Defined in: sdk/typescript/src/models/user.ts:8

displayName

readonly displayName: string | null

Defined in: sdk/typescript/src/models/user.ts:6

id

readonly id: string

Defined in: sdk/typescript/src/models/user.ts:5

Accessors

isBot

Get Signature

get isBot(): boolean

Defined in: sdk/typescript/src/models/user.ts:18

Whether this is a bot user.

Returns

boolean

Methods

toString()

toString(): string

Defined in: sdk/typescript/src/models/user.ts:22

Returns

string

Workspace

Defined in: sdk/typescript/src/models/workspace.ts:4

Model representing a Syncopate workspace.

Constructors

Constructor

new Workspace(data): Workspace

Defined in: sdk/typescript/src/models/workspace.ts:11

Parameters

data

WorkspaceData

Returns

Workspace

Properties

id

readonly id: string

Defined in: sdk/typescript/src/models/workspace.ts:5

insertedAt

readonly insertedAt: string

Defined in: sdk/typescript/src/models/workspace.ts:8

name

readonly name: string

Defined in: sdk/typescript/src/models/workspace.ts:6

slug

readonly slug: string

Defined in: sdk/typescript/src/models/workspace.ts:7

updatedAt

readonly updatedAt: string

Defined in: sdk/typescript/src/models/workspace.ts:9

Methods

toString()

toString(): string

Defined in: sdk/typescript/src/models/workspace.ts:19

Returns

string

WorkspaceMember

Defined in: sdk/typescript/src/models/member.ts:37

Model representing a workspace member.

Constructors

Constructor

new WorkspaceMember(data): WorkspaceMember

Defined in: sdk/typescript/src/models/member.ts:44

Parameters

data

WorkspaceMemberData

Returns

WorkspaceMember

Properties

id

readonly id: string

Defined in: sdk/typescript/src/models/member.ts:38

insertedAt

readonly insertedAt: string

Defined in: sdk/typescript/src/models/member.ts:42

role

readonly role: string

Defined in: sdk/typescript/src/models/member.ts:40

user

readonly user: User

Defined in: sdk/typescript/src/models/member.ts:41

userId

readonly userId: string

Defined in: sdk/typescript/src/models/member.ts:39

Interfaces

BotOptions

Defined in: sdk/typescript/src/client.ts:16

Options for creating a Bot instance.

Properties

baseUrl?

optional baseUrl: string

Defined in: sdk/typescript/src/client.ts:21

Base URL of the Syncopate API. Defaults to http://localhost:4000.

commandPrefix?

optional commandPrefix: string

Defined in: sdk/typescript/src/client.ts:24

Command prefix. Defaults to !.

token

token: string

Defined in: sdk/typescript/src/client.ts:18

The bot token (from Authorization: Bot <token>).

ChannelCreatedEvent

Defined in: sdk/typescript/src/models/events.ts:60

Properties

channelId

channelId: string

Defined in: sdk/typescript/src/models/events.ts:62

data

data: object

Defined in: sdk/typescript/src/models/events.ts:63

id

id: string

name

name: string | null

topic

topic: string | null

type

type: string

workspace_id

workspace_id: string

type

type: "channelCreate"

Defined in: sdk/typescript/src/models/events.ts:61

ChannelDeletedEvent

Defined in: sdk/typescript/src/models/events.ts:78

Properties

channelId

channelId: string

Defined in: sdk/typescript/src/models/events.ts:80

data

data: object

Defined in: sdk/typescript/src/models/events.ts:81

channel_id

channel_id: string

type

type: "channelDelete"

Defined in: sdk/typescript/src/models/events.ts:79

ChannelUpdatedEvent

Defined in: sdk/typescript/src/models/events.ts:72

Properties

channelId

channelId: string

Defined in: sdk/typescript/src/models/events.ts:74

data

data: object

Defined in: sdk/typescript/src/models/events.ts:75

name?

optional name: string

topic?

optional topic: string

type?

optional type: string

type

type: "channelUpdate"

Defined in: sdk/typescript/src/models/events.ts:73

MemberJoinedEvent

Defined in: sdk/typescript/src/models/events.ts:84

Properties

channelId

channelId: string

Defined in: sdk/typescript/src/models/events.ts:86

data

data: object

Defined in: sdk/typescript/src/models/events.ts:87

user_id

user_id: string

type

type: "memberJoin"

Defined in: sdk/typescript/src/models/events.ts:85

MemberLeftEvent

Defined in: sdk/typescript/src/models/events.ts:90

Properties

channelId

channelId: string

Defined in: sdk/typescript/src/models/events.ts:92

data

data: object

Defined in: sdk/typescript/src/models/events.ts:93

user_id

user_id: string

type

type: "memberLeave"

Defined in: sdk/typescript/src/models/events.ts:91

MessageCreatedEvent

Defined in: sdk/typescript/src/models/events.ts:42

Properties

channelId

channelId: string

Defined in: sdk/typescript/src/models/events.ts:44

data

data: MessageData

Defined in: sdk/typescript/src/models/events.ts:45

type

type: "messageCreate"

Defined in: sdk/typescript/src/models/events.ts:43

MessageDeletedEvent

Defined in: sdk/typescript/src/models/events.ts:54

Properties

channelId

channelId: string

Defined in: sdk/typescript/src/models/events.ts:56

data

data: object

Defined in: sdk/typescript/src/models/events.ts:57

message_id

message_id: string

type

type: "messageDelete"

Defined in: sdk/typescript/src/models/events.ts:55

MessageUpdatedEvent

Defined in: sdk/typescript/src/models/events.ts:48

Properties

channelId

channelId: string

Defined in: sdk/typescript/src/models/events.ts:50

data

data: MessageData

Defined in: sdk/typescript/src/models/events.ts:51

type

type: "messageUpdate"

Defined in: sdk/typescript/src/models/events.ts:49

TypingStartEvent

Defined in: sdk/typescript/src/models/events.ts:96

Properties

channelId

channelId: string

Defined in: sdk/typescript/src/models/events.ts:98

data

data: object

Defined in: sdk/typescript/src/models/events.ts:99

user_id

user_id: string

type

type: "typingStart"

Defined in: sdk/typescript/src/models/events.ts:97

Type Aliases

EventType

EventType = "ready" | "messageCreate" | "messageUpdate" | "messageDelete" | "channelCreate" | "channelUpdate" | "channelDelete" | "memberJoin" | "memberLeave" | "typingStart"

Defined in: sdk/typescript/src/models/events.ts:6

SSE event types emitted by the Syncopate backend.

SyncopateEvent

SyncopateEvent = MessageCreatedEvent | MessageUpdatedEvent | MessageDeletedEvent | ChannelCreatedEvent | ChannelUpdatedEvent | ChannelDeletedEvent | MemberJoinedEvent | MemberLeftEvent | TypingStartEvent

Defined in: sdk/typescript/src/models/events.ts:103

Discriminated union of all event types.

Functions

Command()

Command(name, options?): (target, propertyKey, _descriptor) => void

Defined in: sdk/typescript/src/decorators/command.ts:34

Decorator that registers a method as a bot command handler.

Commands are triggered by messages matching the command prefix + name. Default prefix is !.

Parameters

name

string

options?

description?

string

Returns

(target, propertyKey, _descriptor): void

Parameters

target

unknown

propertyKey

string

_descriptor

PropertyDescriptor

Returns

void

Example

class MyBot extends Bot {
  @Command('ping')
  async ping(ctx: Context) {
    await ctx.reply('Pong!');
  }

  @Command('greet', { description: 'Greet someone' })
  async greet(ctx: Context) {
    const name = ctx.args[0] ?? 'world';
    await ctx.reply(`Hello, ${name}!`);
  }
}

OnEvent()

OnEvent(event): (target, propertyKey, _descriptor) => void

Defined in: sdk/typescript/src/decorators/event.ts:31

Decorator that registers a method as an event handler.

Parameters

event

EventType

Returns

(target, propertyKey, _descriptor): void

Parameters

target

unknown

propertyKey

string

_descriptor

PropertyDescriptor

Returns

void

Example

class MyBot extends Bot {
  @OnEvent('messageCreate')
  async onMessage(message: Message) {
    // Handle message
  }

  @OnEvent('ready')
  async onReady() {
    console.log('Bot is ready!');
  }
}