Final Release v1.1.0 — ZCC, proxy, transcript params, individual video, Python asyncio/executor

.github/workflows/main.yml

@@ -196,14 +196,66 @@ jobs:
   # TEST JOBS - Test against pre-built artifacts
   # ============================================================================
 
+  # C++ unit tests — mock SDK replaces the binary; real headers downloaded via check-deps
+  test-cpp-linux:
+    name: Test C++ Core (Linux)
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Setup Node.js (for check-deps.js SDK download)
+      uses: actions/setup-node@v4
+      with:
+        node-version: '24.x'
+
+    - name: Install CMake
+      run: sudo apt-get install -y cmake
+
+    - name: Download SDK headers
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: node scripts/check-deps.js
+
+    - name: Build and run C++ tests
+      run: |
+        cmake -B build/tests -DRTMS_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug
+        cmake --build build/tests --target rtms_tests -j$(nproc)
+        cd build/tests && ctest --output-on-failure
+
+  test-cpp-macos:
+    name: Test C++ Core (macOS)
+    runs-on: macos-latest
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - name: Setup Node.js (for check-deps.js SDK download)
+      uses: actions/setup-node@v4
+      with:
+        node-version: '24.x'
+
+    - name: Download SDK headers
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      run: node scripts/check-deps.js
+
+    - name: Build and run C++ tests
+      run: |
+        cmake -B build/tests -DRTMS_BUILD_TESTS=ON -DCMAKE_BUILD_TYPE=Debug
+        cmake --build build/tests --target rtms_tests -j$(sysctl -n hw.logicalcpu)
+        cd build/tests && ctest --output-on-failure
+
   # Test Node.js SDK on Linux using pre-built prebuilds
   test-nodejs-linux:
     name: Test Node.js SDK on Linux (Node ${{ matrix.node-version }})
     runs-on: ubuntu-latest
     needs: [build-nodejs-linux]
     strategy:
       matrix:
-        node-version: ['20.3.0', '24.x']  # Test minimum (N-API v9) and latest LTS
+        node-version: ['22.x', '24.x']  # Test current LTS and latest LTS
       fail-fast: false  # Continue testing other versions if one fails
 
     steps:
@@ -224,8 +276,16 @@ jobs:
     - name: Install dependencies
       run: npm install
 
+    - name: Extract native prebuild
+      # install.js skips extraction when .git exists (dev mode detection).
+      # --force bypasses that check so the full install flow runs in CI.
+      run: node scripts/install.js --force
+
+    - name: Compile TypeScript
+      run: npx tsc
+
     - name: Run Node.js tests
-      run: npx jest tests/rtms.test.ts
+      run: npx jest tests/ts/rtms.test.ts tests/ts/rtms.wrapper.test.ts
 
   # Test Node.js SDK on macOS using pre-built prebuilds
   test-nodejs-macos:
@@ -251,8 +311,16 @@ jobs:
     - name: Install dependencies
       run: npm install
 
+    - name: Extract native prebuild
+      # Use install.js so macOS framework archives (.framework.tar.gz) are
+      # extracted after prebuild-install runs. --force bypasses dev-mode check.
+      run: node scripts/install.js --force
+
+    - name: Compile TypeScript
+      run: npx tsc
+
     - name: Run Node.js tests
-      run: npx jest tests/rtms.test.ts
+      run: npx jest tests/ts/rtms.test.ts tests/ts/rtms.wrapper.test.ts
 
   # Integration test: npm pack → install → load (validates end-user install flow)
   test-nodejs-integration-macos:
@@ -279,7 +347,7 @@ jobs:
       run: npm install
 
     - name: Run integration test (npm pack → install → load)
-      run: npx jest tests/pack-install.test.js --testTimeout=120000
+      run: npx jest tests/ts/pack-install.test.js --testTimeout=120000
 
   # Test Python SDK on Linux using pre-built wheels
   test-python-linux:
@@ -323,7 +391,7 @@ jobs:
       run: pip install pytest python-dotenv
 
     - name: Run Python tests
-      run: pytest tests/test_rtms.py -v
+      run: pytest tests/py/test_rtms.py -v
 
   # Test Python SDK on macOS using pre-built wheels
   test-python-macos:
@@ -367,7 +435,7 @@ jobs:
       run: pip install pytest python-dotenv
 
     - name: Run Python tests
