Skip to main content

​
fetchRooms

Retrieves rooms sorted by start time with automatic status calculation. Rooms are categorized as “live”, “upcoming”, or “finished” and sorted by priority (live first, then upcoming, then finished).
​
userId
string
Filter rooms by author ID
​
cursorRoomId
string
Cursor for pagination. Pass the last room ID to fetch the next page of results.
Returns: Promise<Room[]> - Array of rooms with computed status field
​
status
'upcoming' | 'live' | 'finished'
Computed status based on current time, startTime, and endTime:
  • “finished”: endTime is in the past
  • “upcoming”: startTime is in the future
  • “live”: between startTime and endTime
Error Handling: Throws error if fetching fails. Error is logged and re-thrown. 
import { fetchRooms } from '@/services/rooms.service';

// Fetch all rooms
const rooms = await fetchRooms({});

// Fetch rooms by user
const userRooms = await fetchRooms({ userId: 'user123' });

// Fetch next page
const lastRoomId = rooms[rooms.length - 1].$id;
const nextPage = await fetchRooms({ cursorRoomId: lastRoomId });

// Filter by status
const liveRooms = rooms.filter(room => room.status === 'live');
const upcomingRooms = rooms.filter(room => room.status === 'upcoming');

​
executeRoom

Executes a room action through the rooms guard function. This is the recommended way to perform room operations as it includes proper validation and authorization.
​
action
'create' | 'update' | 'delete'
required
The action to perform on the room
​
teams
string[]
required
Array of team names participating in the match
​
startTime
string
required
ISO 8601 timestamp for match start time
​
matchType
'ODI' | 'TEST' | 'T20'
required
Type of cricket match
​
isLocked
boolean
required
Whether the room is locked for new participants
​
roomId
string
Room ID (required for update and delete actions)
​
endTime
string
ISO 8601 timestamp for match end time
Returns: Promise<Execution> Error Handling: Throws error if execution fails or status is “failed”. Error message from execution is included. Error is logged and re-thrown. 
import { executeRoom } from '@/services/rooms.service';

// Create a room
await executeRoom({
  action: 'create',
  teams: ['India', 'Australia'],
  startTime: '2026-03-15T10:00:00Z',
  matchType: 'ODI',
  isLocked: false
});

// Update a room
await executeRoom({
  action: 'update',
  roomId: 'room123',
  teams: ['India', 'Australia'],
  startTime: '2026-03-15T10:00:00Z',
  endTime: '2026-03-15T18:00:00Z',
  matchType: 'ODI',
  isLocked: true
});

// Delete a room
await executeRoom({
  action: 'delete',
  roomId: 'room123',
  teams: [],
  startTime: '',
  matchType: 'ODI',
  isLocked: false
});

​
fetchRoomMessages

Retrieves messages for a specific room, sorted by creation date (newest first). Limited to 50 messages.
​
roomId
string
required
ID of the room whose messages to fetch
Returns: Promise<{ rows: RoomMessage[], total: number }> Error Handling: Throws error if fetching fails. Error is logged and re-thrown. 
import { fetchRoomMessages } from '@/services/roomMessage.service';

const data = await fetchRoomMessages('room123');
const messages = data.rows;

// Messages are sorted newest first
const latestMessage = messages[0];

​
executeRoomMessage

Executes a room message action through the room message guard function. This is the recommended way to perform message operations as it includes proper validation, rate limiting, and push notifications.
​
action
'create' | 'update' | 'delete'
required
The action to perform on the message
​
roomId
string
required
ID of the room where the message belongs
​
content
string
Message content (required for create and update actions)
​
roomMessageId
string
Message ID (required for update and delete actions)
Returns: Promise<Execution> Error Handling: Throws error if execution fails or status is “failed”. Error is logged and re-thrown. 
import { executeRoomMessage } from '@/services/roomMessage.service';

// Send a message
await executeRoomMessage({
  action: 'create',
  roomId: 'room123',
  content: 'What a shot! Six runs!'
});

// Edit a message
await executeRoomMessage({
  action: 'update',
  roomId: 'room123',
  roomMessageId: 'msg456',
  content: 'Updated message content'
});

// Delete a message
await executeRoomMessage({
  action: 'delete',
  roomId: 'room123',
  roomMessageId: 'msg456'
});
Room messages have a rate limit of 60 requests per minute enforced by the room-message-guard function. Creating messages also triggers push notifications to other room participants.

Build docs developers (and LLMs) love

Get started for freeTalk to us