crowdplaysdk 0.2.3

package/src/index.ts

@@ -0,0 +1,294 @@
+/**
+ * crowdplaysdk — CrowdPlay's lossless capture SDK for React Native (iOS).
+ *
+ * The recording engine is 100% native (CrowdPlaySDK): studio-grade audio
+ * (48 kHz / 24-bit, unprocessed) + 1080p30 video captured locally during a
+ * live call, clock-synced across participants, uploaded to CrowdPlay with
+ * retries and crash recovery. **No media ever crosses the JS bridge** —
+ * only control calls and state events — so recording quality is identical
+ * to a fully native app.
+ *
+ *     import CrowdPlay, { CrowdPlayConsentScreen, CrowdPlayVideoView } from 'crowdplaysdk';
+ *
+ *     CrowdPlay.configure({ serverUrl: '…', appKey: 'liva_pk_…' });
+ *     // Show CrowdPlayConsentScreen (or your own UI) → ConsentGrant
+ *     await CrowdPlay.join({ displayName: 'Sam', roomCode: 'abc', consent });
+ *     // …
+ *     await CrowdPlay.leave(); // recording stops; uploads continue automatically
+ *
+ * Consent is enforced twice: join() throws here without a grant, and the
+ * native layer requires the consent record structurally — there is no code
+ * path that records without it.
+ */
+
+import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Live-call (Path A) quality. The RECORDING is always 1080p30 + 24-bit WAV
+ * regardless; raising these trades upload + thermal headroom (which the
+ * recording needs on long sessions) for a prettier live picture. Values are
+ * clamped natively to a safe envelope (≤1280×720, 10–30 fps, ≤2.5 Mbps
+ * video, 16–128 kbps audio). */
+export interface CallQuality {
+  videoWidth?: number;
+  videoHeight?: number;
+  videoFps?: number;
+  videoBitrate?: number;
+  audioBitrate?: number;
+}
+
+export interface CrowdPlayConfig {
+  /** CrowdPlay backend base URL (https, no trailing slash). */
+  serverUrl: string;
+  /** From the CrowdPlay dashboard. Also your data-access credential. */
+  appKey: string;
+  /** Video (~2 GB/session) rides cellular too when true. Audio + metadata
+   * always upload on any network. Default false. */
+  videoUploadsOnCellular?: boolean;
+  /** Upload segments while the call records, so the post-call wait is
+   * roughly the final segment + manifests. Mid-call transfers run one at
+   * a time and pause automatically when call quality drops — the call
+   * always wins the uplink. Default true. */
+  uploadDuringCall?: boolean;
+  callQuality?: CallQuality;
+}
+
+/** Proof the participant agreed. Produce it with CrowdPlayConsentScreen, or —
+ * if you render your own consent UI — call CrowdPlay.consentText() to show the
+ * REQUIRED wording and construct the grant at the moment of agreement. */
+export interface ConsentGrant {
+  /** Date.now() at the moment the participant agreed. */
+  grantedAtMs: number;
+}
+
+export type Phase = 'idle' | 'connecting' | 'connected' | 'failed';
+
+export interface RecordingSnapshot {
+  /** Seconds of audio safely written so far. */
+  seconds: number;
+  segmentsClosed: number;
+  droppedSamples: number;
+  /** Live input level. Speech sits around −25…−45 dBFS. */
+  inputLevelDbfs: number;
+  /** True after 10 s of silence while unmuted — a dead/disconnected mic.
+   * Surface this loudly; it is fixable mid-call. */
+  inputSilent: boolean;
+  /** Samples at digital full scale — a too-hot mic, irreversibly clipped. */
+  fullScaleSamples: number;
+}
+
+export interface UploadKindProgress {
+  total: number;
+  uploaded: number;
+  failed: number;
+  bytesTotal: number;
+  bytesUploaded: number;
+}
+
+export interface UploadProgress {
+  sessionId: string;
+  fraction: number;
+  isComplete: boolean;
+  failed: number;
+  /** Manifests + audio: upload on any network. */
+  audio: UploadKindProgress;
+  /** Video: waits for WiFi unless videoUploadsOnCellular. */
+  video: UploadKindProgress;
+}
+
+export interface Participant {
+  identity: string;
+  name: string;
+}
+
+export interface DoctorCheck {
+  id: string;
+  passed: boolean;
+  detail: string;
+}
+
+export interface CrowdPlayEvents {
+  /** Connection lifecycle. `error` is set when phase === 'failed'. */
+  phase: { phase: Phase; error?: string };
+  /** Recording state. `error` non-null means the session is NOT being
+   * captured — show it prominently and offer retryRecording(). */
+  recording: { isRecording: boolean; error?: string };
+  /** Upload progress for every session with outstanding or recent work. */
+  uploads: { sessions: UploadProgress[]; onWifi: boolean };
+  /** Remote participants (join/leave). Render a CrowdPlayVideoView per entry. */
+  participants: { participants: Participant[] };
+  /** Live capture warnings: audioStalled (engine down, auto-recovering),
+   * micSilent (dead mic), clipping (too-hot mic), crossTalk (loudspeaker
+   * leaking the far end into this mic), micPolicy (unexpected input). */
+  warning: { kind: 'audioStalled' | 'micSilent' | 'clipping' | 'crossTalk' | 'micPolicy'; active: boolean; message: string };
+  /** The audio output route: current device by name ("AirPods Pro",
+   * "iPhone speaker"), connected candidates, and whether headphones are
+   * attached. Drive the call screen's output menu from this (D-079). */
+  audioRoute: { currentOutputName: string; detectedOutputs: string[]; headphonesConnected: boolean };
+}
+
+export type CrowdPlayEventName = keyof CrowdPlayEvents;
+
+// ---------------------------------------------------------------------------
+// Native module access
+// ---------------------------------------------------------------------------
+
+interface NativeCrowdPlay {
+  configure(config: Record<string, unknown>): void;
+  consentText(): Promise<string>;
+  join(displayName: string, roomCode: string, consentGrantedAtMs: number): Promise<void>;
+  leave(): Promise<void>;
+  setMicMuted(muted: boolean): Promise<void>;
+  setCameraEnabled(enabled: boolean): Promise<void>;
+  retryRecording(): void;
+  retryUploads(): void;
+  warmUp(): void;
+  setAudioOutput(output: string): void;
+  snapshot(): Promise<RecordingSnapshot | null>;
+  doctor(): Promise<DoctorCheck[]>;
+  addListener(eventName: string): void;
+  removeListeners(count: number): void;
+}
+
+function native(): NativeCrowdPlay {
+  const module = NativeModules.CrowdPlayReactNative as NativeCrowdPlay | undefined;
+  if (!module) {
+    throw new Error(
+      "crowdplaysdk: native module not found. iOS setup: add the CrowdPlaySDK " +
+        "Swift package (https://github.com/symbiateam/crowdplaysdk) to your Xcode " +
+        "project and add the two bridge files from node_modules/crowdplaysdk/ios " +
+        "to your app target — see the package README. " +
+        (Platform.OS !== 'ios' ? `(platform '${Platform.OS}' is not supported yet — iOS only.)` : '')
+    );
+  }
+  return module;
+}
+
+let emitter: NativeEventEmitter | undefined;
+function events(): NativeEventEmitter {
+  if (!emitter) {
+    emitter = new NativeEventEmitter(NativeModules.CrowdPlayReactNative);
+  }
+  return emitter;
+}
+
+let configured = false;
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+const CrowdPlay = {
+  /** Call once at app start, before anything else. Also resumes uploads
+   * interrupted by a crash, reboot or force-quit. */
+  configure(config: CrowdPlayConfig): void {
+    if (!config?.serverUrl || !/^https:\/\//.test(config.serverUrl)) {
+      throw new Error('crowdplaysdk: configure() needs a https serverUrl');
+    }
+    if (!config.appKey) {
+      throw new Error('crowdplaysdk: configure() needs the appKey from your CrowdPlay dashboard');
+    }
+    native().configure(config as unknown as Record<string, unknown>);
+    configured = true;
+  },
+
+  /** The REQUIRED consent wording (owned by CrowdPlay, versioned by hash). Show
+   * it verbatim if you build your own consent UI. */
+  consentText(): Promise<string> {
+    return native().consentText();
+  },
+
+  /** Pre-warms CrowdPlay's backend so joining is fast. Call from your join/lobby
+   * screen. Fire-and-forget. */
+  warmUp(): void {
+    native().warmUp();
+  },
+
+  /**
+   * Join a room. Recording starts automatically on join and stops on
+   * leave(). Rejects if the connection fails.
+   *
+   * `consent` is REQUIRED — produce it with <CrowdPlayConsentScreen> or from
+   * your own UI at the moment of agreement. There is no way to record
+   * without it, here or natively.
+   */
+  async join(options: { displayName: string; roomCode: string; consent: ConsentGrant }): Promise<void> {
+    if (!configured) {
+      throw new Error('crowdplaysdk: call CrowdPlay.configure() before join()');
+    }
+    const { displayName, roomCode, consent } = options ?? ({} as never);
+    if (!displayName?.trim()) throw new Error('crowdplaysdk: displayName is required');
+    if (!roomCode?.trim()) throw new Error('crowdplaysdk: roomCode is required');
+    if (!consent || typeof consent.grantedAtMs !== 'number' || consent.grantedAtMs <= 0) {
+      throw new Error(
+        'crowdplaysdk: join() requires a ConsentGrant. Show CrowdPlayConsentScreen ' +
+          '(or your own UI displaying CrowdPlay.consentText()) and pass its result. ' +
+          'Recording without consent is not supported.'
+      );
+    }
+    return native().join(displayName.trim(), roomCode, consent.grantedAtMs);
+  },
+
+  /** Leave the room. Recording stops; uploads proceed automatically (they
+   * survive backgrounding; force-quit pauses them until next launch). */
+  leave(): Promise<void> {
+    return native().leave();
+  },
+
+  /** Mutes the call AND writes silence into the recording (never records
+   * someone who believes they are muted). */
+  setMicMuted(muted: boolean): Promise<void> {
+    return native().setMicMuted(muted);
+  },
+
+  /** Camera off sends + records black frames; the timeline stays continuous. */
+  setCameraEnabled(enabled: boolean): Promise<void> {
+    return native().setCameraEnabled(enabled);
+  },
+
+  /** Retry after a `recording` event with an error (the meeting is NOT
+   * being captured until this succeeds). */
+  retryRecording(): void {
+    native().retryRecording();
+  },
+
+  /** Re-attempts any uploads that settled as failed. */
+  /** Route call audio: 'automatic' = the connected device (AirPods,
+   * wired, ...), 'speaker' = force the loudspeaker. Pair with the
+   * 'audioRoute' event to build an output menu. */
+  setAudioOutput(output: 'automatic' | 'speaker'): void {
+    native().setAudioOutput(output);
+  },
+
+  retryUploads(): void {
+    native().retryUploads();
+  },
+
+  /** Live recording stats (REC timer, input level, silence/clipping). Null
+   * when not recording. Poll ~1 Hz for a status line. */
+  snapshot(): Promise<RecordingSnapshot | null> {
+    return native().snapshot();
+  },
+
+  /** Integration self-check: configuration, permissions, disk, backend
+   * reachability, app-key auth. Every failing check names its fix. */
+  doctor(): Promise<DoctorCheck[]> {
+    return native().doctor();
+  },
+
+  /** Subscribe to state events. Returns a subscription; call .remove(). */
+  addListener<E extends CrowdPlayEventName>(
+    event: E,
+    listener: (payload: CrowdPlayEvents[E]) => void
+  ): { remove(): void } {
+    const subscription = events().addListener(`crowdplay:${event}`, listener as (payload: unknown) => void);
+    return { remove: () => subscription.remove() };
+  },
+};
+
+export default CrowdPlay;
+export { CrowdPlayConsentScreen } from './ConsentScreen';
+export { CrowdPlayVideoView } from './VideoView';