vg-x07df 0.1.0

package/packages/sdk/src/core/signal/signal.client.ts

@@ -0,0 +1,101 @@
+import { CallsService } from "../../generated/api";
+import type { CallsData } from "../../generated/api/models";
+import { createLogger } from "../../utils/logger";
+import type {
+  CallActionResponse,
+  CallResponse,
+  InitiateCallParams,
+  SignalClientConfig,
+} from "./types";
+
+export class SignalClient {
+  private config: SignalClientConfig;
+  private logger = createLogger("signal");
+
+  constructor(config: SignalClientConfig) {
+    this.config = config;
+  }
+
+  async initiate(params: InitiateCallParams): Promise<CallResponse> {
+    try {
+      return await CallsService.postSignalCalls({
+        appId: this.config.appId,
+        requestBody: {
+          mode: params.mode || "AUDIO",
+          participants: params.invitees.map((userId) => ({ userId })),
+        },
+      });
+    } catch (error) {
+      this.handleApiError("initiate", error);
+      throw error;
+    }
+  }
+
+  async accept(callId: string): Promise<CallActionResponse> {
+    try {
+      const response = await CallsService.postSignalCallsByCallIdAccept({
+        callId,
+        appId: this.config.appId,
+      });
+      return {
+        ...response,
+        callId,
+        state: "ACTIVE" as const,
+        message: "Call accepted",
+      };
+    } catch (error) {
+      this.handleApiError("accept", error);
+      throw error;
+    }
+  }
+
+  async decline(callId: string): Promise<CallActionResponse> {
+    try {
+      const response = await CallsService.postSignalCallsByCallIdDecline({
+        callId,
+        appId: this.config.appId,
+      });
+      return {
+        ...response,
+        callId,
+        state: "ENDED" as const,
+        message: "Call declined",
+      };
+    } catch (error) {
+      this.handleApiError("decline", error);
+      throw error;
+    }
+  }
+
+  async leave(callId: string): Promise<CallActionResponse> {
+    try {
+      const response = await CallsService.postSignalCallsByCallIdLeave({
+        callId,
+        appId: this.config.appId,
+      });
+      return {
+        ...response,
+        callId,
+        state: "ENDED" as const,
+        message: "Left call",
+      };
+    } catch (error) {
+      this.handleApiError("leave", error);
+      throw error;
+    }
+  }
+
+  private handleApiError(operation: string, error: any): void {
+    const errorMessage =
+      error?.body?.message || error?.message || "Unknown error";
+    const errorCode = error?.status || error?.code || "UNKNOWN";
+
+    // Log error for debugging - real-time error handling happens via Socket.IO
+    this.logger.error(`Signal API error during ${operation}`, {
+      operation,
+      errorCode,
+      errorMessage,
+      error,
+    });
+  }
+}

package/packages/sdk/src/core/signal/types.ts

