Skip to content

feat: add task event consumer#1510

Merged
tengchengwei merged 4 commits into
larksuite:mainfrom
ILUO:feat/task-event-consume
Jun 24, 2026
Merged

feat: add task event consumer#1510
tengchengwei merged 4 commits into
larksuite:mainfrom
ILUO:feat/task-event-consume

Conversation

@ILUO

@ILUO ILUO commented Jun 17, 2026

Copy link
Copy Markdown
Contributor

Summary

Add the Lark Task v2 event consumer for task.task.update_user_access_v2 using the existing EventKey registry, bus daemon, and schema pipeline. This also removes the legacy task +subscribe-event shortcut so Task event subscription is exposed through the unified event consume flow only.

Changes

  • Register the new Task EventKey task.task.update_user_access_v2.
  • Use Native V2 envelope output with fields under .event and schema metadata for .event.task_guid, .event.event_types, and .header.event_id.
  • Add local Task event schema metadata, including event_types enum values and task_guid format.
  • Add PreConsume subscription logic for POST /open-apis/task/v2/task_v2/task_subscription?user_id_type=open_id.
  • Preserve typed API errors and wrap untyped subscription failures as typed network errors.
  • Remove the legacy task +subscribe-event shortcut, tests, and skill reference docs.
  • Update lark-event and lark-task docs to use event consume task.task.update_user_access_v2.

Test Plan

  • Targeted regression: go test ./shortcuts/task ./events/... ./cmd/event/... -count=1
  • Event package regression: go test ./events/task -count=1
  • Manual local verification: go run . task --help no longer shows +subscribe-event
  • Manual local verification: go run . event list --json | grep task.task.update_user_access_v2
  • Manual local verification: go run . event schema task.task.update_user_access_v2 --json
  • Race/unit coverage split around local npx availability: non-shortcuts/apps packages pass without shim; shortcuts/apps passes with a temporary npx shim

Related Issues

  • None

Summary by CodeRabbit

  • New Features

    • Added support for task.task.update_user_access_v2 event type for real-time task access update consumption
  • Documentation

    • Added comprehensive documentation for task event subscription, configuration, and usage patterns
  • Deprecated

    • Migrated task event subscription from shortcuts to the event system; old shortcut method no longer available

@coderabbitai

coderabbitai Bot commented Jun 17, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 14111386-0e42-4087-9318-0c027698c17d

📥 Commits

Reviewing files that changed from the base of the PR and between 5b94b12 and b4dc062.

📒 Files selected for processing (1)
  • events/task/preconsume_test.go
🚧 Files skipped from review as they are similar to previous changes (1)
  • events/task/preconsume_test.go

📝 Walkthrough

Walkthrough

Adds the task.task.update_user_access_v2 event to the Lark CLI with a native V2 schema payload struct, a pre-consume hook that subscribes to the task API before listening, registry wiring into the global event system, CLI integration tests, and skill documentation. Concurrently removes the deprecated SubscribeTaskEvent shortcut, which is superseded by the new event consumption workflow.

Changes

Task Event: task.task.update_user_access_v2

Layer / File(s) Summary
Payload struct and commit types
events/task/native.go
TaskUpdateUserAccessV2Data struct with EventTypes and TaskGUID fields; taskUpdateUserAccessCommitTypes slice enumerates supported task update event types.
Event key registration and metadata
events/task/register.go, events/task/register_test.go
Keys() exports a single event.KeyDefinition for task.task.update_user_access_v2 with schema binding, task:task:read scope, user/bot auth types, pre-consume hook, and single-consumer flag; tests validate metadata, schema JSON annotations (task_guid format and event_types enum), and event.Lookup behavior.
Pre-consume subscription hook
events/task/preconsume.go
taskSubscriptionPreConsume POSTs to the task subscription endpoint at startup; returns API validation errors directly or wraps untyped network errors as network-transport typed errors.
Pre-consume hook unit tests
events/task/preconsume_test.go
Four tests with stubAPIClient verify correct POST, nil-runtime error handling, API error propagation, and untyped error wrapping while preserving errors.Is identity.
Global registry wiring and CLI output tests
events/register.go, cmd/event/list_test.go, cmd/event/schema_test.go
task.Keys() added to registry initialization; TestRunList_TextOutput and TestRunList_JSONOutput assert key presence with single_consumer: true; TestRunSchema_TaskUpdateUserAccessJSON validates jq_root_path, single_consumer, field formats, and enum values.
Skill documentation
skills/lark-event/SKILL.md, skills/lark-event/references/lark-event-task.md
New lark-event-task.md reference documents subscription lifecycle, V2 envelope shape, commit types, required scopes/auth, single-consumer constraints, and CLI examples; lark-event SKILL.md updated to mention Task updates and add Task topic index.
Removal of deprecated SubscribeTaskEvent
shortcuts/task/shortcuts.go, shortcuts/task/task_subscribe_event.go, skills/lark-task/SKILL.md
SubscribeTaskEvent shortcut removed from task shortcuts list; implementation file deleted; shortcut no longer appears in lark-task documentation. Workflow superseded by event consume with pre-consume hook.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

  • larksuite/cli#377: Implements the task +subscribe-event shortcut which manually invokes the same task subscription POST that the new taskSubscriptionPreConsume hook now performs automatically.
  • larksuite/cli#1231: Refactors shortcuts/task/task_subscribe_event.go error handling to use typed errors, directly overlapping with the shortcut code removed in this PR.