-      run: pytest tests/test_rtms.py -v
+      run: pytest tests/py/test_rtms.py -v
 
   # ============================================================================
   # VERSION CHECK & PUBLISH TRIGGERS
@@ -377,7 +445,7 @@ jobs:
   check-version-change:
     name: Check for Version Changes
     runs-on: ubuntu-latest
-    needs: [test-nodejs-linux, test-nodejs-macos, test-nodejs-integration-macos, test-python-linux, test-python-macos]
+    needs: [test-cpp-linux, test-cpp-macos, test-nodejs-linux, test-nodejs-macos, test-nodejs-integration-macos, test-python-linux, test-python-macos]
     if: |
       success() &&
       github.event_name == 'push' &&
@@ -467,7 +535,7 @@ jobs:
   build-docs:
     name: Build Documentation
     runs-on: ubuntu-latest
-    needs: [test-nodejs-linux, test-nodejs-macos, test-python-linux, test-python-macos]
+    needs: [test-cpp-linux, test-cpp-macos, test-nodejs-linux, test-nodejs-macos, test-python-linux, test-python-macos]
     # Only run on main/master branches and if tests pass, or via workflow_dispatch
     if: |
       success() &&

.gitignore

@@ -12,6 +12,7 @@ __pycache__/
 ### Dev Only
 docs/*
 !docs/*.md
+spec.md
 
 ### Build
 dist

CHANGELOG.md

@@ -5,6 +5,75 @@ All notable changes to the Zoom RTMS SDK will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0] - 2026-04-15
+
+### Added
+
+#### ZCC (Zoom Contact Center) Support
+- **`engagement_id` in `join()`**: ZCC voice engagements identify sessions with an `engagement_id` instead of `meeting_uuid`; `join()` now accepts `engagement_id` as an alternative identifier (all bindings)
+- **ZCC event constants**: `EVENT_CONSUMER_ANSWERED`, `EVENT_CONSUMER_END`, `EVENT_USER_ANSWERED`, `EVENT_USER_END`, `EVENT_USER_HOLD`, `EVENT_USER_UNHOLD` exported as flat module-level constants in both Node.js and Python
+
+#### Transcript Configuration
+- **`TranscriptParams`**: New parameter class for configuring transcript streams (language hint, content type, language detection)
+- **`TranscriptLanguage` constants**: Full set of language constants (`ENGLISH`, `SPANISH`, `JAPANESE`, `CHINESE_SIMPLIFIED`, and many more) for skipping auto-detection (~30 s delay) by hinting the source language
+- **`setTranscriptParams()`/`set_transcript_params()`**: New method on Client to apply transcript configuration before joining (Node.js and Python)
+
+#### HTTP Proxy Support
+- **`setProxy()`/`set_proxy()`**: New method on Client for configuring HTTP and HTTPS proxies for RTMS connections (Node.js and Python)
+
+#### Individual Video Streams
+- **`subscribeVideo()`/`subscribe_video()`**: Subscribe or unsubscribe per-participant video when using `VIDEO_SINGLE_INDIVIDUAL_STREAM` mode
+- **`onParticipantVideo()`/`on_participant_video()`**: Callback fired when a participant's video turns on or off
+- **`onVideoSubscribed()`/`on_video_subscribed()`**: Callback fired with the result of each `subscribeVideo()` call
+- **`EVENT_PARTICIPANT_VIDEO_ON` / `EVENT_PARTICIPANT_VIDEO_OFF`**: Exported as flat module-level constants in both Node.js and Python
+
+#### Python — Concurrency & Scaling
+- **`EventLoop` / `EventLoopPool`**: New primitives for fine-grained control over polling threads; `EventLoop` wraps a dedicated background thread, `EventLoopPool` balances clients across a pool of threads
+- **`run_async()`**: Drop-in async replacement for `run()` using `asyncio.sleep()` between polls; composes naturally with aiohttp, FastAPI, asyncpg
+- **Executor dispatch**: `Client(executor=...)` and `run(executor=...)` / `run_async(executor=...)` dispatch data callbacks to a `concurrent.futures.Executor`, keeping the poll loop fast for CPU-bound or I/O-heavy callbacks
+- **Async callback detection**: Coroutine callbacks are detected automatically and scheduled on the running event loop via `asyncio.run_coroutine_threadsafe`
+- **GIL release in `poll()`**: The C++ poll call now releases the GIL, allowing other Python threads (e.g. the webhook HTTP server) to run freely during polling
+- **Context manager support**: `with rtms.Client() as client:` guarantees `leave()` is called on exit
+- **Lazy `alloc()` / thread affinity**: `Client()` construction is safe from any thread; the C SDK handle is allocated lazily on the EventLoop's own thread to satisfy the C SDK's thread-affinity constraint
+- **Snake_case aliases**: All `camelCase` methods have `snake_case` aliases (`on_audio_data`, `set_audio_params`, `subscribe_event`, etc.)
+
+#### Metadata & AI Interpreter Fields
+- **Full metadata fields**: `Metadata` now exposes `userId`, `userName`, `startTs`, `endTs` in both bindings
+- **`AiInterpreter` fields**: `Metadata` now exposes `aiInterpreter` with language pair targets from the AI language interpreter SDK feature
+
+#### Constants & Enums
+- **`IntEnum` for Python codec/rate/option types**: `AudioCodec`, `VideoCodec`, `AudioSampleRate`, `AudioChannel`, `DataOption` are now proper Python `IntEnum` values (comparisons with integers still work)
+- **`DataOption`**: Unified stream delivery mode enum covering both audio (`AUDIO_MIXED_STREAM`, `AUDIO_MULTI_STREAMS`) and video (`VIDEO_SINGLE_ACTIVE_STREAM`, `VIDEO_SINGLE_INDIVIDUAL_STREAM`, `VIDEO_MIXED_GALLERY_VIEW`) options — mirrors the C++ `MEDIA_DATA_OPTION` enum directly; `AudioDataOption` and `VideoDataOption` kept as backward-compat aliases
+- **Bidirectional param aliases**: All four param structs (`AudioParams`, `VideoParams`, `DeskshareParams`, `TranscriptParams`) now accept both `snake_case` and `camelCase` field names so existing code continues to work regardless of convention
+
+### Fixed
+
+- **`setOnParticipantVideo` missing auto-subscription**: Registering the participant video callback now automatically subscribes to `EVENT_PARTICIPANT_VIDEO_ON` and `EVENT_PARTICIPANT_VIDEO_OFF` events, matching the pattern used by `setOnUserUpdate` ([#108](https://github.com/zoom/rtms/issues/108))
+- **`config()` called before `open()`**: Video/audio/transcript params are now applied after the SDK session is open; calling `setVideoParams()` before `join()` no longer fails silently
+- **`AiInterpreter.target_size` out-of-bounds**: Guard against uninitialized or negative `target_size` values from the C SDK to prevent array over-reads
+- **`_run_executor` undefined**: Python's `_wrap_callback` referenced a module-level `_run_executor` that was never initialised; added the initialisation and wired the `executor` kwarg through `run()` / `run_async()`
+- **Redundant `RTMS_` prefix on C++ enum names**: All enum classes inside the `rtms` namespace drop the redundant prefix (`RTMS_EVENT_TYPE` → `EVENT_TYPE`, `RTMS_SESSION_STATE` → `SESSION_STATE`, etc.) — internal refactor, no public API change
+- **Spurious configure warnings on leave**: `updateMediaConfiguration` was called during callback teardown after the session was already closed, printing 4 `"Failed to update media configuration"` warnings on every clean leave; suppressed by tracking `sdk_opened_` state and calling `markClosed()` before stopping callbacks
+- **SIGSEGV on meeting end (Python)**: Race condition between the EventLoop thread (inside `poll()`) and the webhook thread (calling `release()`) caused a use-after-free crash with exit status 139; fixed with `poll_mutex_` — `poll()` releases the GIL before acquiring the mutex so neither thread can deadlock the other
+
+### Changed
+
+- **Protocol enums moved to `rtms.h`**: `EVENT_TYPE`, `ZCC_VOICE_EVENT_TYPE`, `SESSION_STATE`, `STREAM_STATE`, `MESSAGE_TYPE`, `STOP_REASON`, and `TRANSCRIPT_LANGUAGE` are now defined in the shared C++ header, making them automatically available to both Node.js and Python bindings
+
+### Documentation
+
+- **Node.js API reference**: New "Media Configuration" section covering `setVideoParams`, `setAudioParams`, `setDeskshareParams`, `setTranscriptParams` with codec/resolution/option constants; updated "Individual Video Streams" section
+- **Python API reference**: New "Media Callbacks", "Media Configuration", and "Individual Video Streams" sections; asyncio integration and executor dispatch examples; scaling strategy guide (4-layer progression from single-process to multi-process)
+- **ZCC product guide**: Added Zoom Contact Center as a supported product with webhook event names and `engagement_id` usage
+
+### Testing
+
+- **C++ unit tests** (70 tests): Full mock-SDK test suite covering Client lifecycle, session/user events, media callbacks, proxy, transcript params, individual video subscriptions, metadata construction, and `AiInterpreter` bounds guarding
+- **Python tests** (122 tests): Coverage for asyncio, executor dispatch, context manager, GIL release, ZCC `engagement_id` routing, individual video methods, transcript params, and all new constants
+- **Node.js wrapper tests** (98 tests): Integration tests against the real built ESM module covering all Client methods, callbacks, event subscriptions, constants, and utility functions
+- **Test reorganisation**: Tests moved from `tests/` root into `tests/ts/`, `tests/py/`, `tests/cpp/` subdirectories for clarity
+- **CI test path fixes**: CI/CD workflows updated to reference new test locations; C++ unit tests added as dedicated `test-cpp-linux` and `test-cpp-macos` jobs using the mock SDK (no real Zoom SDK binary required in CI)
+
 ## [1.0.3] - 2026-02-17
 
 ### Fixed

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.25.1)
-project(rtms VERSION 0.0.1 LANGUAGES CXX)
+project(rtms VERSION 1.1.0 LANGUAGES CXX)
 
 # ===== Build settings =====
 set(CMAKE_CXX_STANDARD 20)
@@ -57,7 +57,7 @@ set(RTMS_SEARCH_PATHS
 
 # ===== Locate library and headers =====
 find_path(RTMS_HEADER_DIR
-  NAMES rtms_csdk.h rtms_common.h
+  NAMES rtms_sdk.h rtms_common.h
   PATHS ${RTMS_INCLUDE_DIR} ${RTMS_SEARCH_PATHS}
   DOC "RTMS SDK headers"
 )
@@ -68,8 +68,13 @@ find_library(RTMS_LIBRARY
   DOC "RTMS SDK library"
 )
 
-# Error if not found
-if(NOT RTMS_LIBRARY)
+# ===== Test-only build option =====
+# When RTMS_BUILD_TESTS=ON the SDK binary is replaced by tests/mock_sdk.cpp,
+# so the real library is not required.
+option(RTMS_BUILD_TESTS "Build C++ unit tests using the mock SDK (no real SDK binary needed)" OFF)
+
+# Error if not found (skip library check for pure test builds)
+if(NOT RTMS_LIBRARY AND NOT RTMS_BUILD_TESTS)
   message(FATAL_ERROR "RTMS SDK library not found. Please install it or specify its location.")
 endif()
 
@@ -297,3 +302,41 @@ elseif(DEFINED SKBUILD_PROJECT_NAME)
 elseif(GO)
   message(STATUS "Go bindings not yet implemented")
 endif()
+
+# ============================================================================
+# C++ Unit Tests
+# Uses mock_sdk.cpp in place of the real Zoom SDK binary.
+# Configure with: cmake -B build/tests -DRTMS_BUILD_TESTS=ON
+# ============================================================================
+if(RTMS_BUILD_TESTS)
+  message(STATUS "Configuring C++ unit tests (mock SDK)")
+
+  include(FetchContent)
+  FetchContent_Declare(
+    Catch2
+    GIT_REPOSITORY https://github.com/catchorg/Catch2.git
+    GIT_TAG        v3.5.3
+    GIT_SHALLOW    TRUE
+  )
+  FetchContent_MakeAvailable(Catch2)
+
+  add_executable(rtms_tests
+    "${RTMS_SOURCE_DIR}/rtms.cpp"
+    "${CMAKE_SOURCE_DIR}/tests/cpp/mock_sdk.cpp"
+    "${CMAKE_SOURCE_DIR}/tests/cpp/test_cpp_wrapper.cpp"
+  )
+
+  target_include_directories(rtms_tests PRIVATE
+    ${RTMS_HEADER_DIR}
+    ${RTMS_SOURCE_DIR}
+    "${CMAKE_SOURCE_DIR}/tests/cpp"
+  )
+
+  target_compile_features(rtms_tests PRIVATE cxx_std_20)
+  target_link_libraries(rtms_tests PRIVATE Catch2::Catch2WithMain)
+
+  include(CTest)
+  list(APPEND CMAKE_MODULE_PATH ${catch2_SOURCE_DIR}/extras)
+  include(Catch)
+  catch_discover_tests(rtms_tests)
+endif()

Dockerfile

@@ -31,31 +31,40 @@ RUN apt update && apt install -y \
 # Install nvm (Node Version Manager) and Node.js
 ENV NVM_DIR="/root/.nvm"
 ENV NODE_VERSION="24"
-RUN curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash \
-    && . "$NVM_DIR/nvm.sh" \
-    && nvm install $NODE_VERSION \
-    && nvm alias default $NODE_VERSION \
-    && nvm use default \
-    && npm config set update-notifier false \
-    && ln -sf "$NVM_DIR/versions/node/$(nvm version default)" /usr/local/node
-
-# Add Node.js to PATH
 ENV PATH="/usr/local/node/bin:$PATH"
 
+RUN if [ "$TARGET" = "js" ] || [ "$TARGET" = "all" ]; then \
+        echo "Installing NVM..." \
+        && curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash \
+        && . "$NVM_DIR/nvm.sh" \
+        && nvm install $NODE_VERSION \
+        && nvm alias default $NODE_VERSION \
+        && nvm use default \
+        && npm config set update-notifier false \
+        && ln -sf "$NVM_DIR/versions/node/$(nvm version default)" /usr/local/node; \
+    fi
+
+
 # Install pyenv (Python Version Manager)
 ENV PYENV_ROOT="/root/.pyenv"
 ENV PYTHON_VERSION="3.13"
-RUN git clone https://github.com/pyenv/pyenv.git $PYENV_ROOT \
-    && cd $PYENV_ROOT && src/configure && make -C src \
-    && echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc \
-    && echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc \
-    && echo 'eval "$(pyenv init -)"' >> ~/.bashrc
+ENV PATH="$PYENV_ROOT/shims:$PYENV_ROOT/bin:$PATH"
+RUN if [ "$TARGET" = "py" ] || [ "$TARGET" = "all" ]; then \
+        echo "Installing pyenv version..." \ 
+        && git clone https://github.com/pyenv/pyenv.git $PYENV_ROOT \
+        && cd $PYENV_ROOT && src/configure && make -C src \
+        && echo 'export PYENV_ROOT="$HOME/.pyenv"' >> ~/.bashrc \
+        && echo 'export PATH="$PYENV_ROOT/bin:$PATH"' >> ~/.bashrc \
+        && echo 'eval "$(pyenv init -)"' >> ~/.bashrc; \
+    fi
 
 # Add pyenv to PATH and install Python
-ENV PATH="$PYENV_ROOT/shims:$PYENV_ROOT/bin:$PATH"
-RUN pyenv install $PYTHON_VERSION \
-    && pyenv global $PYTHON_VERSION \
-    && python --version
+RUN if [ "$TARGET" = "py" ] || [ "$TARGET" = "all" ]; then \
+        echo "Installing pyenv version..." \ 
+        && pyenv install $PYTHON_VERSION \
+        && pyenv global $PYTHON_VERSION \
+        && python --version; \
+    fi
 
 # Install Task (go-task)
 RUN sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin
@@ -66,10 +75,11 @@ RUN if [ "$TARGET" = "js" ] || [ "$TARGET" = "all" ]; then \
         npm install -g prebuild; \
     fi
 
+COPY requirements-dev.txt .
 RUN if [ "$TARGET" = "py" ] || [ "$TARGET" = "all" ]; then \
         echo "Installing Python build tools..." && \
         pip install --no-cache-dir --upgrade pip && \
-        pip install --no-cache-dir build "pybind11[global]" python-dotenv pdoc3 auditwheel twine; \
+        pip install --no-cache-dir -r requirements-dev.txt; \
     fi
 
 RUN if [ "$TARGET" = "go" ] || [ "$TARGET" = "all" ]; then \