@shadowob/sdk 0.2.1

package/src/constants.ts

@@ -0,0 +1,15 @@
+// Re-export shared event constants for convenience
+
+export type { ClientEvent, ServerEvent } from '@shadowob/shared'
+export { CLIENT_EVENTS, SERVER_EVENTS } from '@shadowob/shared'
+
+// ─── Room helpers ───────────────────────────────────────────────────────────
+
+/** Build a Socket.IO room name for a channel */
+export const channelRoom = (channelId: string) => `channel:${channelId}` as const
+
+/** Build a Socket.IO room name for a thread */
+export const threadRoom = (threadId: string) => `thread:${threadId}` as const
+
+/** Build a Socket.IO room name for user-level notifications */
+export const userRoom = (userId: string) => `user:${userId}` as const

package/src/index.ts

@@ -0,0 +1,47 @@
+// Client
+export { ShadowClient } from './client'
+export type { ClientEvent, ServerEvent } from './constants'
+// Constants & room helpers
+export {
+  CLIENT_EVENTS,
+  channelRoom,
+  SERVER_EVENTS,
+  threadRoom,
+  userRoom,
+} from './constants'
+export type { ShadowSocketOptions } from './socket'
+// Socket
+export { ShadowSocket } from './socket'
+
+// Types
+export type {
+  ChannelCreatedPayload,
+  ChannelMemberAddedPayload,
+  ChannelMemberRemovedPayload,
+  ClientEventMap,
+  DmMessage,
+  MemberJoinPayload,
+  MemberLeavePayload,
+  MessageDeletedPayload,
+  PolicyChangedPayload,
+  PresenceActivityPayload,
+  PresenceChangePayload,
+  ReactionPayload,
+  ServerEventMap,
+  ServerJoinedPayload,
+  ShadowAttachment,
+  ShadowChannel,
+  ShadowChannelPolicy,
+  ShadowDmChannel,
+  ShadowInviteCode,
+  ShadowMember,
+  ShadowMessage,
+  ShadowNotification,
+  ShadowRemoteChannel,
+  ShadowRemoteConfig,
+  ShadowRemoteServer,
+  ShadowServer,
+  ShadowThread,
+  ShadowUser,
+  TypingPayload,
+} from './types'

package/src/socket.ts

@@ -0,0 +1,180 @@
+import { io, type Socket } from 'socket.io-client'
+import type { ClientEventMap, ServerEventMap } from './types'
+
+export interface ShadowSocketOptions {
+  /** Shadow server base URL (e.g. "https://shadow.example.com") */
+  serverUrl: string
+  /** JWT token for authentication */
+  token: string
+  /** Socket.IO transports (default: ['websocket']) */
+  transports?: string[]
+  /** Auto-reconnect on disconnect (default: true) */
+  autoReconnect?: boolean
+  /** Reconnection delay in ms (default: 1000) */
+  reconnectionDelay?: number
+}
+
+type ServerEventName = keyof ServerEventMap
+type ServerEventHandler<E extends ServerEventName> = ServerEventMap[E]
+
+/**
+ * Shadow real-time event listener.
+ *
+ * Wraps Socket.IO with strongly-typed events that match the Shadow server
+ * gateway broadcasts. Provides channel/thread room management and
+ * convenience methods for sending messages and typing indicators.
+ */
+export class ShadowSocket {
+  private socket: Socket
+  private _connected = false
+
+  constructor(options: ShadowSocketOptions) {
+    this.socket = io(options.serverUrl, {
+      auth: { token: options.token },
+      transports: options.transports ?? ['websocket'],
+      autoConnect: false,
+      reconnection: options.autoReconnect ?? true,
+      reconnectionDelay: options.reconnectionDelay ?? 1000,
+    })
+
+    this.socket.on('connect', () => {
+      this._connected = true
+    })
+    this.socket.on('disconnect', () => {
+      this._connected = false
+    })
+  }
+
+  /** Whether the socket is currently connected */
+  get connected(): boolean {
+    return this._connected
+  }
+
+  /** The underlying Socket.IO socket instance */
+  get raw(): Socket {
+    return this.socket
+  }
+
+  // ── Connection lifecycle ──────────────────────────────────────────────
+
+  /** Connect to the Shadow server */
+  connect(): void {
+    if (!this.socket.connected) {
+      this.socket.connect()
+    }
+  }
+
+  /** Disconnect from the Shadow server */
+  disconnect(): void {
+    this.socket.disconnect()
+  }
+
+  /** Wait until the socket is connected (resolves immediately if already connected) */
+  waitForConnect(timeoutMs = 5000): Promise<void> {
+    if (this.socket.connected) return Promise.resolve()
+    return new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`Socket connect timeout after ${timeoutMs}ms`))
+      }, timeoutMs)
+      this.socket.once('connect', () => {
+        clearTimeout(timer)
+        resolve()
+      })
+    })
+  }
+
+  // ── Typed event listeners ─────────────────────────────────────────────
+
+  /** Listen for a server event */
+  on<E extends ServerEventName>(event: E, handler: ServerEventHandler<E>): this {
+    this.socket.on(event as string, handler as (...args: unknown[]) => void)
+    return this
+  }
+
+  /** Listen for a server event (one-time) */
+  once<E extends ServerEventName>(event: E, handler: ServerEventHandler<E>): this {
+    this.socket.once(event as string, handler as (...args: unknown[]) => void)
+    return this
+  }
+
+  /** Remove a specific event listener */
+  off<E extends ServerEventName>(event: E, handler: ServerEventHandler<E>): this {
+    this.socket.off(event as string, handler as (...args: unknown[]) => void)
+    return this
+  }
+
+  /** Remove all listeners for an event or all events */
+  removeAllListeners(event?: ServerEventName): this {
+    if (event) {
+      this.socket.removeAllListeners(event)
+    } else {
+      this.socket.removeAllListeners()
+    }
+    return this
+  }
+
+  // ── Connection event listeners ────────────────────────────────────────
+
+  /** Listen for raw connection events (connect, disconnect, connect_error) */
+  onConnect(handler: () => void): this {
+    this.socket.on('connect', handler)
+    return this
+  }
+
+  onDisconnect(handler: (reason: string) => void): this {
+    this.socket.on('disconnect', handler)
+    return this
+  }
+
+  onConnectError(handler: (error: Error) => void): this {
+    this.socket.on('connect_error', handler)
+    return this
+  }
+
+  // ── Room management ───────────────────────────────────────────────────
+
+  /** Join a channel room to receive its messages and events */
+  joinChannel(channelId: string): Promise<{ ok: boolean }> {
+    return new Promise((resolve) => {
+      this.socket.emit(
+        'channel:join' satisfies keyof ClientEventMap,
+        { channelId },
+        (res: { ok: boolean }) => {
+          resolve(res ?? { ok: true })
+        },
+      )
+    })
+  }
+
+  /** Leave a channel room */
+  leaveChannel(channelId: string): void {
+    this.socket.emit('channel:leave' satisfies keyof ClientEventMap, { channelId })
+  }
+
+  // ── Client actions ────────────────────────────────────────────────────
+
+  /** Send a message via WebSocket (text-only; for file attachments use REST) */
+  sendMessage(data: {
+    channelId: string
+    content: string
+    threadId?: string
+    replyToId?: string
+  }): void {
+    this.socket.emit('message:send' satisfies keyof ClientEventMap, data)
+  }
+
+  /** Send a typing indicator */
+  sendTyping(channelId: string): void {
+    this.socket.emit('message:typing' satisfies keyof ClientEventMap, { channelId })
+  }
+
+  /** Update user presence status */
+  updatePresence(status: 'online' | 'idle' | 'dnd' | 'offline'): void {
+    this.socket.emit('presence:update' satisfies keyof ClientEventMap, { status })
+  }
+
+  /** Update activity status in a channel (e.g. 'thinking', 'working', null) */
+  updateActivity(channelId: string, activity: string | null): void {
+    this.socket.emit('presence:activity' satisfies keyof ClientEventMap, { channelId, activity })
+  }
+}

package/src/types.ts

@@ -0,0 +1,252 @@
+// ─── Shadow SDK Types ───────────────────────────────────────────────────────
+
+/** Message returned by the Shadow REST API and Socket.IO broadcasts */
+export interface ShadowMessage {
+  id: string
+  content: string
+  channelId: string
+  authorId: string
+  threadId?: string | null
+  replyToId?: string | null
+  isPinned?: boolean
+  createdAt: string
+  updatedAt: string
+  author?: {
+    id: string
+    username: string
+    displayName?: string | null
+    avatarUrl?: string | null
+    isBot?: boolean
+  }
+  attachments?: ShadowAttachment[]
+}
+
+export interface ShadowAttachment {
+  id: string
+  filename: string
+  url: string
+  contentType: string
+  size: number
+  width?: number | null
+  height?: number | null
+}
+
+export interface ShadowChannel {
+  id: string
+  name: string
+  type: string
+  serverId: string
+  description?: string | null
+  position?: number
+}
+
+export interface ShadowDmChannel {
+  id: string
+  user1Id: string
+  user2Id: string
+  createdAt: string
+}
+
+export interface ShadowThread {
+  id: string
+  name: string
+  channelId: string
+  parentMessageId: string
+  createdAt: string
+}
+
+export interface ShadowMember {
+  userId: string
+  serverId: string
+  role: string
+  user?: ShadowUser
+}
+
+export interface ShadowInviteCode {
+  id: string
+  code: string
+  createdBy: string
+  usedBy?: string | null
+  usedAt?: string | null
+  isActive: boolean
+  note?: string | null
+  createdAt: string
+}
+
+export interface ShadowServer {
+  id: string
+  name: string
+  slug: string
+  description: string | null
+  iconUrl: string | null
+  bannerUrl: string | null
+  homepageHtml: string | null
+  isPublic: boolean
+}
+
+export interface ShadowUser {
+  id: string
+  username: string
+  displayName?: string
+  avatarUrl?: string
+  isBot?: boolean
+  agentId?: string
+}
+
+export interface ShadowNotification {
+  id: string
+  userId: string
+  type: string
+  title: string
+  body: string
+  referenceId?: string
+  referenceType?: string
+  isRead: boolean
+  createdAt: string
+}
+
+// ─── Channel Policy Types ───────────────────────────────────────────────────
+
+export interface ShadowChannelPolicy {
+  listen: boolean
+  reply: boolean
+  mentionOnly: boolean
+  config: Record<string, unknown>
+}
+
+export interface ShadowRemoteChannel {
+  id: string
+  name: string
+  type: string
+  policy: ShadowChannelPolicy
+}
+
+export interface ShadowRemoteServer {
+  id: string
+  name: string
+  slug?: string
+  iconUrl?: string | null
+  defaultPolicy: ShadowChannelPolicy
+  channels: ShadowRemoteChannel[]
+}
+
+export interface ShadowRemoteConfig {
+  agentId: string
+  botUserId: string
+  servers: ShadowRemoteServer[]
+}
+
+// ─── Socket Event Payloads ──────────────────────────────────────────────────
+
+export interface TypingPayload {
+  channelId: string
+  userId: string
+  username: string
+}
+
+export interface PresenceChangePayload {
+  userId: string
+  status: 'online' | 'idle' | 'dnd' | 'offline'
+}
+
+export interface PresenceActivityPayload {
+  userId: string
+  activity: string | null
+  channelId: string
+}
+
+export interface MemberJoinPayload {
+  channelId: string
+  userId: string
+}
+
+export interface MemberLeavePayload {
+  channelId: string
+  userId: string
+}
+
+export interface ReactionPayload {
+  messageId: string
+  userId: string
+  emoji: string
+}
+
+export interface MessageDeletedPayload {
+  id: string
+  channelId: string
+}
+
+export interface ChannelCreatedPayload {
+  id: string
+  name: string
+  type: string
+  serverId: string
+}
+
+export interface ChannelMemberAddedPayload {
+  channelId: string
+  userId: string
+}
+
+export interface ChannelMemberRemovedPayload {
+  channelId: string
+  userId: string
+}
+
+export interface ServerJoinedPayload {
+  serverId: string
+  serverName: string
+}
+
+export interface PolicyChangedPayload {
+  agentId: string
+  serverId: string
+  channelId?: string | null
+}
+
+export interface DmMessage {
+  id: string
+  content: string
+  senderId: string
+  receiverId: string
+  createdAt: string
+}
+
+// ─── Socket Event Map ───────────────────────────────────────────────────────
+
+/** Events the server pushes to the client */
+export interface ServerEventMap {
+  'message:new': (message: ShadowMessage) => void
+  'message:updated': (message: ShadowMessage) => void
+  'message:deleted': (payload: MessageDeletedPayload) => void
+  'member:typing': (payload: TypingPayload) => void
+  'member:join': (payload: MemberJoinPayload) => void
+  'member:leave': (payload: MemberLeavePayload) => void
+  'presence:change': (payload: PresenceChangePayload) => void
+  'presence:activity': (payload: PresenceActivityPayload) => void
+  'reaction:add': (payload: ReactionPayload) => void
+  'reaction:remove': (payload: ReactionPayload) => void
+  'notification:new': (notification: ShadowNotification) => void
+  'dm:message:new': (message: DmMessage) => void
+  'channel:created': (payload: ChannelCreatedPayload) => void
+  'channel:member-added': (payload: ChannelMemberAddedPayload) => void
+  'channel:member-removed': (payload: ChannelMemberRemovedPayload) => void
+  'server:joined': (payload: ServerJoinedPayload) => void
+  'agent:policy-changed': (payload: PolicyChangedPayload) => void
+  error: (payload: { message: string }) => void
+}
+
+/** Events the client sends to the server */
+export interface ClientEventMap {
+  'channel:join': (data: { channelId: string }, ack?: (res: { ok: boolean }) => void) => void
+  'channel:leave': (data: { channelId: string }) => void
+  'message:send': (data: {
+    channelId: string
+    content: string
+    threadId?: string
+    replyToId?: string
+  }) => void
+  'message:typing': (data: { channelId: string }) => void
+  'presence:update': (data: { status: 'online' | 'idle' | 'dnd' | 'offline' }) => void
+  'presence:activity': (data: { channelId: string; activity: string | null }) => void
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "include": ["src"]
+}