Collab-Kit Utils

Shared types and utilities for Collab-Kit.

Install

npm install @collab-kit/utils

Store Schemas

Define typed KV store schemas with defineStores(). The schema is used by @collab-kit/client for type-safe CRUD operations and by the server for validation.

import { defineStores } from '@collab-kit/utils';

const stores = defineStores({
  settings: {
    theme: { type: 'string', required: true, default: 'light' },
    fontSize: { type: 'number', required: true, default: 14 },
    notifications: { type: 'boolean', default: true },
  },
  cursors: {
    x: { type: 'number', required: true },
    y: { type: 'number', required: true },
    color: { type: 'string', default: '#000000' },
  },
});

Field Options

| Option | Type | Description | |---|---|---| | type | 'string' \| 'number' \| 'boolean' | Field primitive type | | required | boolean | If true, field must be present on set. Defaults to false | | default | string \| number \| boolean | Default value applied when field is missing on set |

Type Inference

Schemas are automatically inferred as TypeScript types via InferDocument<S>:

import type { InferDocument } from '@collab-kit/utils';

// Given a schema:
const schema = {
  theme: { type: 'string' as const, required: true as const },
  fontSize: { type: 'number' as const, required: true as const },
  notifications: { type: 'boolean' as const },
};

// InferDocument<typeof schema> resolves to:
// { theme: string; fontSize: number; notifications?: boolean }

Fields with required: true become mandatory keys. All others become optional.

Types

Core Types

import type {
  CollabKitClientOptions,
  CollabKitUser,
  CollabKitRoom,
  CollabKitOrganization,
  ServerResponse,
} from '@collab-kit/utils';

CollabKitClientOptions<T>

Options passed to the client constructor.

{
  serverUrl: string;     // Base HTTP(S) URL of the server
  authToken: string;     // JWT from POST /v1/accounts/:accountId/users
  stores?: T;            // Optional store schemas from defineStores()
}

CollabKitUser

{
  id: string;
  room_id: string;
  name: string;
  profile_picture?: string;
  custom_id?: string;          // optional external identifier
  created_at: string;
  joined_at?: string;
  left_at?: string;
  status: 'online' | 'offline';
  token?: string;              // JWT, present when created via POST /v1/accounts/:accountId/users
  following?: string[];        // ordered chain of followed user IDs
  followers?: string[];        // user IDs who transitively follow this user
}

CollabKitRoom

{
  id: string;
  account_id: string;
  name: string;
  custom_id?: string;          // optional external identifier
  created_at: string;
  state: 'active' | 'disabled';
  duration_seconds: number;
  active_participants: number;
  total_users_created: number;
}

ServerResponse<T>

Standard response envelope used across all server responses.

{
  type: string;
  success: boolean;
  description: string;
  data: T;
  error: ServerResponseError | null;
  requestId?: string;
}

Storage Types

import type {
  UploadResult,
  StorageFile,
  StorageGetAllOptions,
} from '@collab-kit/utils';

| Type | Fields | |---|---| | UploadResult | { key: string; url: string } | | StorageFile | { key, url, filename, mimeType, size, uploadedAt, uploadedBy } | | StorageGetAllOptions | { mimeType?: string \| string[]; userId?: string } |

Socket Types

Types for building custom WebSocket integrations.

import type {
  SocketClientMessage,      // Union of all client-to-server messages
  SocketServerMessage,      // Union of all server-to-client messages
  SocketClientEventMap,     // Lifecycle event map (connected, disconnected, etc.)
  SocketState,              // Connection state enum
  SocketClientOptions,      // Socket constructor options
  SocketMessageResponseMap, // Maps each request MessageType to its response data shape
  InferResponseData,        // Infers response data type from a client message type
} from '@collab-kit/utils';

Type-Safe Responses

SocketMessageResponseMap maps each client request type to the shape of the server's response data field. InferResponseData<T> uses this to infer the response type from a request message, eliminating the need for manual type casts when using sendMessagePromise:

// Before (manual cast):
const response = (await socket.sendMessagePromise(message)) as ServerResponse<{
  comment: CollabKitComment;
}>;

// After (automatically inferred):
const response = await socket.sendMessagePromise(message);
// response.data is typed as { comment: CollabKitComment }

Comment Types

import type {
  CollabKitComment,        // Comment data model (id, text, reactions, tags, replies)
  AddCommentMessage,       // Client -> Server: add a comment
  DeleteCommentMessage,    // Client -> Server: delete a comment
  GetAllCommentsMessage,   // Client -> Server: fetch all comments
} from '@collab-kit/utils';

CollabKitComment

{
  id: string;
  userId: string;
  text: string;
  reactions: Record<string, string[]>; // reaction text -> userIds
  tags: string[];                       // tagged userIds
  parentId: string | null;              // null for top-level, parent ID for replies
  replies: CollabKitComment[];          // nested replies (one level)
  createdAt: string;
}