vg-x07df 0.1.0

package/packages/sdk/src/state/errors.ts

@@ -0,0 +1,163 @@
+import type { LogLevel } from "../utils/logger";
+import { rtcStore } from "./store";
+import type { RtcError } from "./types";
+
+// Re-export RtcError type for external consumption
+export type { RtcError } from "./types";
+
+export type ErrorCode =
+  | "NETWORK"
+  | "SOCKET_PAYLOAD"
+  | "JOIN_FLOW"
+  | "LIVEKIT_CONNECT"
+  | "LIVEKIT_MEDIA"
+  | "MEDIA_PERMISSION"
+  | "DEVICE_SWITCH"
+  | "API_ERROR"
+  | "UNEXPECTED";
+
+export function pushError(
+  code: ErrorCode,
+  message: string,
+  context?: any,
+  logger?: (level: LogLevel, message: string, meta?: any) => void
+): void {
+  const error: RtcError = {
+    code,
+    message,
+    timestamp: Date.now(),
+    context,
+  };
+
+  // Log the error if logger is provided
+  logger?.("error", message, { code, context });
+  rtcStore.getState().addError(error);
+}
+
+/**
+ * Clear errors from the store
+ * @param predicate Optional filter function - if provided, only matching errors are removed
+ */
+export function clearErrors(predicate?: (error: RtcError) => boolean): void {
+  rtcStore.getState().patch((state) => {
+    if (predicate) {
+      // Remove only errors matching the predicate
+      state.errors = state.errors.filter((error) => !predicate(error));
+    } else {
+      // Clear all errors
+      state.errors = [];
+    }
+  });
+}
+
+// Convenience helpers for common error scenarios
+export function pushSocketValidationError(
+  eventType: string,
+  issues: any,
+  payload?: any,
+  logger?: (level: LogLevel, message: string, meta?: any) => void
+): void {
+  pushError(
+    "SOCKET_PAYLOAD",
+    `Invalid ${eventType} event payload`,
+    { eventType, issues, payload },
+    logger
+  );
+}
+
+export function pushIdentityGuardError(
+  reason: string,
+  expected?: string,
+  received?: string,
+  logger?: (level: LogLevel, message: string, meta?: any) => void
+): void {
+  pushError(
+    "JOIN_FLOW", // Use new error code
+    `Identity guard failed: ${reason}`,
+    { expected, received },
+    logger
+  );
+}
+
+export function pushLiveKitConnectError(
+  message: string,
+  error: unknown,
+  logger?: (level: LogLevel, message: string, meta?: any) => void
+): void {
+  pushError(
+    "LIVEKIT_CONNECT",
+    `LiveKit connection failed: ${message}`,
+    { originalError: error },
+    logger
+  );
+}
+
+export function pushStaleEventError(
+  eventType: string,
+  reason: string,
+  context?: any,
+  logger?: (level: LogLevel, message: string, meta?: any) => void
+): void {
+  pushError(
+    "JOIN_FLOW", // Use new error code
+    `Ignored stale ${eventType} event: ${reason}`,
+    context,
+    logger
+  );
+}
+
+export function pushApiError(
+  operation: string,
+  error: unknown,
+  logger?: (level: LogLevel, message: string, meta?: any) => void
+): void {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  pushError(
+    "API_ERROR",
+    `API ${operation} failed: ${errorMessage}`,
+    { operation, originalError: error },
+    logger
+  );
+}
+
+export function pushNetworkError(
+  operation: string,
+  error: unknown,
+  logger?: (level: LogLevel, message: string, meta?: any) => void
+): void {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  pushError(
+    "NETWORK",
+    `Network error during ${operation}: ${errorMessage}`,
+    { operation, originalError: error },
+    logger
+  );
+}
+
+export function pushMediaPermissionError(
+  device: string,
+  error?: unknown,
+  logger?: (level: LogLevel, message: string, meta?: any) => void
+): void {
+  pushError(
+    "MEDIA_PERMISSION",
+    `${device} permission denied`,
+    { device, originalError: error },
+    logger
+  );
+}
+
+export function pushDeviceError(
+  operation: string,
+  device: string,
+  error: unknown,
+  logger?: (level: LogLevel, message: string, meta?: any) => void
+): void {
+  const errorMessage = error instanceof Error ? error.message : String(error);
+  pushError(
+    "DEVICE_SWITCH",
+    `Failed to ${operation} ${device}: ${errorMessage}`,
+    { operation, device, originalError: error },
+    logger
+  );
+}

package/packages/sdk/src/state/selectors.ts

