@tencent-rtc/mcp 1.4.6 → 1.6.0-beta.1

package/resource/knowledge/livekit/core-sdk/api-reference/ios/BattleStore.md

@@ -0,0 +1,309 @@
+## Introduction
+
+PK feature enables real-time interactive battles between hosts. `BattleStore` provides a comprehensive set of APIs to manage the entire PK lifecycle.
+
+> **Important: **
+>
+
+> Always use the factory method **create(liveID:)** with a valid live room ID to create a `BattleStore` instance. Do not attempt to initialize directly.
+>
+
+> **Note: **
+>
+
+> PK state updates are delivered through the **state** publisher. Subscribe to it to receive real-time updates about PK information, participating users, and scores.
+>
+
+> **Warning: **
+>
+
+> If a PK request does not receive a response within the specified timeout, a timeout event will be triggered. Always handle timeout scenarios in the UI.
+>
+
+## Features
+- **PK Request Management**: Hosts can initiate PK requests, and invitees can accept or reject.
+
+- **State Management**: Real-time tracking of PK information, participating users, and scores.
+
+- **Event-Driven Architecture**: Provides complete PK event callbacks.
+
+- **Timeout Handling**: Built-in timeout mechanism for PK requests.
+
+## Subscribable Data
+
+**BattleState** fields are described below:
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|currentBattleInfo|BattleInfo?|Current PK information.|
+|battleUsers|[SeatUserInfo]|PK user list.|
+|battleScore|[String:UInt]|PK score mapping.|
+
+## API List
+
+|**Function**|**Description**|
+|---------|---------|
+|create|Create BattleStore instance.|
+|battleEventPublisher|PK event publisher.|
+|requestBattle|Initiate PK request.|
+|cancelBattleRequest|Cancel PK request.|
+|acceptBattle|Accept PK request.|
+|rejectBattle|Reject PK request.|
+|exitBattle|Exit PK.|
+
+### Creating Instance
+
+#### create
+
+Create BattleStore instance.
+``` swift
+public static func create(liveID: String) -> BattleStore {
+    let store: BattleStoreImpl = StoreFactory.shared.getStore(roomID: liveID)
+    return store
+}
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|liveID|String|Live room ID.|
+
+### Observing State and Events
+
+#### battleEventPublisher
+
+PK event publisher.
+
+PK event publisher.
+
+**Data Structures：**BattleEvent
+
+### PK Operations
+
+#### requestBattle
+
+Initiate PK request.
+``` swift
+public func requestBattle(config: BattleConfig, userIDList: [String], timeout: TimeInterval, completion: BattleRequestClosure?) {
+    fatalError("\(#function) must be overridden by subclass")
+}
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|config|BattleConfig|PK configuration.|
+|userIDList|[String]|List of user IDs to invite for PK. Please pass in the user IDs of the other hosts you wish to PK with. Note: do not include the current user's own ID in this list.|
+|timeout|TimeInterval|Timeout in seconds. The maximum limit is 30 seconds.|
+|completion|BattleRequestClosure?|Callback for successful request initiation.|
+
+#### cancelBattleRequest
+
+Cancel PK request.
+``` swift
+public func cancelBattleRequest(battleId: String, userIdList: [String], completion: CompletionClosure?) {
+    fatalError("\(#function) must be overridden by subclass")
+}
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|battleId|String|PK ID.|
+|userIdList|[String]|User ID list.|
+|completion|CompletionClosure?|Callback for successful cancellation.|
+
+#### acceptBattle
+
+Accept PK request.
+``` swift
+public func acceptBattle(battleID: String, completion: CompletionClosure?) {
+    fatalError("\(#function) must be overridden by subclass")
+}
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|battleID|String|PK ID.|
+|completion|CompletionClosure?|Callback for successful acceptance.|
+
+#### rejectBattle
+
+Reject PK request.
+``` swift
+public func rejectBattle(battleID: String, completion: CompletionClosure?) {
+    fatalError("\(#function) must be overridden by subclass")
+}
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|battleID|String|PK ID.|
+|completion|CompletionClosure?|Callback for successful rejection.|
+
+#### exitBattle
+
+Exit PK.
+``` swift
+public func exitBattle(battleID: String, completion: CompletionClosure?) {
+    fatalError("\(#function) must be overridden by subclass")
+}
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|battleID|String|PK ID.|
+|completion|CompletionClosure?|Callback for successful exit.|
+
+## Data Structures
+
+### BattleEndedReason
+
+Reason for PK ending received by users in an ongoing PK.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|timeOver|0|PK countdown ended.|
+|allMemberExit|1|All PK members exited.|
+
+### BattleEvent
+
+PK-related callback events received.
+
+|**Enum Value**|**Description**|
+|---------|---------|
+|onBattleStarted|This callback is triggered when PK officially starts, notifying all participants that PK has begun.|
+|onBattleEnded|This callback is triggered when PK ends.|
+|onUserJoinBattle|This callback is triggered when a user joins PK.|
+|onUserExitBattle|This callback is triggered when a user exits PK.|
+|onBattleRequestReceived|This callback is triggered when a PK request is received.|
+|onBattleRequestCancelled|This callback is triggered when a PK request is cancelled.|
+|onBattleRequestTimeout|This callback is triggered when a PK request times out.|
+|onBattleRequestAccept|This callback is triggered when a PK request is accepted.|
+|onBattleRequestReject|This callback is triggered when a PK request is rejected.|
+
+### BattleConfig
+
+PK configuration information set when sending a PK request.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|duration|TimeInterval|PK duration (unit: seconds).|
+|needResponse|Bool|Whether the invitee needs to reply with accept/reject.|
+|extensionInfo|String|Extension information.|
+
+### BattleInfo
+
+PK information.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|battleID|String|PK ID.|
+|config|BattleConfig|PK configuration information set when sending a PK request.|
+|startTime|UInt|PK start marker timestamp (unit: seconds).|
+|endTime|UInt|PK end marker timestamp (unit: seconds).|
+
+### BattleState
+
+PK-related state data provided by BattleStore.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|currentBattleInfo|BattleInfo?|Current PK information.|
+|battleUsers|[SeatUserInfo]|PK user list.|
+|battleScore|[String:UInt]|PK score mapping.|
+
+### BattleRequestCallback
+
+PK request callback.
+
+Callback interface for PK requests, used to handle success or failure results of PK requests.
+
+**Methods**
+
+**onSuccess**: Success callback.
+``` swift
+fun onSuccess(battleInfo: BattleInfo, resultMap: Map<String, Int>)
+```
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|battleInfo|BattleInfo|PK information, containing detailed configuration and status of the PK.|
+|resultMap|Map<String,Int>|Response result callback for PK request.|
+
+**onError**: Failure callback.
+``` swift
+fun onError(code: Int, desc: String)
+```
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|code|Int|Error code.|
+|desc|String|Error description.|
+
+## Usage Example
+``` swift
+// Create store instance
+let store = BattleStore.create(liveID: "live_room_123")
+// Subscribe to state changes
+store.state.subscribe { state in
+    if let battleInfo = state.currentBattleInfo {
+        print("Current PK ID: \(battleInfo.battleID)")
+    }
+    print("PK user count: \(state.battleUsers.count)")
+}
+// Subscribe to PK events
+store.battleEventPublisher.sink { event in
+    switch event {
+    case .onBattleStarted(let battleInfo, let inviter, let invitees):
+        print("PK started, initiator: \(inviter.userName)")
+    case .onBattleEnded(let battleInfo, let reason):
+        print("PK ended, reason: \(reason)")
+    default:
+        break
+    }
+}
+// Initiate PK request
+let config = BattleConfig(duration: 300, needResponse: true)
+store.requestBattle(config: config, userIDList: ["user_456"], timeout: 30) { result in
+    switch result {
+    case .success(let (battleInfo, resultMap)):
+        print("PK request successful: \(battleInfo.battleID)")
+    case .failure(let error):
+        print("PK request failed: \(error)")
+    }
+}
+```

