serika.js

A highly optimized TypeScript library for the SerikaCord API — Discord v10 compatible bot API + SerikaCord client API.

Features

• Full API coverage — every endpoint in the SerikaCord API
• Discord v10 compatible — bot endpoints match Discord's REST API shape
• Optimized HTTP client — concurrency limiting, automatic retry with exponential backoff + jitter, global rate limit handling, keep-alive connection reuse
• Gateway WebSocket client — HELLO → IDENTIFY → READY lifecycle, heartbeat with zombie detection, RESUME on reconnect, exponential backoff
• TypeScript-first — full type definitions for all request/response payloads
• Zero runtime dependencies in Node 22+, Bun, Deno, and browsers. Optional ws peer dependency for Node 18-21 WebSocket support
• Tree-shakeable ESM

Installation

npm install @serikadev/serika.js
# Node 18-21 also needs the optional ws peer dependency:
npm install @serikadev/serika.js ws
# or
bun add @serikadev/serika.js

Quick Start

Bot with REST + Gateway

import { SerikaClient, Intents } from '@serikadev/serika.js';

const client = new SerikaClient({
  token: 'your-bot-token',
  baseURL: 'https://api.serika.chat', // optional, this is the default
});

// REST: send a message
await client.bot.createMessage('channel-id', {
  content: 'Hello from serika.js!',
});

// Gateway: listen for events
const gw = await client.connectGateway({
  intents: Intents.GUILDS | Intents.GUILD_MESSAGES | Intents.MESSAGE_CONTENT,
});

gw.onDispatch((event, data) => {
  if (event === 'MESSAGE_CREATE') {
    console.log('New message:', (data as any).content);
  }
});

gw.onReady(() => {
  console.log('Bot is ready!');
});

Client API (user session)

import { SerikaClient } from '@serikadev/serika.js';

const client = new SerikaClient({
  authToken: 'your-auth-token',
});

// Get current user
const me = await client.client.getCurrentUser();

// Send a friend request
await client.client.sendFriendRequest('username');

// Get notifications
const { notifications } = await client.client.getNotifications();

API Reference

SerikaClient

Main entry point. Creates an optimized HTTP client and exposes bot (Bot API v10) and client (SerikaCord Client API) namespaces.

Constructor options

Option	Type	Default	Description
baseURL	string	https://api.serika.chat	API base URL
token	string	—	Bot token (sets Authorization: Bot <token>)
authToken	string	—	User auth token (sets Authorization: Bearer <token>)
timeout	number	15000	Request timeout in ms
maxConcurrency	number	10	Max concurrent requests
retries	number	3	Retry attempts on 429/5xx
fetch	typeof fetch	globalThis.fetch	Custom fetch implementation
headers	Record<string, string>	—	Additional default headers

Bot API (client.bot)

Discord v10 compatible endpoints under /api/v10:

• Gateway: getGateway(), getGatewayBot()
• Users: getCurrentUser(), getUser(id), getDMChannels(), createDM(), leaveGuild()
• Guilds: getGuild(), modifyGuild(), getGuildPreview(), getGuildChannels(), createGuildChannel(), modifyGuildChannel(), deleteGuildChannel(), getGuildRoles(), createGuildRole(), modifyGuildRole(), deleteGuildRole(), getGuildMembers(), getGuildMember(), modifyGuildMember(), modifyCurrentUserNick(), removeGuildMember()
• Bans: getGuildBans(), getGuildBan(), createGuildBan(), removeGuildBan()
• Emojis: getGuildEmojis(), getGuildEmoji(), createGuildEmoji(), modifyGuildEmoji(), deleteGuildEmoji()
• Stickers: getGuildStickers(), getGuildSticker()
• Channels: getChannel(), modifyChannel(), deleteChannel()
• Messages: getMessages(), getMessage(), createMessage(), editMessage(), deleteMessage(), bulkDeleteMessages()
• Pins: getPinnedMessages(), pinMessage(), unpinMessage()
• Reactions: addReaction(), removeOwnReaction(), removeUserReaction(), getReactions(), removeAllReactions()
• Typing: triggerTyping()
• Webhooks: getGuildWebhooks(), getChannelWebhooks(), createWebhook(), getWebhook(), deleteWebhook()
• Invites: getInvite(), deleteInvite(), getGuildInvites()
• Audit Log: getGuildAuditLog()
• Application Commands: getGlobalCommands(), getGlobalCommand(), createGlobalCommand(), modifyGlobalCommand(), deleteGlobalCommand(), bulkOverwriteGlobalCommands(), getGuildCommands(), bulkOverwriteGuildCommands()
• Interactions: createInteractionResponse(), createInteractionFollowup()
• Voice: getVoiceRegions()

Client API (client.client)

SerikaCord-specific endpoints:

• Platform: health(), getPlatformAnnouncement(), getFileTypes(), getFileTypesAccept(), getTtsSounds(), getTtsVoices()
• Users: getCurrentUser(), getCurrentUserServers(), getCurrentUserGuilds(), getMentions(), getEmojis(), getStickers(), updateCurrentUser()
• Notifications: getNotifications(), markNotificationsRead()
• Friends: sendFriendRequest(), acceptFriendRequest(), cancelFriendRequest(), declineFriendRequest(), blockUser(), unblockUser(), removeFriend()
• Auth: register(), login(), logout()
• Uploads: uploadAvatar(), uploadBanner()
• Experiments: getExperimentVariant(), getActiveExperiments()
• Developers: getApplications(), getApplication(), createApplication(), updateApplication(), deleteApplication(), getTeams()
• IGDB: lookupGame()
• GIFs: searchGifs(), getTrendingGifs()
• OEmbed: getOEmbed()
• Webhooks: executeWebhook()

Gateway Client

const gw = client.connectGateway({
  intents: Intents.GUILDS | Intents.GUILD_MESSAGES,
  shard: [0, 1],        // optional
  reconnect: true,       // default
  maxReconnectAttempts: 10,
  presence: {
    status: 'online',
    activities: [{ name: 'with serika.js', type: 0 }],
  },
});

// Event handlers
gw.onDispatch((event, data, seq) => { ... });
gw.onReady((data) => { ... });
gw.onError((err) => { ... });
gw.onClose((code, reason) => { ... });

// Send gateway commands
gw.sendPresenceUpdate({ status: 'dnd' });
gw.sendVoiceStateUpdate({ ... });
gw.requestGuildMembers({ ... });

// Disconnect
gw.disconnect(); // graceful

Intents

import { Intents } from '@serikadev/serika.js';

Intents.GUILDS           // 1 << 0
Intents.GUILD_MEMBERS    // 1 << 1
Intents.GUILD_BANS       // 1 << 2
Intents.GUILD_MESSAGES   // 1 << 9
Intents.MESSAGE_CONTENT  // 1 << 15
// ... see types.ts for all flags

Error Handling

import { HTTPError } from '@serikadev/serika.js';

try {
  await client.bot.createMessage('channel-id', { content: 'Hello!' });
} catch (err) {
  if (err instanceof HTTPError) {
    console.error(`HTTP ${err.status}:`, err.body);
    // err.retryAfter — ms until rate limit resets (if 429)
  }
}

License

MIT