Suggested labels

feature

Poem

🐇 A task event hops into the queue,
With a POST that subscribes before consume,
task_guid and commit types in view,
Single consumer, no room for two—
The rabbit registers, tests pass, docs bloom! 🌸

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 7.14% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title 'feat: add task event consumer' accurately describes the main change—adding an event consumer for Lark Task v2 events—and is specific and clear.
Description check ✅ Passed The description follows the template structure with Summary, Changes, Test Plan, and Related Issues sections. All critical information is provided, though the Related Issues section correctly states 'None'.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

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

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

@github-actions github-actions Bot added domain/task PR touches the task domain size/L Large or sensitive change across domains or core paths labels Jun 17, 2026
@ILUO

ILUO commented Jun 17, 2026 via email

Copy link
Copy Markdown
Contributor Author

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🧹 Nitpick comments (1)
skills/lark-task/references/lark-task-subscribe-event.md (1)

105-106: 💤 Low value

Optional: Reduce repetition of "wants to" phrasing in workflow steps.

Lines 105–106 use "wants to" twice in close succession. Consider rewording for variety:

  • Line 105: "If the user wants to listen now" → "If listening immediately is the goal" or "To start listening now"
  • Line 106: "If the user only wants to register the subscription" → "To only register the subscription"

This improves readability without changing meaning.

📝 Suggested revision
 1. Confirm whether the user wants to subscribe with `user` identity or `bot` identity.
-2. If the user wants to listen now, execute `lark-cli event consume task.task.update_user_access_v2 --as <identity>`.
-3. If the user only wants to register the subscription, execute `lark-cli task +subscribe-event --as <identity>`.
+2. To start listening now, execute `lark-cli event consume task.task.update_user_access_v2 --as <identity>`.
+3. To only register the subscription, execute `lark-cli task +subscribe-event --as <identity>`.
 4. Report whether the subscription or consumer startup succeeded, and clarify which identity it applies to.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@skills/lark-task/references/lark-task-subscribe-event.md` around lines 105 -
106, The workflow steps contain repetitive "wants to" phrasing that reduces
readability. Reword the two conditional statements in the event subscription
instructions to eliminate this repetition. For the step about listening
immediately (currently "If the user wants to listen now"), revise to use a more
direct phrasing like "To start listening now" or "If listening immediately is
the goal". For the step about registration (currently "If the user only wants to
register the subscription"), change to "To only register the subscription".
These rewording maintain the meaning while improving clarity and variety in the
documentation flow.

Source: Linters/SAST tools

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@events/task/preconsume_test.go`:
- Around line 58-70: The TestTaskSubscriptionPreConsumeRequiresRuntime test
function only asserts the error category but does not validate the subtype and
param fields of the typed error returned by taskSubscriptionPreConsume. After
the existing category assertion on line 64, add additional error assertions to
check the p.Subtype field against the expected subtype value and verify the
p.Param field if applicable to ensure error classification regressions are
caught according to the coding guidelines.

In `@events/task/preconsume.go`:
- Around line 21-23: The error handling in the rt.CallAPI call needs to be
updated to preserve the typed error contract. Instead of returning raw errors
directly, check if the returned error from rt.CallAPI is already a typed error
using the appropriate type assertion or check, and if it is, pass it through
unchanged. For untyped errors, wrap them using errs.NewNetworkError with
errs.SubtypeNetworkTransport as the subtype, and chain the original error using
the .WithCause method to preserve the underlying error information before
returning.

In `@skills/lark-event/references/lark-event-task.md`:
- Line 34: The task_subscribe_event.go file currently only implements a POST
endpoint for subscribing to task events at
/open-apis/task/v2/task_v2/task_subscription with no corresponding DELETE
endpoint for unsubscribing. Add a DELETE endpoint to task_subscribe_event.go
that mirrors the unsubscribe pattern used in the peer event handlers
(whiteboard, vc, minutes, mail implementations) to enable proper subscription
cleanup on graceful shutdown. This will prevent repeated subscription calls when
the consumer is re-run.

---