package/resource/knowledge/livekit/core-sdk/api-reference/ios/CoGuestStore.md

@@ -0,0 +1,370 @@
+## Introduction
+
+Co-guest feature enables real-time interaction between hosts and audience members through a seat-based system. `CoGuestStore` provides a comprehensive set of APIs to manage the entire co-guest lifecycle.
+
+> **Important: **
+>
+
+> Always use the factory method **create(liveID:)** with a valid live room ID to create a `CoGuestStore` instance. Do not attempt to initialize directly.
+>
+
+> **Note: **
+>
+
+> Co-guest state updates are delivered through the **state** publisher. Subscribe to it to receive real-time updates about connected users, invitations and applications.
+>
+
+> **Warning: **
+>
+
+> If a co-guest request does not receive a response within the specified timeout, an event with `NoResponseReason.timeout` will be triggered. Always handle timeout scenarios in your UI.
+>
+
+## Features
+- **Bidirectional Invitation**: Hosts can invite audience members, and audience members can also apply to join.
+
+- **State Management**: Real-time tracking of connected users, invitations and applications.
+
+- **Event-Driven Architecture**: Provides separate event streams for host and guest roles.
+
+- **Timeout Handling**: Built-in timeout mechanism for invitations and applications.
+
+## Subscribable Data
+
+**CoGuestState** fields are described below:
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|connected|[SeatUserInfo]|List of users already on seats.|
+|invitees|[LiveUserInfo]|List of users invited by host.|
+|applicants|[LiveUserInfo]|List of users who applied for co-guest received by host.|
+|candidates|[LiveUserInfo]|List of candidate users for co-guest.|
+
+## API List
+
+|**Function**|**Description**|
+|---------|---------|
+|create|Create object instance.|
+|hostEventPublisher|Host-side event publisher.|
+|guestEventPublisher|Guest-side event publisher.|
+|applyForSeat|Guest applies for co-guest.|
+|cancelApplication|Guest cancels application.|
+|acceptApplication|Host accepts application.|
+|rejectApplication|Host rejects application.|
+|inviteToSeat|Host invites guest to co-guest.|
+|cancelInvitation|Host cancels invitation.|
+|acceptInvitation|Guest accepts invitation.|
+|rejectInvitation|Guest rejects invitation.|
+|disConnect|End co-guest session.|
+
+### Creating Instance
+
+#### create
+
+Create CoGuestStore instance.
+``` swift
+public static func create(liveID: String) -> CoGuestStore {
+    let store: CoGuestStoreImpl = StoreFactory.shared.getStore(roomID: liveID)
+    return store
+}
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|liveID|String|Live room ID.|
+
+### Observing State and Events
+
+#### hostEventPublisher
+
+Host-side event publisher.
+
+Host event publisher.
+
+**Data Structures：**HostEvent
+
+#### guestEventPublisher
+
+Guest-side event publisher.
+
+Guest event publisher.
+
+**Data Structures：**GuestEvent
+
+### Guest Operations
+
+#### applyForSeat
+
+Apply to go on seat.
+``` swift
+public func applyForSeat(seatIndex: Int = -1, timeout: TimeInterval, extraInfo: String?, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+Request to join co-guest session as an audience member.
+
+After calling this method, a co-guest request is sent to all hosts in the live room. The request will remain active until:
+• Host accepts via **acceptApplication**
+• Host rejects via **rejectApplication**
+• Timeout expires
+• You cancel via **cancelApplication**.
+
+**Version**
+
+Supported since version 3.5.
+
+**Notes**
+
+> **Note: **
+>
+
+> If no host responds within the timeout, {ref2} event with **NoResponseReason/timeout** will be triggered.
+>
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|seatIndex|Int|Seat index, -1 means auto-assign seat.|
+|timeout|TimeInterval|Timeout (unit: seconds).|
+|extraInfo|String?|Extra information.|
+|completion|CompletionClosure?|Completion callback.|
+
+#### cancelApplication
+
+Cancel seat application.
+``` swift
+public func cancelApplication(completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+Cancel a previously sent co-guest application. After calling this method, all hosts will be notified of the application cancellation.
+
+**Version**
+
+Supported since version 3.5.
+
+**Notes**
+
+> **Note: **
+>
+
+> If the application has already been processed by a host, the cancellation may have no effect.
+>
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|completion|CompletionClosure?|Completion callback.|
+
+#### acceptApplication
+
+Accept seat application.
+``` swift
+public func acceptApplication(userID: String, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|userID|String|User ID.|
+|completion|CompletionClosure?|Completion callback.|
+
+#### rejectApplication
+
+Reject seat application.
+``` swift
+public func rejectApplication(userID: String, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|userID|String|User ID.|
+|completion|CompletionClosure?|Completion callback.|
+
+### Host Operations
+
+#### inviteToSeat
+
+Invite audience to seat.
+``` swift
+public func inviteToSeat(userID: String, seatIndex: Int = -1, timeout: TimeInterval, extraInfo: String?, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|userID|String|Invited user ID.|
+|seatIndex|Int|Seat index, -1 means auto-assign seat.|
+|timeout|TimeInterval|Timeout in seconds. Please set a value between 5 and 1800 seconds.|
+|extraInfo|String?|Extra information.|
+|completion|CompletionClosure?|Completion callback.|
+
+#### cancelInvitation
+
+Cancel seat invitation.
+``` swift
+public func cancelInvitation(inviteeID: String, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|inviteeID|String|Invited user ID.|
+|completion|CompletionClosure?|Completion callback.|
+
+#### acceptInvitation
+
+Accept seat invitation.
+``` swift
+public func acceptInvitation(inviterID: String, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|inviterID|String|Inviter user ID.|
+|completion|CompletionClosure?|Completion callback.|
+
+#### rejectInvitation
+
+Reject seat invitation.
+``` swift
+public func rejectInvitation(inviterID: String, completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|inviterID|String|Inviter user ID.|
+|completion|CompletionClosure?|Completion callback.|
+
+### Connection Control
+
+#### disConnect
+
+Disconnect co-guest.
+``` swift
+public func disConnect(completion: CompletionClosure?) { fatalError("\(#function) must be overridden by subclass") }
+```
+
+**Version**
+
+Supported since version 3.5.
+
+**Parameters**
+
+|**Parameter**|**Type**|**Description**|
+|---------|---------|---------|
+|completion|CompletionClosure?|Completion callback.|
+
+## Data Structures
+
+### NoResponseReason
+
+Reason for no response to co-guest invitation sent by host or co-guest request initiated by audience.
+
+|**Enum Value**|**Value**|**Description**|
+|---------|---------|---------|
+|timeout|0|Request timeout.|
+|alreadySeated|1|User already on seat.|
+
+### HostEvent
+
+Callback events received on host side.
+
+|**Enum Value**|**Description**|
+|---------|---------|
+|onGuestApplicationReceived|This callback is triggered when an audience applies for co-guest.|
+|onGuestApplicationCancelled|This callback is triggered when an audience cancels co-guest application.|
+|onGuestApplicationProcessedByOtherHost|This callback is triggered when an audience's co-guest application is processed by another host.|
+|onHostInvitationResponded|This callback is triggered when a co-guest invitation sent by host receives a response from audience.|
+|onHostInvitationNoResponse|This callback is triggered when a co-guest invitation sent by host receives no response.|
+
+### GuestEvent
+
+Callback events received on guest side.
+
+|**Enum Value**|**Description**|
+|---------|---------|
+|onHostInvitationReceived|This callback is triggered when receiving a co-guest invitation from host.|
+|onHostInvitationCancelled|This callback is triggered when host cancels co-guest invitation.|
+|onGuestApplicationResponded|This callback is triggered when audience's co-guest application receives a response from host.|
+|onGuestApplicationNoResponse|This callback is triggered when audience's co-guest application receives no response.|
+|onKickedOffSeat|This callback is triggered when audience is kicked off seat by host.|
+
+### CoGuestState
+
+Co-guest related state data provided externally by CoGuestStore.
+
+|**Property**|**Type**|**Description**|
+|---------|---------|---------|
+|connected|[SeatUserInfo]|List of users already on seats.|
+|invitees|[LiveUserInfo]|List of users invited by host.|
+|applicants|[LiveUserInfo]|List of users who applied for co-guest received by host.|
+|candidates|[LiveUserInfo]|List of candidate users for co-guest.|
+
+## Usage Example
+``` swift
+// Create store instance
+let store = CoGuestStore.create(liveID: "live_room_123")
+// Subscribe to state changes
+store.state.subscribe { state in
+    print("Connected users: \(state.connected.count)")
+    print("Pending applications: \(state.applicants.count)")
+}
+// Subscribe to host events (for hosts)
+store.hostEventPublisher.sink { event in
+    switch event {
+    case .onGuestApplicationReceived(let guestUser):
+        print("Received application from \(guestUser.userName)")
+        // Show accept/reject UI
+    case .onHostInvitationResponded(let isAccept, let guestUser):
+        print("Audience \(guestUser.userName) \(isAccept ? "accepted" : "rejected")")
+    default:
+        break
+    }
+}
+// Host: Accept application
+store.acceptApplication(userID: "user_456") { code, message in
+    if code == 0 {
+        print("Application accepted successfully")
+    }
+}
+```