feat(vc): add recording event support

[calendar-assistant]

Summary

Add support for consuming recording open events through lark-cli event consume. This PR covers recording started, recording transcript generated, and recording ended events, and outputs structured JSON that scripts and AI agents can process directly.

This change only supports Recording Bean events. Other recording sources are intentionally filtered out for now.

New EventKeys

Apps need to enable the following open platform events:

• vc.recording.recording_started_v1: recording started
• vc.recording.recording_transcript_generated_v1: recording transcript items generated
• vc.recording.recording_ended_v1: recording ended and uploaded successfully

CLI consume examples:

lark-cli event consume vc.recording.recording_started_v1
lark-cli event consume vc.recording.recording_transcript_generated_v1
lark-cli event consume vc.recording.recording_ended_v1

Permissions

These events are consumed with user authentication. The app needs:

• Auth type: user
• Scope: vc:recording:read

Output

This PR flattens the original event payload into stable fields so callers do not need to parse the raw open platform payload shape.

Recording started and recording ended events output:

• type
• event_id
• event_time
• unique_key
• source

Recording transcript generated events additionally output:

• transcript_items[].speaker_name
• transcript_items[].text
• transcript_items[].start_time
• transcript_items[].end_time
• transcript_items[].sentence_id

Limitations

Only Recording Bean events are supported in this PR. In the raw payload, this is represented as source = recording_bean.

• Events from non-Recording Bean sources are filtered and do not produce output.
• These events are documented as generated only when connected to Feishu software.
• recording_ended output does not expose object_type or object_id, so callers do not depend on non-core object metadata.
• Time fields are normalized to local-time RFC3339 strings through event_time, start_time, and end_time; raw millisecond timestamp fields are not exposed.

Changes

• Register the three recording open event EventKeys.
• Add typed schemas and processors for the three events.
• Support the recording event subscription lifecycle before and after consume.
• Preserve malformed payloads as raw passthrough so one bad payload does not break the consume flow.
• Add unit tests for registration, permissions, schema, payload transformation, source filtering, field trimming, malformed payload fallback, and subscription lifecycle behavior.

Test Plan

• Unit tests pass: make unit-test
• Manual local verification confirms the lark-cli event consume <EventKey> recording event flow works as expected

Related Issues

• None

Summary by CodeRabbit

Release Notes

• New Features

  • Added support for video conferencing recording lifecycle events, including recording started, ended, and transcript generated.
  • Recording event data is automatically processed and transformed into a structured output format.

• Tests

  • Added comprehensive test coverage for recording event processing, registration, data transformation, and API lifecycle management.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 5da8e920-a3e6-47f0-9f20-210b06154da1

📥 Commits

Reviewing files that changed from the base of the PR and between 7fdf558 and 3e9dd24.

📒 Files selected for processing (5)

• events/vc/recording_ended.go
• events/vc/recording_started.go
• events/vc/recording_test.go
• events/vc/recording_transcript_generated.go
• events/vc/register.go

---

📝 Walkthrough

Walkthrough

This PR adds three new VC event processors for recording lifecycle events: recording_started, recording_transcript_generated, and recording_ended. Each processor parses an envelope-structured payload, filters to recording_bean-sourced events, flattens the schema, converts millisecond timestamps to local RFC3339 format, and marshals the output. All three processors are registered as event key definitions with consistent auth and scope requirements, and comprehensive tests validate registration, processing logic, timestamp conversion, field mapping, filtering, and subscription lifecycle.

Changes

VC Recording Event Processors

Layer / File(s)	Summary
Recording transcript-generated event processor events/vc/recording_transcript_generated.go	Defines VCRecordingTranscriptGeneratedOutput and VCRecordingTranscriptItemOutput DTOs; unmarshals envelope structure from raw JSON; transforms transcript items with millisecond-to-RFC3339 timestamp conversion; implements custom UnmarshalJSON to tolerate null and numeric timestamp fields; filters to recording_bean-sourced events.
Recording ended event processor events/vc/recording_ended.go	Defines VCRecordingEndedOutput DTO and envelope structs; parses envelope and filters to recording_bean events; constructs flattened output with envelope header type, event metadata, and timestamp conversion; returns original payload on parse failure or nil for non-matching sources.
Recording started event processor events/vc/recording_started.go	Complete processor for recording_started_v1: defines VCRecordingStartedOutput DTO and envelope structures; parses payload with fallback to original on failure; filters to recording_bean events; transforms create_time (milliseconds) to local RFC3339 event_time; includes event ID, unique key, and source.
Event registration and wiring events/vc/register.go	Adds event type constants and subscription/unsubscription API paths; extends Keys() with three event.KeyDefinition entries wiring each processor to its output schema, processing function, auth type (user), scope (vc:recording:read), required console event, and PreConsume subscription configuration.
Comprehensive test coverage events/vc/recording_test.go	Tests registration with correct schema/auth/scope configuration; validates processor output correctness (type, IDs, timestamp conversion); verifies transcript item mapping and JSON shape constraints (required fields present, forbidden fields omitted); confirms object metadata and raw timestamp fields are dropped; ensures non-recording_bean events are filtered and malformed payloads are passed through; validates PreConsume subscription lifecycle with API mocking and request body assertions.

Sequence Diagram

sequenceDiagram
  participant RawEvent
  participant Processor
  participant Envelope
  participant Output
  RawEvent->>Processor: raw payload (JSON)
  Processor->>Envelope: unmarshal envelope structure
  alt envelope parsed successfully
    Envelope->>Processor: header + event body
    alt source == "recording_bean"
      Processor->>Output: flatten & convert timestamps
      Output->>Processor: flattened DTO
      Processor->>RawEvent: marshal & return output
    else non-recording_bean source
      Processor->>RawEvent: return nil (drop event)
    end
  else envelope parse fails
    Processor->>RawEvent: return original payload bytes
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

domain/vc, feature

Suggested reviewers

• zhaoleibd
• zhangjun-bytedance

Poem

🐰 Three recording sprites take flight,
Envelopes parsed with care and might,
Timestamps bloom in RFC light,
Transcripts flow, events ring bright—
The VC stage shines ever right! 🎬

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/recording_event

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

❌ Patch coverage is 84.97110% with 26 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.94%. Comparing base (cc416a4) to head (3e9dd24).
⚠️ Report is 121 commits behind head on main.

Files with missing lines	Patch %	Lines
events/vc/recording_transcript_generated.go	75.75%	11 Missing and 5 partials ⚠️
events/vc/recording_ended.go	83.87%	3 Missing and 2 partials ⚠️
events/vc/recording_started.go	83.87%	3 Missing and 2 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1369      +/-   ##
==========================================
+ Coverage   71.47%   71.94%   +0.46%     
==========================================
  Files         688      694       +6     
  Lines       65483    65802     +319     
==========================================
+ Hits        46807    47338     +531     
+ Misses      15031    14808     -223     
- Partials     3645     3656      +11     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@3e9dd245c85dae856b6c78f66f3ffece89de9a77

🧩 Skill update

npx skills add larksuite/cli#feat/recording_event -y -g