@@ -0,0 +1,28 @@
+import { useRtcStore } from "./store";
+import type { Participant } from "./types";
+
+export function useParticipants(): Participant[] {
+  return useRtcStore((state) => Object.values(state.room.participants));
+}
+
+export function useParticipant(id: string): Participant | undefined {
+  return useRtcStore((state) => state.room.participants[id]);
+}
+
+export function useRingingParticipants(): Participant[] {
+  return useRtcStore((state) =>
+    Object.values(state.room.participants).filter(
+      (p) => p.callState === "RINGING"
+    )
+  );
+}
+
+export function useLocalParticipant(): Participant | undefined {
+  return undefined;
+}
+
+export function useSpeakingParticipants(): Participant[] {
+  return useRtcStore((state) =>
+    Object.values(state.room.participants).filter((p) => p.isSpeaking)
+  );
+}

package/packages/sdk/src/state/store.ts

@@ -0,0 +1,36 @@
+import { create } from "zustand";
+import { immer } from "zustand/middleware/immer";
+import type { RtcError, RtcState } from "./types";
+import { defaultState } from "./types";
+
+type Actions = {
+  patch: (fn: (draft: RtcState) => void) => void;
+  reset: () => void;
+  addError: (error: RtcError) => void;
+  clearErrors: () => void;
+};
+
+export const useRtcStore = create<RtcState & Actions>()(
+  immer((set) => ({
+    ...defaultState,
+
+    patch: (fn) =>
+      set((state) => {
+        fn(state);
+      }),
+
+    reset: () => set(() => defaultState),
+
+    addError: (error) =>
+      set((state) => {
+        state.errors.push(error);
+      }),
+
+    clearErrors: () =>
+      set((state) => {
+        state.errors = [];
+      }),
+  }))
+);
+
+export const rtcStore = useRtcStore;

package/packages/sdk/src/state/types.ts

@@ -0,0 +1,151 @@
+export type SessionStatus =
+  | "IDLE"
+  | "CALLING"        // Caller initiated, waiting for acceptance
+  | "RINGING"        // Incoming call (callee perspective)
+  | "ACCEPTED"       // Call accepted but not yet joined media
+  | "AWAITING_JOIN_INFO"  // Waiting for join credentials
+  | "READY_TO_JOIN"  // Has join-info but not connected to media
+  | "CONNECTING"     // Joining LiveKit room
+  | "ACTIVE"         // Successfully connected to media session
+  | "ENDED";
+
+// Unified Participant interface - combines all participant data
+export interface Participant {
+  id: string;
+  // Profile data
+  firstName?: string;
+  lastName?: string;
+  avatarUrl?: string;
+  // Call state
+  role: "CALLER" | "CALLEE" | "HOST" | "MEMBER";
+  callState: "INVITED" | "RINGING" | "JOINED" | "LEFT";
+  // Media state
+  audioEnabled: boolean;
+  videoEnabled: boolean;
+  isSpeaking: boolean;
+  connectionQuality?: "excellent" | "good" | "poor" | "lost" | "unknown";
+  // Timestamps
+  invitedAt?: number;
+  joinedAt?: number;
+  leftAt?: number;
+}
+
+export type PermissionStatus = "granted" | "denied" | "prompt" | "unknown";
+
+export interface DeviceState {
+  mics: MediaDeviceInfo[];
+  cams: MediaDeviceInfo[];
+  speakers: MediaDeviceInfo[];
+  selected: {
+    micId: string | undefined;
+    camId: string | undefined;
+    speakerId: string | undefined;
+  };
+  permissions: {
+    camera: PermissionStatus;
+    microphone: PermissionStatus;
+  };
+  isEnumerating: boolean;
+  lastEnumeratedAt: number | undefined;
+}
+
+export interface IncomingCallInfo {
+  callId: string;
+  caller: {
+    id: string;
+    name: string;
+    avatarUrl: string | undefined;
+  };
+  type: "AUDIO" | "VIDEO";
+  timestamp: number;
+}
+
+export interface LiveKitJoinInfo {
+  token: string;
+  roomName: string;
+  callId: string;
+  url?: string;
+}
+
+export interface RtcError {
+  code: string;
+  message: string;
+  timestamp: number;
+  context?: any;
+}
+
+export type AutoJoinStatus = "idle" | "pending" | "retrying" | "succeeded" | "failed";
+
+export interface AutoJoinState {
+  status: AutoJoinStatus;
+  attempt: number;
+  maxAttempts: number;
+  lastError?: string;
+  startedAt?: number;
+  completedAt?: number;
+}
+
+export interface RtcState {
+  session: {
+    id?: string;
+    status: SessionStatus;
+    mode?: "AUDIO" | "VIDEO";
+    livekitInfo?: LiveKitJoinInfo;
+    // Identity context: how did I get into this call?
+    myRole?: "CALLER" | "CALLEE";
+    initiatedByMe: boolean;
+  };
+
+  room: {
+    participants: Record<string, Participant>; // Single unified record
+  };
+
+  local: {
+    audioEnabled: boolean;
+    videoEnabled: boolean;
+    screenEnabled: boolean;
+  };
+
+  connection: {
+    connected: boolean;
+    reconnecting: boolean;
+    quality?: "excellent" | "good" | "poor" | "lost";
+  };
+
+  autoJoin: AutoJoinState;
+  devices: DeviceState;
+  errors: RtcError[];
+  incomingCall: IncomingCallInfo | undefined;
+}
+
+export const defaultState: RtcState = {
+  session: { status: "IDLE", initiatedByMe: false },
+  room: {
+    participants: {},
+  },
+  local: { audioEnabled: false, videoEnabled: false, screenEnabled: false },
+  connection: { connected: false, reconnecting: false },
+  autoJoin: {
+    status: "idle",
+    attempt: 0,
+    maxAttempts: 0,
+  },
+  devices: {
+    mics: [],
+    cams: [],
+    speakers: [],
+    selected: {
+      micId: undefined,
+      camId: undefined,
+      speakerId: undefined,
+    },
+    permissions: {
+      camera: "unknown",
+      microphone: "unknown",
+    },
+    isEnumerating: false,
+    lastEnumeratedAt: undefined,
+  },
+  errors: [],
+  incomingCall: undefined,
+};

