feat(client): support custom_set and custom_unset in batch channel update

[kanat]

Ticket

CHA-3618

Problem

PUT /channels/batch gained two root-level fields in GetStream/chat#15840 (merged 2026-09-01, first released in v237.13.0): custom_set and custom_unset. They patch individual keys of a channel's custom object, unlike data.custom, which replaces the whole object — and since a channel's display name lives inside custom, a full replace that omits name deletes the channel name. UpdateChannelsBatchOptions carries only operation, filter, members and data, so this SDK cannot send them.

Solution

UpdateChannelsBatchOptions gets custom_set?: Record<string, unknown> (the same value type as BatchChannelDataUpdate.custom) and custom_unset?: string[]. custom_set merges its keys into each matched channel's existing custom, custom_unset deletes its keys, and every other custom key is left untouched.

Both sit at the request root, next to operation and filter, not inside data. That placement is load-bearing: on the v1 routes data is decoded through an extra-fields sink, so data: { custom_set: … } is already a valid payload today meaning "replace custom with a key literally named custom_set". The request root has no sink.

ChannelBatchUpdater keeps one operation-aligned helper, updateData:

• Existing updateData(filter, data) calls remain source- and runtime-compatible.
• updateData(filter, { custom_set, custom_unset }) sends a custom-only patch without an undefined placeholder or a data key.
• updateData(filter, { data, custom_set, custom_unset }) combines channel data and custom-key changes in one request.

The exported ChannelBatchDataUpdateOptions type names the options-object form. The client normalizes only the legacy form into the root-level request shape; the wire format is unchanged.

Validation stays server-side: the backend owns the rules for which field combinations it rejects (patch together with data.custom, a patch on any operation other than updateData, the same or overlapping key in both, empty dot-path segments, whitespace in keys — all 400s). The SDK only carries the fields.

How to verify

1. yarn vitest run test/unit/channel_batch_update.test.ts — 5 tests, no API credentials needed. They pin both JSON key names and their placement at the request root, the legacy updateData(filter, data) request, the custom-only options form with no data key, and the combined form.
2. yarn types, yarn run-types-gen, yarn lint, and yarn build pass.
3. Full yarn vitest run passes: 80 files, 3151 tests passed, 1 skipped.

[mogita]

The union type lets a mixed literal compile, and the mixed call then silently drops the channel-data fields.

updater.updateData(filter, { frozen: true, custom_set: { group: 'new' } }); // no type error

TypeScript relaxes the excess-property check across a union: frozen is known to BatchChannelDataUpdate, custom_set to ChannelBatchDataUpdateOptions, so the literal passes (checked with tsc --strict). At runtime isChannelBatchDataUpdateOptions sees custom_set and returns true, so the whole object is spread at the request root and frozen goes out as a root-level key. The request root has no extra-fields sink, so the server ignores it: the caller gets a task_id back and frozen never applies.

Two real overloads on updateData, one per argument shape, reject that literal at compile time (TS2769) while every valid call in the tests still type-checks.

[kanat]

Fixed in e8a082cb — restored the two public overloads and added a declaration test that rejects the mixed literal.

[mogita]

[Must Fix] ...options is spread after operation and filter, so a caller's own keys win at runtime.

ChannelBatchDataUpdateOptions is all-optional, so a non-fresh object needs only one matching key to satisfy the weak-type check, and excess-property checking does not apply to it:

const o = { operation: 'hide' as const, filter: oldFilter, data: { frozen: true } };
updater.updateData(newFilter, o); // typechecks, sends operation: "hide" with oldFilter

That is the shape a refactor from client.updateChannelsBatch(options) to this helper produces, and BatchUpdateOperation includes hide and removeMembers, so a data update can silently become a visibility or membership change against the wrong filter. Before this PR the second argument was always nested under data, so a stray key could not reach the request root.

Pick the three known keys instead of spreading:

const { data, custom_set, custom_unset } = isChannelBatchDataUpdateOptions(update)
  ? update
  : { data: update };

return await this.client.updateChannelsBatch({
  operation: 'updateData',
  filter,
  ...(data && { data }),
  ...(custom_set && { custom_set }),
  ...(custom_unset && { custom_unset }),
});

Worth one test that passes operation and filter inside the options object and asserts the request still carries updateData and the filter argument, since none of the five current tests can fail on this.

[kanat]

Fixed in 5512b213 — the helper now copies only data, custom_set, and custom_unset, with a regression test for conflicting operation and filter fields.

[stream-ci-bot]

🎉 This PR is included in version 9.53.0 🎉

The release is available on:

• GitHub release
• npm package (@latest dist-tag)

Your semantic-release bot 📦🚀

[stream-ci-bot]

🎉 This PR is included in version 10.0.0-rc.12 🎉

The release is available on:

• GitHub release
• npm package (@rc dist-tag)

Your semantic-release bot 📦🚀