@@ -0,0 +1,110 @@
+import type { AuthManager } from "../auth.manager";
+
+export interface SignalClientConfig {
+  baseUrl: string;
+  appId: string;
+  authManager: AuthManager;
+}
+
+export interface CallInfo {
+  id: string;
+  mode: "AUDIO" | "VIDEO";
+  state: "RINGING" | "ACTIVE" | "ON_HOLD" | "ENDED";
+  callerId: string;
+  roomName: string;
+  lkRoomSid?: string;
+  createdAt: string;
+  startedAt?: string;
+  endedAt?: string;
+  participants: CallParticipant[];
+}
+
+export interface CallParticipant {
+  id: string;
+  userId: string;
+  joinedAt?: string;
+  leftAt?: string;
+  lkIdentity?: string;
+  lkParticipantSid?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface LiveKitJoinInfo {
+  token: string;
+  roomName: string;
+  callId: string;
+}
+
+export interface IncomingCallEvent {
+  callId: string;
+  fromUserId: string;
+  fromUserName: string;
+  fromUserAvatar?: string;
+  type: "VIDEO" | "AUDIO";
+  timestamp: number;
+  participants?: string[];
+}
+
+export type CallState = "RINGING" | "ACTIVE" | "ON_HOLD" | "ENDED";
+export type CallMode = "AUDIO" | "VIDEO";
+export type EndReason = "ENDED" | "TIMEOUT" | "ERROR" | "CANCELLED";
+
+export class SignalError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public statusCode?: number
+  ) {
+    super(message);
+    this.name = "SignalError";
+  }
+}
+
+export interface InitiateCallParams {
+  invitees: string[];
+  mode?: "AUDIO" | "VIDEO";
+  metadata?: any;
+}
+
+export interface ApiConfig {
+  baseUrl: string;
+  token?: string | (() => Promise<string> | string);
+  credentials?: "include" | "omit" | "same-origin";
+  withCredentials?: boolean;
+  headers?: Record<string, string>;
+}
+
+// Backend API Response Types
+export interface CallResponse {
+  id: string;
+  mode: "AUDIO" | "VIDEO";
+  state: "RINGING" | "ACTIVE" | "ON_HOLD" | "ENDED";
+  callerId: string;
+  roomName: string;
+  lkRoomSid?: string;
+  createdAt: string;
+  startedAt?: string;
+  endedAt?: string;
+  participants: Array<{
+    id: string;
+    userId: string;
+    joinedAt?: string;
+    leftAt?: string;
+    lkIdentity?: string;
+    lkParticipantSid?: string;
+    createdAt: string;
+    updatedAt: string;
+  }>;
+}
+
+export interface CallActionResponse {
+  callId: string;
+  state: "RINGING" | "ACTIVE" | "ON_HOLD" | "ENDED";
+  message: string;
+  token?: string;
+  roomName?: string;
+}
+
+// Legacy alias for backward compatibility
+export type LeaveCallResponse = CallActionResponse;

package/packages/sdk/src/core/socketio/handlers/base.handler.ts

