API Reference

interface PresenceConfig {
  /** Channel identifier — groups users into presence rooms */
  tag: string;
  /** Your application key from the dashboard */
  appKey: string;
  /** Custom API URL for self-hosted deployments */
  apiUrl?: string;
  /** Callback fired whenever the count changes */
  onCountChange?: (count: number) => void;
}

interface CountSnapshot {
  /** Unix timestamp (ms) when snapshot was recorded */
  timestamp: number;
  /** Total sessions (online + away) */
  sessions: number;
  /** Users actively on the page */
  online: number;
  /** Users who switched to another tab */
  away: number;
}

interface TagPeak {
  /** Highest concurrent session count observed */
  peak: number;
  /** When the peak was recorded (ISO date string) */
  peakAt: string;
}

interface PresenceState {
  /** Current live user count */
  count: number;
  /** Historical count snapshots */
  history: CountSnapshot[];
  /** Peak concurrent users */
  peak: number;
  /** When the peak occurred */
  peakAt: Date | null;
  /** Manually refresh history and stats */
  refresh: () => void;
}

type PresenceOptions = {
  appKey: string;
  apiUrl?: string;
};

// React
usePresenceCount(tag: string, options: PresenceOptions): number
usePresence(tag: string, options: PresenceOptions): PresenceState

// SolidJS
createPresenceCount(tag: Accessor<string>, options: Accessor<PresenceOptions>): Accessor<number>
createPresence(tag: Accessor<string>, options: Accessor<PresenceOptions>): PresenceState

// WebSocket URL format:
// wss://<apiUrl>/<appKey>?cid=<clientId>

// Subscribe to count updates (server-sent stream)
presence.on({ tag: string }); // → AsyncIterable<number>

// Update visibility status
presence.update({ tag: string, status: "online" | "away" });

// Fetch historical snapshots
presence.history({ tag: string }); // → CountSnapshot[]

// Fetch peak stats
presence.stats({ tag: string }); // → TagPeak

interface AppSummary {
  id: string;
  name: string;
  key: string;
  createdAt: string;
  activeSessions: number;
}

interface AppDetail extends AppSummary {
  tags: TagInfo[];
  events: PresenceEvent[];
}

// CRUD operations (requires auth session)
apps.list(); // → AppSummary[]
apps.create({ name: string }); // → AppSummary
apps.delete({ id: string }); // → void

// Live watch stream
apps.watch({ id: string }); // → AsyncIterable<WatchAppPayload>

interface WatchAppPayload {
  tags: WatchTagStat[];
  events: PresenceEvent[];
}

interface WatchTagStat {
  tag: string;
  sessions: number;
  online: number;
  away: number;
}

interface PresenceEvent {
  type: "join" | "leave" | "update";
  tag: string;
  clientId: string;
  status: "online" | "away";
  timestamp: string;
}