[🐛] Push Preferences API - `channel_cid` Property Not Included in TypeScript Types

[CavalcanteLeo]

The JavaScript SDK documentation shows using client.upsertPushPreferences() but the actual SDK only provides client.setPushPreferences(). Additionally, the TypeScript type definition for PushPreference is incomplete - it's missing the channel_cid property that is required for channel-level push notification preferences.

Steps to reproduce

1. Install stream-chat-expo@8.12.0 (which includes stream-chat@9.27.2)
2. Follow the documentation at https://getstream.io/chat/docs/react-native/push_preferences/
3. Try to use the documented approach:

import { StreamChat } from 'stream-chat';

const client = new StreamChat('api_key');

// Documentation shows this:
await client.upsertPushPreferences({
  preferences: [
    {
      user_id: "user-1",
      channel_cid: "messaging:general",
      chat_level: "none",
    },
  ],
});

4. Get error: Property 'upsertPushPreferences' does not exist on type 'StreamChat'
5. Try using setPushPreferences instead (which exists in the SDK):

// SDK actually has this method:
await client.setPushPreferences([
  {
    channel_cid: 'messaging:my-channel-id', // TypeScript error here
    chatLevel: 'none',
  },
]);

6. TypeScript throws error: Object literal may only specify known properties, and 'channel_cid' does not exist in type 'PushPreference'.

Expected behavior

1. The documentation should show client.setPushPreferences() instead of client.upsertPushPreferences()
2. The documentation should show the method takes an array directly, not wrapped in an object: setPushPreferences(preferences: PushPreference[])
3. The PushPreference type should include the channel_cid property to support channel-level push notification preferences as documented in:
   • https://getstream.io/chat/docs/react-native/push_preferences/

Actual behavior

Issue 1: Wrong method name in documentation

The documentation shows client.upsertPushPreferences() but the SDK only has:

setPushPreferences(preferences: PushPreference[]): Promise<UpsertPushPreferencesResponse>

Issue 2: Wrong method signature in documentation

Documentation shows:

await client.upsertPushPreferences({
  preferences: [ /* ... */ ]
});

But the SDK actually expects:

await client.setPushPreferences([ /* ... */ ]);

Issue 3: Incomplete type definition

The current type definition in stream-chat@9.27.2/dist/types/types.d.ts:

export type PushPreference = {
    disabled?: boolean;
    chatLevel?: ChatLevelPushPreference;
    soundLevel?: 'default' | 'muted';
};

But the API actually accepts channel_cid and user_id for channel-specific and user-specific preferences. The type should be:

export type PushPreference = {
    disabled?: boolean;
    chatLevel?: ChatLevelPushPreference;
    soundLevel?: 'default' | 'muted';
    channel_cid?: string; // Missing - needed for channel-level preferences
    user_id?: string; // Missing - needed for server-side user specification
};

Note: There is a ChannelPushPreference type defined in the SDK, but it's only used in the response type UpsertPushPreferencesResponse, not as an input type for setPushPreferences.

Project Related Information

Customization

Click To Expand

// What the documentation shows (doesn't work):
await client.upsertPushPreferences({  // ❌ Method doesn't exist
  preferences: [
    {
      user_id: "user-1",
      channel_cid: "messaging:general",
      chat_level: "none",
    },
  ],
});

// What actually works (with TypeScript errors):
await client.setPushPreferences([  // ✅ Method exists
  {
    // @ts-expect-error - Properties not in type definition
    user_id: "user-1",
    channel_cid: "messaging:general",
    chatLevel: "none",  // Note: SDK uses camelCase, not snake_case
  },
]);

// Attempted service implementation:
import type { PushPreference, StreamChat } from 'stream-chat';

export type PushPreferenceLevel = 'all' | 'none' | 'mentions';

export async function setChannelPushPreference(
  client: StreamChat,
  channelCid: string,
  level: PushPreferenceLevel,
): Promise<void> {
  // Requires @ts-expect-error because channel_cid is not in PushPreference type
  await client.setPushPreferences([
    {
      // @ts-expect-error - Stream SDK type definitions for PushPreference are incomplete
      channel_cid: channelCid,
      chatLevel: level,
    },
  ]);
}

Offline support

• I have enabled offline support.
• The feature I'm having does not occur when offline support is disabled.

Environment

Click To Expand

package.json:

{
  "dependencies": {
    "stream-chat-expo": "^8.12.0"
  }
}

Installed versions:

• stream-chat-expo: 8.12.0
• stream-chat: 9.27.2 (peer dependency)

react-native info output:

System:
  OS: macOS 15.3
  CPU: (10) arm64 Apple M1 Pro
  Memory: 512.00 MB / 32.00 GB
  Shell: /bin/zsh
Binaries:
  Node: 22.21.1
  pnpm: 10.27.0
  Watchman: Not Found
SDKs:
  iOS SDK:
    Platforms: DriverKit 24.3, iOS 18.3, macOS 15.3, tvOS 18.3, visionOS 2.3, watchOS 11.3
  Android SDK: Not Found
IDEs:
  Android Studio: Not Found
  Xcode: 16.3/16D127
npmPackages:
  @react-native/babel-preset: Not Found
  expo: ^54.0.31 => 54.0.31
  react: 19.1.0 => 19.1.0
  react-native: ^0.81.5 => 0.81.5
npmGlobalPackages:
  *react-native*: Not Found

• Platform that you're experiencing the issue on:
  • iOS
  • Android
  • iOS but have not tested behavior on Android
  • Android but have not tested behavior on iOS
  • Both (issue is TypeScript-related, affects all platforms)
• stream-chat-react-native version you're using that has this issue:
  • stream-chat-expo@8.12.0 (includes stream-chat@9.27.2)
• Device/Emulator info:
  • I am using a physical device
  • OS version: iOS 26.3
  • Device/Emulator: iPhone Simulator

Additional context

Summary of Issues:

1. Documentation shows upsertPushPreferences but SDK only has setPushPreferences
2. Documentation shows wrong method signature (object wrapper vs direct array)
3. Documentation uses snake_case properties but SDK expects camelCase
4. TypeScript types are incomplete (missing channel_cid and user_id)

Screenshots

N/A - This is a TypeScript type definition issue.

[CavalcanteLeo]

@vishalnarkhede @khushal87 can u guys help me here?