package/packages/sdk/src/utils/logger.ts

@@ -0,0 +1,183 @@
+/**
+ * Comprehensive logging system for the Callpad Web SDK
+ *
+ * Features:
+ * - Log level filtering (debug, info, warn, error)
+ * - Environment variable configuration (DEBUG, CALLPAD_LOG_LEVEL)
+ * - Hierarchical namespacing (callpad:socket:connection)
+ * - Custom logger integration
+ * - Zero-cost when disabled
+ */
+
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+export interface LoggerOptions {
+  level?: LogLevel;
+  enableDebug?: boolean;
+  customLogger?: (level: LogLevel, message: string, meta?: any) => void;
+}
+
+export interface CallpadLogger {
+  debug(message: string, meta?: any): void;
+  info(message: string, meta?: any): void;
+  warn(message: string, meta?: any): void;
+  error(message: string, meta?: any): void;
+  child(namespace: string): CallpadLogger;
+  setLevel(level: LogLevel): void;
+  isLevelEnabled(level: LogLevel): boolean;
+}
+
+const LOG_LEVELS: Record<LogLevel, number> = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+class CallpadLoggerImpl implements CallpadLogger {
+  private namespace: string;
+  private level: LogLevel;
+  private enableDebug: boolean;
+  private customLogger?: (level: LogLevel, message: string, meta?: any) => void;
+
+  constructor(namespace = "callpad", options: LoggerOptions = {}) {
+    this.namespace = namespace;
+    this.level = options.level ?? this.getDefaultLevel();
+    this.enableDebug = options.enableDebug ?? this.shouldEnableDebug();
+    if (options.customLogger) {
+      this.customLogger = options.customLogger;
+    }
+  }
+
+  private getDefaultLevel(): LogLevel {
+    const envLevel =
+      typeof window !== "undefined"
+        ? (window as any).__CALLPAD_LOG_LEVEL__
+        : typeof globalThis !== "undefined" &&
+          (globalThis as any).process?.env?.CALLPAD_LOG_LEVEL;
+
+    if (envLevel && this.isValidLogLevel(envLevel)) {
+      return envLevel as LogLevel;
+    }
+
+    const isProduction =
+      typeof globalThis !== "undefined" &&
+      (globalThis as any).process?.env?.NODE_ENV === "production";
+
+    return isProduction ? "warn" : "info";
+  }
+
+  private shouldEnableDebug(): boolean {
+    const debugEnv =
+      typeof window !== "undefined"
+        ? (window as any).__DEBUG__
+        : typeof globalThis !== "undefined" &&
+          (globalThis as any).process?.env?.DEBUG;
+
+    if (!debugEnv) return false;
+
+    const debugPatterns = debugEnv.split(/[\s,]+/);
+    return debugPatterns.some((pattern: string) => {
+      if (pattern === "*") return true;
+      if (pattern.endsWith("*")) {
+        const prefix = pattern.slice(0, -1);
+        return this.namespace.startsWith(prefix);
+      }
+      return this.namespace === pattern;
+    });
+  }
+
+  private isValidLogLevel(level: string): boolean {
+    return Object.keys(LOG_LEVELS).includes(level);
+  }
+
+  private shouldLog(level: LogLevel): boolean {
+    if (level === "debug" && !this.enableDebug) {
+      return false;
+    }
+    return LOG_LEVELS[level] >= LOG_LEVELS[this.level];
+  }
+
+  private formatMessage(level: LogLevel, message: string, meta?: any): void {
+    if (!this.shouldLog(level)) return;
+
+    const timestamp = new Date().toISOString();
+    const prefix = `[${timestamp}] [${this.namespace}] [${level.toUpperCase()}]`;
+
+    if (this.customLogger) {
+      this.customLogger(level, message, meta);
+      return;
+    }
+
+    const logMethod =
+      level === "error"
+        ? console.error
+        : level === "warn"
+          ? console.warn
+          : level === "info"
+            ? console.info
+            : console.log;
+
+    if (meta !== undefined) {
+      logMethod(`${prefix} ${message}`, meta);
+    } else {
+      logMethod(`${prefix} ${message}`);
+    }
+  }
+
+  debug(message: string, meta?: any): void {
+    this.formatMessage("debug", message, meta);
+  }
+
+  info(message: string, meta?: any): void {
+    this.formatMessage("info", message, meta);
+  }
+
+  warn(message: string, meta?: any): void {
+    this.formatMessage("warn", message, meta);
+  }
+
+  error(message: string, meta?: any): void {
+    this.formatMessage("error", message, meta);
+  }
+
+  child(namespace: string): CallpadLogger {
+    const childNamespace = `${this.namespace}:${namespace}`;
+    const childOptions: LoggerOptions = {
+      level: this.level,
+      enableDebug: this.enableDebug,
+    };
+    if (this.customLogger) {
+      childOptions.customLogger = this.customLogger;
+    }
+    return new CallpadLoggerImpl(childNamespace, childOptions);
+  }
+
+  setLevel(level: LogLevel): void {
+    this.level = level;
+  }
+
+  isLevelEnabled(level: LogLevel): boolean {
+    return this.shouldLog(level);
+  }
+}
+
+let rootLogger: CallpadLogger | null = null;
+
+export function createLogger(
+  namespace?: string,
+  options?: LoggerOptions
+): CallpadLogger {
+  if (!namespace) {
+    if (!rootLogger) {
+      rootLogger = new CallpadLoggerImpl("callpad", options);
+    }
+    return rootLogger;
+  }
+
+  return new CallpadLoggerImpl(`callpad:${namespace}`, options);
+}
+
+export function setGlobalLoggerOptions(options: LoggerOptions): void {
+  rootLogger = new CallpadLoggerImpl("callpad", options);
+}

package/packages/sdk/tsconfig.json

@@ -0,0 +1,49 @@
+{
+  "compilerOptions": {
+    // Base configuration (standalone, no dependency on monorepo)
+    "target": "ES2020",
+    "lib": ["DOM", "DOM.Iterable", "ES2020"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noFallthroughCasesInSwitch": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+
+    // Library-specific configuration
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist/types",
+    
+    // Additional strictness for library
+    "exactOptionalPropertyTypes": true,
+    "noImplicitReturns": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    
+    // Library output settings
+    "removeComments": false,
+    "preserveConstEnums": true,
+    "inlineSources": true
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    "**/*.stories.ts",
+    "**/*.stories.tsx"
+  ]
+}

package/packages/sdk/tsup.config.ts

@@ -0,0 +1,51 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: {
+    index: "src/index.ts",
+    "livekit/index": "src/livekit/index.ts",
+  },
+  format: ["cjs", "esm"],
+  sourcemap: true,
+  clean: true,
+  splitting: false,
+  treeshake: true,
+  minify: false, // Keep readable for debugging
+  external: [
+    "react",
+    "react-dom",
+    "livekit-client",
+    "socket.io-client",
+    "axios",
+    "jwt-decode",
+    "zustand",
+    "immer",
+    "zod",
+  ],
+  target: "es2020",
+  platform: "browser",
+  outExtension({ format }) {
+    return {
+      js: format === "esm" ? ".mjs" : ".cjs",
+    };
+  },
+  // Production optimizations
+  bundle: true,
+  skipNodeModulesBundle: true,
+  noExternal: [],
+  // Library specific settings
+  esbuildOptions(options) {
+    options.banner = {
+      js: '"use client";', // Next.js client component support
+    };
+    options.jsx = "automatic";
+    options.jsxImportSource = "react";
+  },
+  // Type generation
+  dts: {
+    resolve: true,
+    compilerOptions: {
+      moduleResolution: "bundler",
+    },
+  },
+});

package/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+packages:
+  - "apps/*"
+  - "packages/*"
+  - "examples/*"

package/tsconfig.base.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["DOM", "DOM.Iterable", "ES2020"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "strict": true,
+    "forceConsistentCasingInFileNames": true,
+    "noFallthroughCasesInSwitch": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx"
+  }
+}