crowdplaysdk 0.6.1 → 0.6.3

package/README.md

@@ -97,7 +97,7 @@ Bare React Native (no Expo):
 npm install crowdplaysdk
 cd ios && pod install
 gem install xcodeproj --user-install              # one time
-ruby node_modules/crowdplaysdk/ios/wire.rb <YourProjectName>
+ruby ../node_modules/crowdplaysdk/ios/wire.rb <YourProjectName>   # from ios/
 ```
 
 `wire.rb` is idempotent. It adds the compiled CrowdPlaySDK Swift package,
@@ -107,6 +107,18 @@ keeps explicit Swift modules on for the app target (React Native 0.8x turns
 them off project-wide on Xcode 26, which breaks importing the compiled
 engine). There is no CocoaPod of our own, so your Podfile stays untouched.
 
+**Updating.** `npm install crowdplaysdk@latest`, then wire again so the
+engine moves with the bridge: Expo, `npx expo prebuild` (or a build that
+runs prebuild; an `ios/` folder committed to git is not re-wired by
+`eas build`, so run prebuild yourself and commit the result); bare React
+Native, re-run `wire.rb`. Since 0.6.3 that also re-pins the engine to the
+version this package ships with. 0.6.2 and older only added the engine
+the first time, so upgrading in place kept the old engine. Before the
+next local build, clean (Xcode: Product > Clean Build Folder): an
+incremental build can reuse Xcode's cached copy of the previous engine's
+interface and fail on new symbols such as `storageWarning`. EAS Build
+starts clean every time.
+
 **2. Declare permissions in Info.plist** (bare React Native only; the Expo
 plugin does this for you).
 
@@ -165,6 +177,7 @@ CrowdPlay.addListener('phase', …)         // idle / connecting / connected / f
 CrowdPlay.addListener('participants', …)  // who to render tiles for
 CrowdPlay.addListener('uploads', …)       // per-session progress
 CrowdPlay.addListener('warning', …)       // micSilent / clipping / crossTalk: show these
+CrowdPlay.addListener('storageWarning', …) // optional: message set = storage low (audio only or stopped)
 CrowdPlay.addListener('recording', …)     // error means NOT capturing; offer retryRecording()
 CrowdPlay.addListener('audioRoute', …)    // current output device, for the output menu
 CrowdPlay.setAudioOutput('speaker')       // or 'automatic' (the connected device)
@@ -223,29 +236,39 @@ backend reachability and your app key. Every failing check names its own
 fix. Then record a one-minute session on a real device and confirm the
 upload finishes.
 
-## Accessing your recordings
+## Checking your sessions
 
-Your app key is also your data-access credential: plain HTTPS, no AWS
+Your app key also lists the sessions it recorded, over plain HTTPS: no AWS
 account, no SDK required.
 
 ```bash
