zyncedjs

A Node.js client library for building bots on Zynced — a typed, event-driven wrapper around Zynced's WebSocket and REST API.

Installation

npm install zyncedjs

Getting a Token

1. Create a regular account at zynced.app.
2. Open your browser's DevTools and inspect the cookies for the site.
3. Your token is a combination of two cookies, formatted as:

cf_clearance=...;connect.sid=...;

Concatenate both cookie values into a single string and pass it as your token.

Note: cf_clearance may expire and need to be refreshed if your process restarts. Once the bot is up and running, it should remain stable.

Quick Start

import { Client } from 'zyncedjs';

const client = new Client('cf_clearance=...;connect.sid=...;');

client.on('ready', ({ user, channels, guilds }) => {
    console.log(`Logged in as ${user.username}`);
    
    // subscribe to all 'general' channels
    channels.findAllByName("general").forEach(channel => {
        channel.subscribe();
    });
});

client.on('messageCreate', (message) => {
    if (message.content === '!ping') {
        client.channel(message.channelId)?.send('Pong!');
    }
});

client.login();

Client

new Client(token, options?)

The main entry point for your bot.

| Parameter | Type | Description | |-----------|-----------------|------------------------------------| | token | string | Your Zynced session token (see above) | | options | ClientOptions | Optional configuration |

Properties

| Property | Type | Description | |------------|------------------|------------------------------------------| | user | ClientUser | The bot's own user object | | channels | ChannelManager | Manager for all DM/private channels | | guilds | GuildManager | Manager for all guild (server) channels |

Methods

| Method | Returns | Description | |---------------------------|----------------|------------------------------------------------------| | login() | Promise<void>| Connects to Zynced and emits ready when done | | channel(id) | Channel | Look up a channel by its ID | | joinGuild(guildId) | Promise<any> | Join a guild by ID | | acceptInvite(from) | Promise<any> | Accept a DM invite from a user |

Events

Listen to events with client.on(event, handler).

client.on('ready', ({ user, channels, guilds }) => { ... });
client.on('messageCreate', (message) => { ... });
client.on('privateMessageCreate', (message) => { ... });
client.on('memberJoined', (data) => { ... });
client.on('memberLeft', (data) => { ... });
client.on('userInvite', (data) => { ... });

ready

Fired once the client has connected and fetched all initial data.

{
    user: ClientUser;
    channels: ChannelManager;
    guilds: GuildManager;
}

messageCreate

Fired when a message is sent in a guild or subscribed channel. Payload is a Message object.

privateMessageCreate

Fired when a DM is received. Payload is a PrivateMessage object.

memberJoined / memberLeft

Fired when a member joins or leaves a channel/guild. Payload is a RawMemberAction object.

userInvite

Fired when another user sends your bot a DM invite. Payload is a RawUserInvite object. You can respond with client.acceptInvite(from).

Types

Message

Represents a message in a guild channel.

| Property | Type | Description | |-------------|-----------|----------------------------------------------| | id | number | Message index within the channel | | guildId | string | ID of the guild the message belongs to | | channelId | string | ID of the channel | | content | string | Text content of the message | | author | string | Username of the sender | | date | Date | When the message was sent | | isReply | boolean | Whether this message is a reply to another |

Methods

message.reply(content: string, attachments?: MessageAttachment[])

Replies to the message in the same channel.

PrivateMessage

Represents a direct message received by the bot.

| Property | Type | Description | |------------|----------|------------------------------------| | content | string | Text content of the message | | author | string | Username of the sender | | date | Date | When the message was received | | chatmode | string | Chat mode identifier |

Channel

Represents a text or voice channel. Extends BaseChannel.

Properties (from BaseChannel)

| Property | Type | Description | |-------------------------|--------------------|--------------------------------------------------| | id | string | Unique channel ID | | name | string | Display name | | description | string | Channel description | | type | 'text' \| 'voice'| Channel type | | owner | string | Username of the channel owner | | group_id | string \| null | Guild ID if this is a guild channel, else null | | category_id | string \| null | Category this channel belongs to | | position | number \| null | Sort order position | | blocked | boolean | Whether the channel is blocked | | avatar | string | Channel avatar URL | | accept_joins | boolean | Whether the channel accepts new joins | | created_at | string | ISO timestamp of creation | | user_joined_at | string | When the bot joined this channel | | lastMessageAt | number | Unix timestamp of the last message |

Methods

For bot to be able to read messages in a channel, it must first subscribe to it. Once subscribed, you can send messages and listen to new messages in that channel.

// Send a text message, optionally with attachments
channel.send(message: string, attachments?: MessageAttachment[])

// Subscribe to live messages in this channel
channel.subscribe()

MessageAttachment

Attach a GIF or file to a message.

interface MessageAttachment {
    type: 'gif' | 'file';
    url: string;      // URL for GIFs, local file path for files
    name?: string;
}

Example:

channel.send('Here is a gif!', [{ type: 'gif', url: 'https://media.giphy.com/...' }]);
channel.send('Here is a file!', [{ type: 'file', url: './report.pdf' }]);

ClientUser

Represents the bot's own Zynced account.

| Property | Type | Description | |----------------|-----------|----------------------------------| | id | string | User ID | | username | string | Display name | | avatar | string | Avatar URL | | status | string | Custom status text | | bannerUrl | string | Profile banner URL | | onlineStatus | string | Online/away/offline state | | isPremium | boolean | Whether the account has Premium |

Methods

await client.user.setStatus('Building something cool...');

console.log(client.user.toString()); // "my-bot#userId"

Example: Echo Bot

import { Client } from 'zyncedjs';

const client = new Client('cf_clearance=...;connect.sid=...;');

client.on('ready', ({ user }) => {
    console.log(`Ready! Logged in as ${user}`);

    client.channels.findAllByName("general").forEach(channel => {
        channel.subscribe();
    });
});

client.on('messageCreate', (message) => {
    if (message.author === client.user.username) return; // ignore self

    client.channel(message.channelId)?.send(message.content);
});

client.on('userInvite', async (invite) => {
    await client.acceptInvite(invite.from);
});

client.login();