Nitpick comments:
In `@skills/lark-task/references/lark-task-subscribe-event.md`:
- Around line 105-106: The workflow steps contain repetitive "wants to" phrasing
that reduces readability. Reword the two conditional statements in the event
subscription instructions to eliminate this repetition. For the step about
listening immediately (currently "If the user wants to listen now"), revise to
use a more direct phrasing like "To start listening now" or "If listening
immediately is the goal". For the step about registration (currently "If the
user only wants to register the subscription"), change to "To only register the
subscription". These rewording maintain the meaning while improving clarity and
variety in the documentation flow.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 845a6276-f14d-4d34-857a-a230ea7b7e92

📥 Commits

Reviewing files that changed from the base of the PR and between 1f2164c and 6190efc.

📒 Files selected for processing (12)
  • cmd/event/list_test.go
  • cmd/event/schema_test.go
  • events/register.go
  • events/task/native.go
  • events/task/preconsume.go
  • events/task/preconsume_test.go
  • events/task/register.go
  • events/task/register_test.go
  • skills/lark-event/SKILL.md
  • skills/lark-event/references/lark-event-task.md
  • skills/lark-task/SKILL.md
  • skills/lark-task/references/lark-task-subscribe-event.md

Comment thread events/task/preconsume_test.go
Comment thread events/task/preconsume.go
Comment thread skills/lark-event/references/lark-event-task.md

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
events/task/preconsume_test.go (1)

75-83: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Strengthen pass-through API error assertions (metadata + identity).

This error-path test currently checks only errors.Is. A wrapped/reclassified error could still pass. Assert typed metadata via errs.ProblemOf and direct identity (err == wantErr) to lock the passthrough contract.

Suggested patch
 func TestTaskSubscriptionPreConsumePassesThroughAPIError(t *testing.T) {
 	wantErr := errs.NewValidationError(errs.SubtypeFailedPrecondition, "subscription already exists")
 	rt := &stubAPIClient{err: wantErr}

 	_, err := taskSubscriptionPreConsume(context.Background(), rt, nil)
+	if err != wantErr {
+		t.Fatalf("err identity changed: got %T %v, want original %T %v", err, err, wantErr, wantErr)
+	}
 	if !errors.Is(err, wantErr) {
 		t.Fatalf("err = %v, want %v", err, wantErr)
 	}
+	p, ok := errs.ProblemOf(err)
+	if !ok {
+		t.Fatalf("expected typed error, got %T: %v", err, err)
+	}
+	if p.Category != errs.CategoryValidation {
+		t.Errorf("category = %s, want %s", p.Category, errs.CategoryValidation)
+	}
+	if p.Subtype != errs.SubtypeFailedPrecondition {
+		t.Errorf("subtype = %s, want %s", p.Subtype, errs.SubtypeFailedPrecondition)
+	}
 }

As per coding guidelines: **/*_test.go: Error-path tests must assert typed metadata via errs.ProblemOf (category / subtype / param) and cause preservation, not message substrings alone.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@events/task/preconsume_test.go` around lines 75 - 83, The test
TestTaskSubscriptionPreConsumePassesThroughAPIError needs stronger assertions to
verify the error passed through from taskSubscriptionPreConsume is not wrapped
or reclassified. In addition to the existing errors.Is check, add assertions
using errs.ProblemOf to verify the typed metadata of the error (ensuring the
category and subtype match the original wantErr), and consider adding a direct
identity check with err == wantErr to enforce that the exact error object is
returned without modification. This ensures the passthrough contract is properly
locked.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@events/task/preconsume_test.go`:
- Around line 75-83: The test
TestTaskSubscriptionPreConsumePassesThroughAPIError needs stronger assertions to
verify the error passed through from taskSubscriptionPreConsume is not wrapped
or reclassified. In addition to the existing errors.Is check, add assertions
using errs.ProblemOf to verify the typed metadata of the error (ensuring the
category and subtype match the original wantErr), and consider adding a direct
identity check with err == wantErr to enforce that the exact error object is
returned without modification. This ensures the passthrough contract is properly
locked.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: bf8783b0-20b2-4240-a874-d181bb76e559

📥 Commits

Reviewing files that changed from the base of the PR and between 6190efc and c353e62.

📒 Files selected for processing (3)
  • events/task/preconsume.go
  • events/task/preconsume_test.go
  • skills/lark-task/references/lark-task-subscribe-event.md
✅ Files skipped from review due to trivial changes (1)
  • skills/lark-task/references/lark-task-subscribe-event.md
🚧 Files skipped from review as they are similar to previous changes (1)
  • events/task/preconsume.go

@github-actions

Copy link
Copy Markdown

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add ILUO/cli#feat/task-event-consume -y -g

@tengchengwei tengchengwei merged commit b46e60c into larksuite:main Jun 24, 2026
19 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

domain/task PR touches the task domain size/L Large or sensitive change across domains or core paths

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants