feat(node-sdk): surface app data change callbacks and the update guard

[tylerhawkes]

Stack

Merge bottom-up — each PR is based on its parent below.
Android is the priority path: #4019 → #4011 → #4012 → #4016.

• feat(xmtp_db): add IntentState::Superseded for abandoned guarded intents #4019 db — IntentState::Superseded (base: main)
  • feat(xmtp_mls): report app data changes and guard updates against clobbering #4011 xmtp_mls — app-data change callbacks + compare-and-swap guard
    • feat(bindings_mobile): expose the app data change callback and update guard #4012 bindings/mobile · Android path
      • feat(android-sdk): surface app data change callbacks and the update guard #4016 sdks/android · Android path
      • feat(ios-sdk): surface app data change callbacks and the update guard #4015 sdks/ios
    • feat(bindings_node): expose the app data change callback and update guard #4013 bindings/node
      • feat(node-sdk): surface app data change callbacks and the update guard #4017 sdks/js/node-sdk ← this PR
    • feat(bindings_wasm): expose the app data change callback and update guard #4014 bindings/wasm

Already merged: #4018 (proto regen). Related follow-up, independent of this stack: #4020.

---

Surfaces the unstable app-data change callback on the node SDK.

Public surface

const client = await Client.create(signer, {
  unstableChangeCallbacks: {
    appData: async (change) => { /* merge and republish */ },
  },
});

The registry is an optional object rather than a bare callback, so handlers for the other mutable fields land as further optional properties.

The binding-level UnstableChangeCallbacks is only constructed when a handler is actually supplied — an empty registry would make the core snapshot app_data on every processed message for no benefit.

AppDataChange is re-exported from the SDK root so callers can type their handler.

Not included

browser-sdk. It runs the client in a Web Worker and passes options across a structured clone, which cannot carry a function; wiring it needs a worker→main reverse-RPC that does not exist yet, plus a decision on whether awaiting the main thread from inside the worker's processing loop is an acceptable stall risk. See #4014.

🤖 Generated with Claude Code

https://claude.ai/code/session_01AdY7WKkNbJmdzpmUWvW1my

Note

Surface app data change callbacks and compare-and-swap update guard in the Node SDK

• Adds UnstableChangeCallbacks to the Node bindings, letting JS callers register an async appData change callback at client creation time via OtherOptions.unstableChangeCallbacks.appData.
• Introduces AppDataChange (carrying group_id, old_value, new_value) as a JS-visible type exported from the SDK.
• Bridges JS callbacks to the core client via a ThreadsafeFunction; callback failures are logged and do not abort message processing.
• Extends Group.updateAppData and UpdateAppDataOptions to accept an optional expectedValue/expectedAppData for compare-and-swap semantics on opaque app data.

📊 Macroscope summarized db23929. 4 files reviewed, 0 issues evaluated, 0 issues filtered, 0 comments posted

🗂️ Filtered Issues

No issues evaluated.

[claude]

Claude finished @tylerhawkes's task —— View job

---

PR Review - App Data Change Callbacks

Progress

• Read changed files
• Analyze implementation
• Provide review feedback

---

Review Date: August 19, 2026, 8:48 PM UTC

This PR cleanly surfaces the app data change callback mechanism from the Node bindings to the SDK layer. The implementation is well-structured and follows established patterns. I have a few observations:

✅ Strengths

1. Good API design - Using an object for unstableChangeCallbacks rather than a bare callback makes the API extensible for future mutable fields (name, description, etc.)

2. Performance conscious - The conditional construction of UnstableChangeCallbacks only when a handler is actually provided (sdks/js/node-sdk/src/utils/createClient.ts:95-97) avoids unnecessary overhead

3. Clear documentation - The JSDoc on updateAppData and unstableChangeCallbacks clearly explains the compare-and-swap semantics and callback behavior

4. Error handling - The bindings layer properly catches and logs callback failures without derailing message processing (bindings/node/src/client/change_callbacks.rs:91-98)

🔍 Observations

1. Unresolved review comment - The macroscopeapp review identified an issue with undefined handling for expectedAppData (sdks/js/node-sdk/src/Group.ts:104). When a caller expects appData to be unset and passes undefined, it's indistinguishable from "no guard" (last-writer-wins), which could silently overwrite a concurrent value. Consider accepting null as a distinct sentinel for "expect unset".

2. Test coverage - Only basic updateAppData usage is tested (sdks/js/node-sdk/test/Group.test.ts:300). Consider adding tests for:

   • The expectedAppData compare-and-swap parameter (both success and conflict cases)
   • The unstableChangeCallbacks.appData callback being invoked
   • Callback error handling

3. Type export location - AppDataChange is exported from the SDK root (sdks/js/node-sdk/src/index.ts:21), which is good for discoverability

---

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR introduces new user-facing behavior: a callback mechanism for app data changes and a compare-and-swap parameter for updateAppData. While well-scoped and additive, new feature capabilities warrant human review even when the author owns the affected files.

No code changes detected at db23929. Prior analysis still applies.

^{You can add or adjust custom eligibility rules. Learn more.}

Dismissing prior approval to re-evaluate 1e34c2a

[macroscopeapp]

🟠 High src/Group.ts:104

updateAppData cannot detect a conflict when the caller expects appData to be unset: passing undefined omits expectedValue, so a concurrent value can be silently overwritten. Accept a distinct unset sentinel such as null and forward it to the binding as expectedValue.

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @sdks/js/node-sdk/src/Group.ts around line 104:

`updateAppData` cannot detect a conflict when the caller expects `appData` to be unset: passing `undefined` omits `expectedValue`, so a concurrent value can be silently overwritten. Accept a distinct unset sentinel such as `null` and forward it to the binding as `expectedValue`.