-BASE=https://dashboard.crowdplay.ai
-
-curl -H "x-liva-key: $APP_KEY" $BASE/sessions
-curl -H "x-liva-key: $APP_KEY" $BASE/sessions/<sessionId>/files
+curl -H "x-liva-key: $APP_KEY" https://dashboard.crowdplay.ai/sessions
 ```
 
-`deliverable/` holds what you actually use: one clean audio file per
-person, aligned so they play together with no offset, plus a mixed version
-and a quality report. You can only reach sessions recorded with your key.
+Each row carries the session id, its state (`uploading`, `ok`, `partial`
+or `failed`), the participants, participant minutes and any quality
+warnings. You only see sessions recorded with your key, and the dashboard
+shows the same list. Use it to confirm that sessions upload and render.
+
+The recordings themselves stay in CrowdPlay's storage. There is no
+download endpoint for builders: `GET /sessions/<sessionId>/files` answers
+403 to an app key, and the dashboard does not offer downloads either.
 
 ## Things to know
 
 - **Don't force-quit the app** after a session: iOS pauses background
   transfers until next launch. They resume automatically and nothing is
   lost.
-- Sessions are roughly 2 GB per participant-hour, dominated by video. The
-  SDK refuses to join below 8 GB free disk.
+- With video, a session uses about 6.8 GB per participant-hour on the phone
+  (1080p HEVC at 14 Mbps plus 24-bit audio); audio-only is about 0.5 GB.
+  Files are deleted as each one uploads. Video waits for WiFi, so on
+  cellular it stays on the phone until then. The SDK never fills the phone
+  (0.6.2+, engine 0.5.4): under 2 GB free the recording continues audio
+  only, under 500 MB it stops, and the call itself always continues. This
+  happens silently: the SDK shows nothing on screen. The `storageWarning`
+  event says when it happens, if you want to ask the user to free up space.
+  `doctor()` also checks free disk (8 GiB by default); joining never
+  refuses for storage.
 - Participants should wear **wired or closed-back headphones**. A
   loudspeaker pipes the far end into the local mic and contaminates the
   track; the SDK surfaces this live through the `warning` event.

package/ios/CrowdPlayRNModule.swift

@@ -63,6 +63,15 @@ final class CrowdPlayRNCore {
                 ])
             }.store(in: &cancellables)
 
+        // Storage (D-148): its own event, not a 'warning' kind, so an app
+        // that renders every warning does not start showing it. Sent on
+        // every change, since the text moves from audio-only to stopped.
+        engine.$storageWarning
+            .removeDuplicates()
+            .sink { [weak self] message in
+                self?.send("crowdplay:storageWarning", ["message": message as Any])
+            }.store(in: &cancellables)
+
         engine.$uploads
             .combineLatest(engine.$uploadsOnWiFi)
             .sink { [weak self] uploads, onWifi in
@@ -231,7 +240,7 @@ public final class CrowdPlayRNModule: RCTEventEmitter {
     public override static func requiresMainQueueSetup() -> Bool { true }
 
     public override func supportedEvents() -> [String]! {
-        ["crowdplay:phase", "crowdplay:recording", "crowdplay:uploads", "crowdplay:participants", "crowdplay:warning", "crowdplay:audioRoute", "crowdplay:voiceActivity", "crowdplay:caption", "crowdplay:agentToolCall"]
+        ["crowdplay:phase", "crowdplay:recording", "crowdplay:uploads", "crowdplay:participants", "crowdplay:warning", "crowdplay:storageWarning", "crowdplay:audioRoute", "crowdplay:voiceActivity", "crowdplay:caption", "crowdplay:agentToolCall"]
     }
 
     @objc public func startVoiceActivityUpdates() {

package/ios/wire.rb

@@ -6,7 +6,8 @@
 #   ruby node_modules/crowdplaysdk/ios/wire.rb <YourProjectName>
 #
 # What it does (idempotent; safe to re-run):
-#   1. adds the CrowdPlaySDK Swift package (compiled engine) to the project
+#   1. adds the CrowdPlaySDK Swift package (compiled engine) to the project,
+#      or re-pins an existing one to SDK_VERSION (an upgrade)
 #   2. copies the three bridge files into your app group + target
 #   3. creates/points the Swift bridging header at the React headers, raises
 #      the app target to iOS 17 and keeps explicit Swift modules ON for it
@@ -30,7 +31,8 @@ SDK_URL = 'https://github.com/symbiateam/crowdplaysdk'
 # D-103 the bridge calls 0.5.0 APIs, and npm 0.5.0 to 0.5.2 shipped with
 # this still at 0.4.0, which broke every install (D-121). publish_rn.sh now
 # compiles the bridge against exactly this release before publishing.
-SDK_VERSION = '0.5.3'
+# 0.5.4: the storage guard and engine.storageWarning (D-148).
+SDK_VERSION = '0.5.4'
 BRIDGE_FILES = ['CrowdPlayRNModule.swift', 'CrowdPlayRNVideoView.swift', 'CrowdPlayReactNative.m'].freeze
 
 project_name = ARGV[0] or abort 'usage: ruby wire.rb <YourProjectName>'
@@ -43,17 +45,30 @@ target = project.targets.find { |t| t.name == project_name } ||
          project.targets.find { |t| t.product_type == 'com.apple.product-type.application' }
 abort 'no application target found' unless target
 
-# 1. CrowdPlaySDK Swift package (skip when already present).
-unless project.root_object.package_references.any? { |r| r.respond_to?(:repositoryURL) && r.repositoryURL == SDK_URL }
+# 1. CrowdPlaySDK Swift package, pinned to exactly SDK_VERSION. An existing
+#    reference is re-pinned, never skipped: step 2 always replaces the bridge
+#    files, and a new bridge against the old engine does not compile (0.6.2
+#    upgraded in place kept engine 0.5.3 and failed on storageWarning, D-151).
+requirement = { 'kind' => 'exactVersion', 'version' => SDK_VERSION }
+existing = project.root_object.package_references.select { |r| r.respond_to?(:repositoryURL) && r.repositoryURL == SDK_URL }
+if existing.empty?
   pkg = project.new(Xcodeproj::Project::Object::XCRemoteSwiftPackageReference)
   pkg.repositoryURL = SDK_URL
-  pkg.requirement = { 'kind' => 'exactVersion', 'version' => SDK_VERSION }
+  pkg.requirement = requirement
   project.root_object.package_references << pkg
   dep = project.new(Xcodeproj::Project::Object::XCSwiftPackageProductDependency)
   dep.package = pkg
   dep.product_name = 'CrowdPlaySDK'
   target.package_product_dependencies << dep
   puts "+ CrowdPlaySDK package #{SDK_VERSION}"
+else
+  existing.each do |pkg|
+    next if pkg.requirement == requirement
+
+    was = (pkg.requirement || {})['version'] || (pkg.requirement || {})['minimumVersion'] || 'unpinned'
+    pkg.requirement = requirement
+    puts "+ CrowdPlaySDK package #{was} -> #{SDK_VERSION}"
+  end
 end
 
 # 2. Bridge files into the app group + target.

package/lib/index.d.ts

@@ -62,7 +62,7 @@ export interface CrowdPlayConfig {
 }
 /** The CrowdPlay Terms of Use and Privacy Notice every participant accepts,
  * as a PDF. CrowdPlayConsentScreen links here; a custom consent UI must too. */
-export declare const CROWDPLAY_TERMS_URL = "https://dashboard.crowdplay.ai/legal/terms.pdf";
+export declare const CROWDPLAY_TERMS_URL = "https://www.crowdplay.ai/legal/consumer-terms";
 /** 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. */
@@ -177,6 +177,14 @@ export interface CrowdPlayEvents {
         active: boolean;
         message: string;
     };
+    /** This iPhone is running out of storage (D-148): under 2 GB free the
+     * recording continues audio only, under 500 MB it stops; the call always
+     * continues. `message` is null when storage is fine. The SDK shows
+     * nothing on screen; listening is optional. Separate from `warning` so
+     * apps that render every warning do not start showing it. */
+    storageWarning: {
+        message: string | null;
+    };
     /** 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). */

package/lib/index.js

@@ -26,7 +26,7 @@ exports.useLatestCaption = exports.useVoiceActivity = exports.VoiceReactive = ex
 const react_native_1 = require("react-native");
 /** The CrowdPlay Terms of Use and Privacy Notice every participant accepts,
  * as a PDF. CrowdPlayConsentScreen links here; a custom consent UI must too. */
-exports.CROWDPLAY_TERMS_URL = 'https://dashboard.crowdplay.ai/legal/terms.pdf';
+exports.CROWDPLAY_TERMS_URL = 'https://www.crowdplay.ai/legal/consumer-terms';
 function native() {
     const module = react_native_1.NativeModules.CrowdPlayReactNative;
     if (!module) {

package/llms.txt

@@ -81,6 +81,14 @@ EXPO (managed, prebuild or EAS Build; app builders such as X1):
     Xcode project. Do not add those Info.plist keys or any native code
     yourself. Expo SDK 50 or newer.
 3.  Rebuild: npx expo prebuild, a development build, or eas build.
+    UPDATING the package later: npx expo prebuild again so the plugin
+    re-pins the engine to the version the package ships with (0.6.3+). An
+    ios/ folder committed to git is not re-wired by eas build on its own:
+    run prebuild and commit the result. Then clean before a LOCAL build
+    (Xcode: Product > Clean Build Folder); an incremental build can reuse
+    the previous engine's cached interface and fail with "has no member
+    '$storageWarning'". That error after an update means "clean", never
+    "edit the bridge". EAS Build starts clean.
 4.  Expo Go and any preview that never ran the plugin cannot load native
     modules: there the consent text, the call and recording fail with a
     clear error and the video view shows a placeholder. That is EXPECTED;
@@ -92,7 +100,8 @@ BARE REACT NATIVE (no Expo):
 2.  cd ios && pod install        (installs RN's own pods; CrowdPlay has none)
 3.  gem install xcodeproj --user-install   (one-time; wire.rb needs it
     and says so itself if missing)
-    ruby node_modules/crowdplaysdk/ios/wire.rb <YourProjectName>
+    ruby ../node_modules/crowdplaysdk/ios/wire.rb <YourProjectName>
+    (from ios/, where step 2 left you; wire.rb must run there)
     Idempotent. It: adds the CrowdPlaySDK binary Swift package to the Xcode
     project, copies the three native bridge files into the app target,
     creates/points the Swift bridging header at the React headers, raises
@@ -100,7 +109,10 @@ BARE REACT NATIVE (no Expo):
     sets SWIFT_ENABLE_EXPLICIT_MODULES = YES on the app target (React Native
     0.8x sets it to NO project-wide on Xcode 26, and with implicit modules
     the compiled engine's interface cannot be imported). Rerun it any time;
-    it never duplicates. Never undo that setting to fix an unrelated error.
+    it never duplicates, and after updating the package it re-pins the
+    engine to the version the package ships with (0.6.3+); then Product >
+    Clean Build Folder before building. Never undo that setting to fix an
+    unrelated error.
 4.  Info.plist: NSMicrophoneUsageDescription, NSCameraUsageDescription,
     UIBackgroundModes = [audio]. A missing usage string makes iOS kill
     the app at first mic/camera access (uncatchable).
@@ -324,22 +336,40 @@ Events (CrowdPlay.addListener):
                  // mic; crossTalk = loudspeaker leaking the far end into
                  // this mic (wear headphones); micPolicy = unexpected
                  // input device.
+  'storageWarning' { message: string | null }
+                 // 0.6.2+: non-null = the phone is low on storage: under
+                 // 2 GB free the recording is audio only, under 500 MB it
+                 // stopped. The call continues. The SDK shows nothing
+                 // itself; listening is optional. Kept out of 'warning' so
+                 // apps that render every warning do not show it.
 
-## Accessing recordings (no AWS, no SDK, plain HTTPS)
+## Checking sessions (no AWS, no SDK, plain HTTPS)
 
-The app key doubles as the data credential:
+The app key lists the sessions it recorded, metadata only:
   GET https://dashboard.crowdplay.ai/sessions            (x-liva-key header)
-  GET https://dashboard.crowdplay.ai/sessions/<id>/files (x-liva-key header)
-    -> [{path, bytes, url}]   // url = 1-hour presigned download
-deliverable/ holds the usable output: speaker-<name>.wav per participant
-(drift-corrected; all files play together with NO offset),
-conversation.wav, qc.json. raw/ is the untouched per-device capture.
-Humans use https://dashboard.crowdplay.ai directly (sign in, download).
+    -> [{sessionId, state ("uploading"|"ok"|"partial"|"failed"),
+         participants, participantMinutes, warnings, warningNotes,
+         uploadedAt}]
+A key sees only its own app's sessions; `state: "ok"` proves the
+integration works end to end. The dashboard shows the same list.
+
+Recordings NEVER leave CrowdPlay's storage. There is no download endpoint
+for builders: GET /sessions/<id>/files answers 403 to an app key and to
+dashboard accounts, and the dashboard has no download button. Do NOT
+build any feature that fetches, plays, shows, or analyses a recording
+after the session; the app has no way to obtain one. During the session
+the app can use the `caption` event (voice-AI transcript lines) and
+`snapshot()` (capture health).
 
 ## Facts, limits, troubleshooting
 
-- iOS 17+, React Native >= 0.71. Storage ~2 GB per participant-hour;
-  join refuses below 8 GB free.
+- iOS 17+, React Native >= 0.71. Storage ~6.8 GB per participant-hour with
+  video, ~0.5 GB audio-only (deleted as files upload; video waits for WiFi,
+  so on cellular it stays on the phone until then). The SDK never fills the
+  phone (0.6.2+): under 2 GB free the recording continues audio only, under
+  500 MB it stops, the call always continues, silently ('storageWarning'
+  says so if you listen). doctor() also checks free disk (8 GiB default);
+  join never refuses for storage.
 - Keep the screen awake during sessions (e.g. react-native-keep-awake or
   the idle-timer API); a locked phone suspends capture. Force-quitting
   pauses uploads until next launch (nothing lost).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crowdplaysdk",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "CrowdPlay lossless conversation capture for React Native (iOS). Studio-grade per-participant recording during live video calls, delivered to CrowdPlay automatically.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/index.ts

@@ -71,7 +71,7 @@ export interface CrowdPlayConfig {
 
 /** The CrowdPlay Terms of Use and Privacy Notice every participant accepts,
  * as a PDF. CrowdPlayConsentScreen links here; a custom consent UI must too. */
-export const CROWDPLAY_TERMS_URL = 'https://dashboard.crowdplay.ai/legal/terms.pdf';
+export const CROWDPLAY_TERMS_URL = 'https://www.crowdplay.ai/legal/consumer-terms';
 
 /** Proof the participant agreed. Produce it with CrowdPlayConsentScreen, or,
  * if you render your own consent UI, call CrowdPlay.consentText() to show the
@@ -180,6 +180,12 @@ export interface CrowdPlayEvents {
    * 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 };
+  /** This iPhone is running out of storage (D-148): under 2 GB free the
+   * recording continues audio only, under 500 MB it stops; the call always
+   * continues. `message` is null when storage is fine. The SDK shows
+   * nothing on screen; listening is optional. Separate from `warning` so
+   * apps that render every warning do not start showing it. */
+  storageWarning: { message: string | null };
   /** 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). */