(ios-core): add core V2 upgrade docs & migration guide

docs/ios-core/Introduction.mdx

@@ -1,6 +1,6 @@
 ---
 title: Introduction
-sidebar_position: 3
+sidebar_position: 4
 sidebar_class_name: module-seperation
 ---
 

docs/ios-core/pre-call/_category_.json

@@ -1,5 +1,5 @@
 {
-  "position": 2,
+  "position": 3,
   "label": "Pre-call",
   "collapsible": true,
   "className": "pre-call-docs"

docs/ios-core/quickstart.mdx

@@ -4,7 +4,7 @@ tags:
   - quickstart
   - setup
 slug: /
-sidebar_position: 1
+sidebar_position: 2
 ---
 
 import Tabs from '@theme/Tabs';

docs/ios-core/upgrade-v2/1-introduction.mdx

@@ -0,0 +1,54 @@
+---
+title: Core V2 Introduction
+sidebar_position: 1
+tags:
+  - iOS-core
+  - v2
+---
+
+With the v2 release of the Dyte Core SDK, we're introducing a major upgrade focused on making the development experience simpler, more consistent, and intuitive. This upgrade introduces breaking changes across four key areas:
+
+### 1. Migration to V2 REST API Terminology
+
+- `meeting.meta.roomName` -> `meeting.meta.meetingId`
+- `DyteMeetingParticipant.clientSpecificId` -> `DyteMeetingParticipant.customParticipantId`
+- Removed `DyteMeetingInfo` (V1)
+
+
+### 2. Removal of Deprecated APIs
+
+We have removed deprecated methods and properties in favour of improved, uniform, and clearer versions.
+
+- Removed `DyteParticipants.screenshares` (use `DyteParticipants.screenShares`). The deprecated type `DyteScreenShareMeetingParticipant` has also been removed
+- **Chat Methods**: Removed deprecated file and image send methods. The new closure-based methods take `NSURL`s & return proper errors
+  - File message methods:
+    - Removed `sendFileMessage(filePath: String)`, `sendFileMessage(filePath: String, fileName: String)`, `sendFileMessage(fileUri: NSURL)`.  
+    Use `sendFileMessage(fileURL: NSURL, onResult: (ChatFileError?) -> Void)`
+    - Removed `sendFileMessage(filePath: String, peerIds: [String])`, `sendFileMessage(fileUri: NSURL, peerIds: [String])`.  
+    Use `sendFileMessage(fileURL: NSURL, peerIds: [String], onResult: (ChatFileError?) -> Void)`
+  - Image message methods:
+    - Removed `sendImageMessage(filePath: String, fileName: String)`, `sendImageMessage(imageUri: NSURL)`, `sendImageMessage(imagePath: String)`.  
+    Use `sendImageMessage(imageURL: NSURL, onResult: (ChatFileError?) -> Void)`
+    - Removed `sendImageMessage(imagePath: String, peerIds: [String])`, `sendImageMessage(imageUri: NSURL, peerIds: [String])`, 
+    `sendImageMessage(filePath: String, fileName: String, peerIds: [String])`.  
+    Use `sendImageMessage(imageURL: NSURL, peerIds: [String], onResult: (ChatFileError?) -> Void)`
+- Removed deprecated listener callbacks:
+  - `DyteSelfEventsListener.onStageStatusUpdated`. Use `DyteStageEventListener.onStageStatusUpdated()`
+  - `DyteStageEventListener.onPresentRequestAccepted(participant: DyteJoinedMeetingParticipant)`
+  - `DyteMeetingRoomEventsListener.onActiveTabUpdate(id: String, tabType: ActiveTabType)`.  
+  Use `DyteMeetingRoomEventsListener.onActiveTabUpdate(meeting: DyteMobileClient, activeTab: ActiveTab)`
+
+
+### 3. Revamped Error Handling
+
+- Errors are categorised by modules, such as `ChatError`, `SelfError`, and `MeetingError`
+- All public APIs provide proper errors and additional error data where applicable for better debugging
+- Uses enums for error codes, making it easier to handle specific cases
+
+
+### 4. API Structural Changes
+
+We made a few direct breaking changes in our APIs to simplify the types, make methods more intuitive and ensure uniformity across platforms. 
+For example, `DyteMeetingParticipant` has been restructured to align with real-world entities.
+
+Learn more about the direct breaking changes and migration instructions on the next page.

docs/ios-core/upgrade-v2/2-breaking-changes-migration.mdx

@@ -0,0 +1,188 @@
+---
+title: Direct Breaking Changes and Migration Guide
+sidebar_position: 2
+tags:
+  - iOS-core
+  - v2
+---
+
+This section provides details about the additional breaking changes made in Dyte Core SDK v2 and provides migration guidance. 
+The changes span multiple modules, mainly simplifying the APIs or renaming them to ensure uniformity across the platforms.
+
+
+### Changes in Participant Hierarchy and Simplified Types
+
+The participant hierarchy has been simplified to align better with real-world entities:
+
+- **Old Structure**:
+  - `DyteMeetingParticipant` was the parent class with direct subtypes:
+    - `DyteJoinedMeetingParticipant`
+    - `DyteWaitlistedParticipant`
+  - `DyteJoinedMeetingParticipant` had two subtypes:
+    - `DyteScreenShareMeetingParticipant`
+    - `DyteSelfParticipant` (local user)
+
+- **New Structure**:
+  - `DyteMeetingParticipant` still represents a participant in a meeting which is simply either:
+    - `DyteSelfParticipant` (local user) or
+    - `DyteRemoteParticipant` (other participants in the meeting)
+
+- Moved methods for managing waiting room requests to `DyteParticipants`:
+  - `DyteWaitlistedParticipant.acceptWaitListedRequest()` -> `DyteParticipants.acceptWaitingRoomRequest(id)`
+  - `DyteWaitlistedParticipant.rejectWaitListedRequest()` -> `DyteParticipants.rejectWaitingRoomRequest(id)`
+
+The old participant hierarchy was complex, with certain types representing temporary states or behaviour at runtime. 
+The new structure simplifies this by clearly differentiating between the local user and remote participants.
+
+**Migration Instructions**:
+
+- Replace instances of `DyteJoinedMeetingParticipant` with `DyteRemoteParticipant`.
+- Replace any usage of `DyteScreenShareMeetingParticipant` with `DyteMeetingParticipant` or its subtype.
+- `DyteSelfParticipant` is now a direct subtype of `DyteMeetingParticipant`.
+- Update the Waiting Room management logic to use APIs from `DyteParticipants` for accepting/rejecting waiting room requests.
+
+
+### Changes in DyteMeetingRoomEventsListener Connection State Callbacks
+
+The following connection state callbacks have been removed:
+
+- `onMeetingRoomDisconnected`, `onConnectingToMeetingRoom`, `onConnectedToMeetingRoom`,  
+`onDisconnectedFromMeetingRoom`, `onMeetingRoomConnectionFailed`, `onReconnectingToMeetingRoom`,  
+`onReconnectedToMeetingRoom`, `onMeetingRoomReconnectionFailed`
+
+These callbacks have been consolidated into a single unified callback:  
+`onSocketConnectionUpdate(newState: SocketConnectionState)`
+
+**Migration Instructions**:
+
+- Move all connection state handling, mainly reconnection logic from the old callbacks to `onSocketConnectionUpdate()`. 
+The new callback provides a `SocketConnectionState` parameter that represents the current state of the meeting connection.
+
+
+### `DyteMeetingInfoV2.baseUrl` has been renamed to `DyteMeetingInfoV2.baseDomain`
+
+This change is applicable only if you are using a white-labeled domain. In normal cases, now you just need to pass `authToken`, 
+`enableAudio` & `enableVideo`.
+
+
+### Other Direct Changes module-wise
+
+#### 1. DyteMobileClient (meeting)
+
+- The following methods now return `MeetingError` in the `onFailure` callback instead of `DyteError`:
+    - `init()`, `leaveRoom()`, `release()`
+- Renamed some methods for adding/removing listeners to align with the respective listener names:
+    - `addParticipantEventsListener()` -> `addParticipantsEventListener()`
+    - `addPollsEventsListener()` -> `addPollsEventListener()`
+    - `addStageEventsListener()` -> `addStageEventListener()`
+    - `addLivestreamEventListener()` -> `addLivestreamEventListener()`
+- Changes in `DyteMeetingRoomEventsListener` callbacks:
+  - Failure callbacks now return standardised `MeetingError` instead of `Exception`:
+    - `onMeetingInitFailed(exception: KotlinException)` -> `onMeetingInitFailed(error: MeetingError)`
+    - `onMeetingRoomJoinFailed(exception: KotlinException)` -> `onMeetingRoomJoinFailed(error: MeetingError)`
+  - Relevant callback methods now include `DyteMobileClient` as a parameter, making it easier to access meeting object
+    - `onMeetingInitCompleted()` -> `onMeetingInitCompleted(meeting: DyteMobileClient)`
+    - `onMeetingRoomJoinCompleted()` -> `onMeetingRoomJoinCompleted(meeting: DyteMobileClient)`
+    - `onActiveTabUpdate(activeTab: ActiveTab)` -> `onActiveTabUpdate(meeting: DyteMobileClient, activeTab: ActiveTab)`
+
+#### 2. DyteSelfParticipant (meeting.localUser)
+
+- Renamed the following screen share methods to make the name casing of "ScreenShare" uniform with the rest of the SDK:
+  - `enableScreenshare()` -> `enableScreenShare()`
+  - `disableScreenshare()` -> `disableScreenShare()`
+- Merged `onScreenShareStarted` & `onScreenShareStopped` into a single callback:  
+`onScreenShareUpdate(isEnabled: Bool)`
+- Moved `onRoomMessage()` callback from `DyteSelfEventsListener` to `DyteParticipantsEventListener` and renamed it to `onNewBroadcastMessage()`
+- Removed the unused `onProximityChanged(isNear: Bool)`
+
+**Migration Instructions**:
+
+- Update enable/disable screen share method names
+- Replace the old screen share callbacks with the new `onScreenShareUpdate()` callback
+- Move the broadcast message handling logic to `DyteParticipantsEventListener.onNewBroadcastMessage()` callback
+
+#### 3. DyteParticipants (meeting.participants)
+
+- Renamed `DyteRoomParticipants` to `DyteParticipants` for uniformity across the platforms
+- `meeting.participants` now contains data only related to remote participants, excluding the local user
+- Changes in `DyteParticipantsEventListener` callbacks:
+  - Callbacks are now given only for remote participant events. Local user changes are dispatched to `DyteSelfEventsListener`
+  - Listener renamed from `DyteParticipantEventsListener` to `DyteParticipantsEventListener`
+  - Merged `onScreenShareStarted` & `onScreenShareEnded` into a single callback:  
+  `onScreenShareUpdate(participant: DyteRemoteParticipant, isEnabled: Bool)`
+  - Removed `onNoActiveSpeaker()`. Now `onActiveSpeakerChanged(participant: DyteRemoteParticipant?)` gets a null value when active participant is cleared
+  - Removed unused, uncalled `onScreenSharesUpdated()`, `onSetAsActiveSpeaker()`, & `onRemovedAsActiveSpeaker()`
+  - Following callbacks have been tweaked for consistency & clarity:
+      - `onAudioUpdate(audioEnabled: Bool, participant: DyteMeetingParticipant)` -> `onAudioUpdate(participant: DyteRemoteParticipant, isEnabled: Bool)`
+      - `onVideoUpdate(videoEnabled: Bool, participant: DyteMeetingParticipant)` -> `onVideoUpdate(participant: DyteRemoteParticipant, isEnabled: Bool)`
+      - `onPinned()` -> `onParticipantPinned(participant: DyteRemoteParticipant)`
+      - `onUnpinned()` -> `onParticipantUnpinned(participant: DyteRemoteParticipant)`
+
+**Migration Instructions**:
+
+- Ensure that local user-related changes are handled using `DyteSelfEventsListener` instead of `DyteParticipantsEventListener`
+- Update the callback signatures wherever `DyteParticipantsEventListener` is implemented
+
+#### 4. DyteStage APIs (meeting.stage)
+
+- Stage Host Methods:
+  - Removed methods `grantAccessAll()` and `denyAccessAll()`
+  - `grantAccess()`, `denyAccess()`, and `kick()` now take a list of user IDs, making them more flexible
+- Removed unused `.rejectedToJoinStage` constant from `StageStatus` enum
+- DyteStageEventListener: Callbacks now consistently use the term '*stage*' to align with the **DyteStage** module for better clarity
+  - Redundant peer callbacks have been removed to simplify the API. Those events can be inferred as per use-case by  
+  `onPeerStageStatusUpdated(participant: DyteRemoteParticipant, oldStatus: StageStatus, newStatus: StageStatus)`
+  - `onPresentRequestReceived()` -> `onStageAccessRequestAccepted()`
+  - `onStageStatusUpdated(stageStatus: DyteStageStatus)` -> `onStageStatusUpdated(oldStatus: StageStatus, newStatus: StageStatus)`
+  - `onPresentRequestAdded(participant: DyteJoinedMeetingParticipant)` -> `onNewStageAccessRequest(participant: DyteRemoteParticipant)`
+  - `onStageRequestsUpdated(accessRequests: [DyteJoinedMeetingParticipant])` -> `onStageAccessRequestsUpdated(accessRequests: [DyteRemoteParticipant])`
+  - Removed `onAddedToStage()`, it was called when localUser successfully joined the stage, the name didn’t match the scenario
+
+**Migration Instructions**:
+
+- Update the method calls for granting, denying, and kicking stage participants to use lists of user IDs
+- Replace removed/renamed callbacks in `DyteStageEventListener` with the new ones
+
+#### 5. DytePolls APIs (meeting.polls)
+
+- Renamed Classes and Properties
+  - `DytePollMessage` -> `DytePoll`
+  - `DytePollEventsListener` -> `DytePollsEventListener`
+  - `DytePolls.messages` -> `DytePolls.items`
+- `DytePollsEventListener` changes:
+  - `onPollUpdates(pollMessages: [DytePoll])` -> `onPollUpdates(pollItems: [DytePoll])`
+
+#### 6. DyteRecording APIs (meeting.recording)
+
+- Removed following error callbacks from `DyteRecordingEventsListener` as `DyteRecording` methods now return proper errors:
+  - `onMeetingRecordingStopError()`, `onMeetingRecordingPauseError()`, `onMeetingRecordingResumeError()`
+- `onMeetingRecordingStarted()`, `onMeetingRecordingEnded()`, and `onMeetingRecordingStateUpdated()` have been merged into a single callback:  
+`onRecordingStateChanged(oldState: DyteRecordingState, newState: DyteRecordingState)`.
+
+**Migration Instructions**
+
+- Remove any references to the deleted error callbacks in your code. Move error handling code to the `onResult` lambda of the recording methods.
+- Replace the separate recording state callbacks with the new unified `onRecordingStateChanged` callback.
+
+#### 7. DyteLivestream APIs (meeting.livestream)
+
+- Changed the term "LiveStream" to "Livestream" throughout the SDK
+  - `meeting.liveStream` -> `meeting.livestream`
+  - `DyteLiveStream` -> `DyteLivestream`
+- Simplified `LivestreamState` enum to align with the Web SDK
+  - **Old States**: `.none`, `.starting`, `.started`, `.stopping`, `.stopped`, `.errored`
+  - **New States**: `.idle`, `.starting`, `.streaming`, `.stopping`
+- `DyteLivestream.liveStreamUrl` -> `DyteLivestream.playbackUrl`
+- Changes in `DyteLivestreamEventsListener`:
+  - The `DyteLiveStreamEventsListener` has been renamed to `DyteLivestreamEventListener`
+  - `onLiveStreamStarting`, `onLiveStreamStarted`, `onLiveStreamEnding`, and `onLiveStreamEnded` have been consolidated into 
+  `onLivestreamStateChanged(oldState: LivestreamState, newState: LivestreamState)`
+  - `onLiveStreamErrored()` -> `onLivestreamError(message: String)`
+  - `onLiveStreamStateUpdate(data: DyteLivestreamData)` ->  `onLivestreamUpdate(data: DyteLivestreamData)`
+  - Removed `onStageCountUpdated(count: Int)`
+
+**Migration Instructions**
+
+- Update all class and property references to replace "LiveStream" with "Livestream"
+- Use the new `LivestreamState` enum values, replacing old state with the new, simplified states
+- Update callbacks in `DyteLivestreamEventListener` to the new versions, ensuring state changes are handled using `onLivestreamStateChanged` and other revised methods

docs/ios-core/upgrade-v2/_category_.json

@@ -0,0 +1,5 @@
+{
+  "position": 2,
+  "label": "2.x Upgrade Guide",
+  "collapsible": true
+}