@@ -0,0 +1,212 @@
+import type { ZodSchema } from "zod";
+import { pushSocketValidationError } from "../../../state/errors";
+import { rtcStore } from "../../../state/store";
+import { createLogger } from "../../../utils/logger";
+import type { CallpadLogger } from "../../../utils/logger";
+import type { AutoJoinConfig } from "../../types";
+import type { AuthManager } from "../../auth.manager";
+
+export interface SocketHandlerOptions {
+  livekit?: any;
+  autoJoinConfig?: AutoJoinConfig | null;
+  authManager?: AuthManager;
+}
+
+export abstract class BaseSocketHandler<T = any> {
+  protected abstract readonly eventName: string;
+  protected abstract readonly schema: ZodSchema<T>;
+  private _logger?: CallpadLogger;
+
+  constructor(protected readonly options: SocketHandlerOptions = {}) {}
+
+  protected get logger(): CallpadLogger {
+    if (!this._logger) {
+      this._logger = createLogger(`socketio:${this.eventName}`);
+    }
+    return this._logger;
+  }
+
+  protected get authManager(): AuthManager | undefined {
+    return this.options.authManager;
+  }
+
+  async handleRaw(rawData: unknown): Promise<void> {
+    this.logger.info(`${this.eventName} received`, rawData);
+
+    const result = this.schema.safeParse(rawData);
+    if (!result.success) {
+      this.logger.error(
+        `${this.eventName} validation failed`,
+        result.error.issues
+      );
+      pushSocketValidationError(
+        this.eventName,
+        result.error.issues,
+        rawData,
+        (level, message, meta) => {
+          switch (level) {
+            case "debug":
+              this.logger.debug(message, meta);
+              break;
+            case "info":
+              this.logger.info(message, meta);
+              break;
+            case "warn":
+              this.logger.warn(message, meta);
+              break;
+            case "error":
+              this.logger.error(message, meta);
+              break;
+          }
+        }
+      );
+      return;
+    }
+
+    try {
+      await this.handle(result.data);
+      this.logger.debug(`${this.eventName} handled successfully`);
+    } catch (error) {
+      this.logger.error(`${this.eventName} handler error`, error);
+      throw error;
+    }
+  }
+
+  protected abstract handle(data: T): Promise<void> | void;
+
+  protected updateStore(updater: (state: any) => void): void {
+    rtcStore.getState().patch(updater);
+  }
+
+  protected get livekit() {
+    return this.options.livekit;
+  }
+
+  protected get autoJoinConfig() {
+    return this.options.autoJoinConfig;
+  }
+
+  /**
+   * Retry logic with exponential backoff for auto-join operations
+   */
+  protected async retryAutoJoin(
+    callId: string,
+    token: string,
+    url: string,
+    attempt = 1
+  ): Promise<boolean> {
+    const maxAttempts = this.autoJoinConfig?.maxRetries || 2;
+    
+    // Initialize auto-join state on first attempt
+    if (attempt === 1) {
+      this.updateStore((state) => {
+        state.autoJoin = {
+          status: "pending",
+          attempt: 1,
+          maxAttempts,
+          startedAt: Date.now(),
+        };
+      });
+    } else {
+      // Update state for retry attempts
+      this.updateStore((state) => {
+        state.autoJoin.status = "retrying";
+        state.autoJoin.attempt = attempt;
+      });
+    }
+    
+    if (attempt > maxAttempts) {
+      this.logger.warn("Max retry attempts reached for auto-join", {
+        callId,
+        maxAttempts,
+        finalAttempt: attempt - 1,
+      });
+      
+      // Mark as failed
+      this.updateStore((state) => {
+        state.autoJoin.status = "failed";
+        state.autoJoin.completedAt = Date.now();
+        state.autoJoin.lastError = "Max retry attempts reached";
+      });
+      
+      return false;
+    }
+
+    try {
+      this.logger.info("Attempting auto-join", {
+        callId,
+        attempt,
+        maxAttempts,
+      });
+
+      await this.livekit?.joinRoom(token, url);
+      
+      this.logger.info("Auto-join successful", {
+        callId,
+        attempt,
+      });
+      
+      // Mark as succeeded
+      this.updateStore((state) => {
+        state.autoJoin.status = "succeeded";
+        state.autoJoin.completedAt = Date.now();
+      });
+      
+      return true;
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : "Unknown error";
+      
+      this.logger.warn("Auto-join attempt failed", {
+        callId,
+        attempt,
+        maxAttempts,
+        error: errorMessage,
+      });
+
+      // Update state with error
+      this.updateStore((state) => {
+        state.autoJoin.lastError = errorMessage;
+      });
+
+      if (attempt < maxAttempts) {
+        // Exponential backoff: 1s, 2s, 4s, etc.
+        // biome-ignore lint/style/useExponentiationOperator: <explanation>
+                const delayMs = Math.pow(2, attempt - 1) * 1000;
+        this.logger.debug("Retrying auto-join after delay", {
+          callId,
+          nextAttempt: attempt + 1,
+          delayMs,
+        });
+
+        await new Promise(resolve => setTimeout(resolve, delayMs));
+        return this.retryAutoJoin(callId, token, url, attempt + 1);
+      }
+
+      // Mark as failed after all attempts
+      this.updateStore((state) => {
+        state.autoJoin.status = "failed";
+        state.autoJoin.completedAt = Date.now();
+      });
+
+      return false;
+    }
+  }
+
+  /**
+   * Determines if an error is retryable
+   */
+  protected isRetryableError(error: any): boolean {
+    if (!error) return false;
+    
+    const errorMessage = error.message?.toLowerCase() || "";
+    const retryableErrors = [
+      "network",
+      "timeout",
+      "connection",
+      "websocket",
+      "transport",
+    ];
+    
+    return retryableErrors.some(keyword => errorMessage.includes(keyword));
+  }
+}

package/packages/sdk/src/core/socketio/handlers/call-accepted.handler.ts

@@ -0,0 +1,34 @@
+import { pushStaleEventError, pushLiveKitConnectError } from "../../../state/errors";
+import { rtcStore } from "../../../state/store";
+import { SdkEventType, eventBus } from "../../events";
+import { BaseSocketHandler } from "./base.handler";
+import { callParticipantAcceptedSchema } from "./schema";
+import type { CallParticipantAcceptedEvent } from "./schema";
+
+export class CallParticipantAcceptedHandler extends BaseSocketHandler<CallParticipantAcceptedEvent> {
+  protected readonly eventName = "call.participant-accepted";
+  protected readonly schema = callParticipantAcceptedSchema;
+
+  protected async handle(data: CallParticipantAcceptedEvent): Promise<void> {
+    const currentState = rtcStore.getState();
+    const currentUserId = this.authManager?.getCurrentUserId();
+    
+    if (currentState.session.id !== data.callId) {
+      pushStaleEventError("call.participant-accepted", "callId mismatch", {
+        eventCallId: data.callId,
+        sessionCallId: currentState.session.id,
+      });
+      return;
+    }
+
+    this.updateStore((state) => {
+      state.session.status = "ACCEPTED";
+      
+      const participant = state.room.participants[data.participantId];
+      if (participant) {
+        participant.callState = "RINGING";
+        participant.joinedAt = data.acceptedAt ? new Date(data.acceptedAt).getTime() : Date.now();
+      }
+    });
+  }
+}

package/packages/sdk/src/core/socketio/handlers/call-canceled.handler.ts

@@ -0,0 +1,34 @@
+import type { Participant } from "../../../state/types";
+import { BaseSocketHandler } from "./base.handler";
+import { callCanceledSchema } from "./schema";
+import type { CallCanceledEvent } from "./schema";
+
+export class CallCanceledHandler extends BaseSocketHandler<CallCanceledEvent> {
+  protected readonly eventName = "call.canceled";
+  protected readonly schema = callCanceledSchema;
+
+  protected handle(data: CallCanceledEvent): void {
+    const reason = data.reason || "canceled";
+    this.logger.info(`Call canceled: ${reason}`, {
+      callId: data.callId,
+      by: data.by?.id,
+    });
+
+    this.updateStore((state) => {
+      if (state.session.id === data.callId) {
+        state.session.status = "ENDED";
+        state.incomingCall = undefined;
+
+        // Clear all participants
+        for (const participant of Object.values(
+          state.room.participants
+        ) as Participant[]) {
+          participant.callState = "LEFT";
+          if (!participant.leftAt) {
+            participant.leftAt = data.timestamp || Date.now();
+          }
+        }
+      }
+    });
+  }
+}

package/packages/sdk/src/core/socketio/handlers/call-declined.handler.ts

@@ -0,0 +1,29 @@
+import { SdkEventType, eventBus } from "../../events";
+import { BaseSocketHandler } from "./base.handler";
+import { callParticipantDeclinedSchema } from "./schema";
+import type { CallParticipantDeclinedEvent } from "./schema";
+
+export class CallParticipantDeclinedHandler extends BaseSocketHandler<CallParticipantDeclinedEvent> {
+  protected readonly eventName = "call.participant-declined";
+  protected readonly schema = callParticipantDeclinedSchema;
+
+  protected handle(data: CallParticipantDeclinedEvent): void {
+    this.updateStore((state) => {
+      if (state.session.id === data.callId) {
+        state.session.status = "IDLE";
+        state.incomingCall = undefined;
+      }
+    });
+
+    eventBus.emit(
+      SdkEventType.CALL_DECLINED,
+      {
+        callId: data.callId,
+        participantId: data.participantId,
+        reason: "declined",
+        timestamp: Date.now(),
+      },
+      "socket"
+    );
+  }
+}

package/packages/sdk/src/core/socketio/handlers/call-ended.handler.ts

@@ -0,0 +1,40 @@
+import { pushStaleEventError } from "../../../state/errors";
+import { BaseSocketHandler } from "./base.handler";
+import { callEndedSchema } from "./schema";
+import type { CallEndedEvent } from "./schema";
+
+export class CallEndedHandler extends BaseSocketHandler<CallEndedEvent> {
+  protected readonly eventName = "call.ended";
+  protected readonly schema = callEndedSchema;
+
+  protected handle(data: CallEndedEvent): void {
+    this.updateStore((state) => {
+      if (state.session.id !== data.callId) {
+        pushStaleEventError("call.ended", "callId mismatch", {
+          eventCallId: data.callId,
+          sessionCallId: state.session.id,
+        });
+        return;
+      }
+
+      state.session.status = "ENDED";
+      state.incomingCall = undefined;
+
+      for (const id of Object.keys(state.room.participants)) {
+        const participant = state.room.participants[id];
+        if (participant) {
+          participant.callState = "LEFT";
+          if (!participant.leftAt) {
+            participant.leftAt = Date.now();
+          }
+        }
+      }
+    });
+
+    if (this.livekit) {
+      this.livekit.disconnect().catch((error: any) => {
+        this.logger.error("Error disconnecting from LiveKit", { error });
+      });
+    }
+  }
+}

package/packages/sdk/src/core/socketio/handlers/call-incoming.handler.ts

@@ -0,0 +1,72 @@
+import { BaseSocketHandler } from "./base.handler";
+import { callIncomingSchema } from "./schema";
+import type { CallIncomingEvent } from "./schema";
+
+export class CallIncomingHandler extends BaseSocketHandler<CallIncomingEvent> {
+  protected readonly eventName = "call.incoming";
+  protected readonly schema = callIncomingSchema;
+
+  protected handle(data: CallIncomingEvent): void {
+    // Find caller from participants array
+    const caller = data.participants.find(
+      (p) => p.role === "CALLER" || p.role === "HOST"
+    );
+
+    if (!caller) {
+      this.logger.error("No caller found in participants", data);
+      return;
+    }
+
+    this.updateStore((state) => {
+      state.incomingCall = {
+        callId: data.callId,
+        caller: {
+          id: caller.id,
+          name:
+            [caller.firstName, caller.lastName].filter(Boolean).join(" ") ||
+            caller.username ||
+            `Guest ${caller.id}`,
+          avatarUrl: caller.profilePhoto,
+        },
+        type: data.type,
+        timestamp: data.timestamp,
+      };
+
+      state.session = {
+        id: data.callId,
+        status: "RINGING",
+        mode: data.type,
+        // Identity context: incoming call, I haven't accepted yet
+        initiatedByMe: false,
+      };
+
+      // Create unified participants from participants array
+      for (const participant of data.participants) {
+        const callState = participant.role === "CALLER" || participant.role === "HOST" ? "JOINED" : "INVITED";
+        
+        state.room.participants[participant.id] = {
+          id: participant.id,
+          firstName: participant.firstName || undefined,
+          lastName: participant.lastName || undefined,
+          avatarUrl: participant.profilePhoto || undefined,
+          role: participant.role || "MEMBER",
+          callState,
+          audioEnabled: false,
+          videoEnabled: false,
+          isSpeaking: false,
+          joinedAt:
+            participant.role === "CALLER" || participant.role === "HOST"
+              ? data.timestamp
+              : undefined,
+        };
+        
+        this.logger.debug("Created participant during incoming call", {
+          participantId: participant.id,
+          role: participant.role || "MEMBER",
+          callState,
+          callId: data.callId,
+        });
+      }
+    });
+  }
+}