@amityco/social-plus-vise 0.14.28 → 1.0.0

package/docs-cache/social-plus-sdk/core-concepts/foundation/logging.mdx

@@ -0,0 +1,236 @@
+# Logging & Errors
+
+> Monitor network activity and handle errors in the social.plus SDK using observeNetworkActivities().
+
+# Logging
+
+## Network Activity Monitoring
+
+Use `observeNetworkActivities()` to inspect all HTTP requests and responses in your social.plus SDK integration during development.
+
+**Best Practice**: Enable network logging during development to troubleshoot issues, but disable it in production to avoid performance overhead.
+
+
+The `observeNetworkActivities()` function provides real-time insights into all HTTP requests and responses within the SDK, enabling effective debugging and performance analysis.
+
+### Key Features
+
+- **Request/Response Logging**: Monitor all API calls with detailed information
+- **Performance Metrics**: Track request timing and response sizes
+- **Error Debugging**: Identify network-related issues quickly
+- **Development Tool**: Essential for troubleshooting SDK integration
+
+```swift iOS
+/// Observe ongoing network activities in sdk
+client.observeNetworkActivities { request, response, data in
+
+    // request: URLRequest // Request
+    // response: HTTPURLResponse // HTTP Protocol response
+    // data: Data // Payload returned from server
+
+}
+```
+
+```kotlin Android
+/// Observe ongoing network activities in sdk
+    AmityCoreClient.observeNetworkActivities()
+        .doOnNext { activity ->
+            (activity as? AmityNetworkActivity.HTTP)?.run {
+                val response: Response = activity.response
+                val request = response.request
+                val processedText =
+                    "Request: ${request.method} ${request.url}\n" +
+                            "(${DateTime(response.sentRequestAtMillis)})\n" +
+                            "Response: ${response.code} ${response.message}\n" +
+                            "(${DateTime(response.receivedResponseAtMillis)})\n"
+                print(processedText)
+            }
+        }
+        .doOnError {
+            // Exception
+        }
+        .subscribe()
+```
+
+```typescript TypeScript
+import { Client } from '@amityco/ts-sdk';
+
+/// Observe ongoing network activities in sdk
+Client.onNetworkActivities((request, response) => {
+  console.log(request);
+  console.log(response);
+});
+```
+
+## Troubleshooting
+
+### Common Issues
+
+    Network logging stores request/response data in memory. Disable logging in production or implement log rotation for long-running applications.
+
+    Logging adds overhead to network operations. Use conditional compilation flags to disable in release builds.
+
+    social.plus apps can generate many API calls. Implement filtering to log only specific endpoints or error conditions.
+
+
+# Error Handling
+
+Effective error handling is crucial for building reliable social applications. social.plus SDK provides structured error information to help you handle different scenarios gracefully.
+
+## Error Types
+
+social.plus errors are categorized into two main types:
+
+Issues on the social.plus backend (400xxx, 500xxx codes)
+
+Issues in the SDK or client environment (800xxx codes)
+
+## Common Server Errors
+
+| Code | Error | Description |
+|------|-------|-------------|
+| 400100 | `UnauthorizedError` | User not authenticated or invalid token |
+| 400101 | `TokenExpired` | Authentication token has expired |
+
+| Code | Error | Description |
+|------|-------|-------------|
+| 400301 | `PermissionDenied` | User lacks permission for the action |
+| 400302 | `UserIsMuted` | Muted user attempting to send message |
+| 400304 | `UserIsBanned` | Banned user accessing restricted content |
+| 400312 | `GlobalBanError` | Globally banned user performing any action |
+
+| Code | Error | Description |
+|------|-------|-------------|
+| 400307 | `MaxRepetitionExceed` | Too many messages with blocked content |
+| 400308 | `BanWordFound` | Message contains blocked words |
+| 400309 | `LinkNotAllowed` | Message contains non-whitelisted links |
+| 400314 | `UnsafeContent` | Content flagged by AI moderation |
+
+| Code | Error | Description |
+|------|-------|-------------|
+| 400000 | `BadRequestError` | Invalid request parameters |
+| 400315 | `DuplicateEntryError` | Duplicate display name or identifier |
+| 400400 | `ItemNotFound` | Requested resource not found |
+| 400900 | `Conflict` | Conflicting data operation |
+
+| Code | Error | Description |
+|------|-------|-------------|
+| 500000 | `BusinessError` | Internal system error |
+
+## Client Errors
+
+| Code | Error | Description |
+|------|-------|-------------|
+| 800000 | `Unknown` | Uncategorized client-side error |
+| 800110 | `InvalidParameter` | Invalid parameter data type |
+| 800210 | `ConnectionError` | Network connectivity issues |
+
+## Error Handling Implementation
+
+### Basic Error Parsing
+```swift iOS
+func parseError(_ error: Error) {
+    let sdkError = error as NSError
+    guard let amityError = AmityErrorCode(rawValue: sdkError.code) else {
+        // Unknown error occurred. Please report this error code to Amity
+        return
+    }
+
+    // ...
+    // Process AmityError here..
+}
+```
+
+```kotlin Android
+fun parseAmityError(exception: Exception) {
+    if (AmityError.from(exception) == AmityError.CHANNEL_IS_MUTED) {
+        // Couldn't send a message to this channel because this channel is muted.
+    }
+}
+```
+
+
+### Global Ban Handling
+
+A global ban error means that the user is banned from the system resulting in the inability to have a connection with the system. If the user already has a session, the session will be revoked, and will be unable to create a new session. 
+
+```swift iOS
+var client: AmityClient?
+client.clientErrorDelegate = self // set yourself as the delegate
+
+...
+
+// Implement this delegate method which gets called when error occurs
+func didReceiveAsyncError(_ error: Error) {
+        let error = error as NSError
+        guard let amityError = AmityErrorCode(rawValue: error.code) else {
+            assertionFailure("unknown error \(error.code), please report this code to Amity")
+            return
+        }
+
+        if amityError == .globalBan {
+            // Handle global ban event here
+        }
+    }
+}
+```
+
+```kotlin Android
+//error handling upon login
+fun login() {
+    AmityCoreClient.login(userId = "userId")
+        .build()
+        .submit()
+        .doOnError {
+            if (AmityError.from(it) == AmityError.USER_IS_GLOBAL_BANNED) {
+                // handle the case the user is globally banned
+            }
+        }
+        .subscribe()
+}
+
+//error handling thru real-time events
+fun subscribeGlobalBan() {
+    // Subscription can be done at Application lifecycle
+    // and lives through the remaining Application lifecycle
+    AmityCoreClient.getGlobalBanEvents()
+        .doOnNext {
+            // handle the case the user is globally banned
+        }
+        .subscribe()
+}
+```
+
+```typescript TypeScript
+import { Client } from '@amityco/ts-sdk';
+
+Client.onConnectionError(error => {
+  if (error.code === Amity.ServerError.GLOBAL_BAN) {
+    console.log('user has been globally banned!');
+  }
+})
+```
+
+
+## Best Practices
+
+### Do's ✅
+
+- **Provide specific error messages** based on error codes
+- **Log errors** for debugging and monitoring
+- **Implement retry logic** for network errors
+- **Handle global bans** with appropriate user communication
+- **Use error boundaries** in React applications
+- **Show loading states** during error recovery
+
+### Don'ts ❌
+
+- **Don't ignore errors** - always handle them appropriately
+- **Don't show technical error codes** to end users
+- **Don't retry indefinitely** - implement maximum retry limits
+- **Don't expose sensitive information** in error messages
+
+
+**Pro Tip**: Use network logging to identify performance bottlenecks, monitor error rates, and validate that your app is making expected API calls during development.
+
+---

package/docs-cache/social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/android.mdx

@@ -0,0 +1,262 @@
+# Android Live Objects/Collections
+
+> Live Objects are supported in the Android SDK with RxJava Data Streaming
+
+The RxJava3 library is being used in Android development to achieve Live Object and Live Collection behavior.
+
+It is a Java VM implementation of ReactiveX, a library for composing asynchronous and event-based programs by using observable sequences. The building blocks of RxJava are Observables and Subscribers. Observable is used for emitting items and Subscriber is used for consuming those items.
+
+You can visit [ReactiveX](https://reactivex.io/) for more information.
+
+## How it Works
+
+SDK handles lots of data received from various sources. Data can be present in local cache. It might also be queried from the server or received from some real-time events. What this means is that same data is constantly updating. The data that you are accessing at the moment can get updated by other sources and becomes out of sync.
+
+Rx3 Data Stream helps in syncing the data so you will always get the most recent one. Whenever the data updates, you will be notified through **Flowable Objects** and **Flowable Collection**.
+
+New data gets automatically collected everytime when there is an updation and user need not refresh to get the recent data.
+
+### Data Sources
+
+    Data present in local storage
+    Data queried from the server
+    Data received from real-time events
+
+## How to Retrieve Data from Rx3 Data Stream
+
+To retrieve data from the RxStream, we need to subscribe to the Stream(Flowable/Single/Completable) by defining subscribing and observing threads.
+
+```kotlin
+fun subscribeToFlowable() {
+    //Flowable
+    val flowableStream: Flowable<Any> =
+        Flowable.just("one", "two", "three") // Flowable initialization
+    flowableStream
+        .subscribeOn(Schedulers.io()) // subscribing an operation on io thread (Background thread)
+        .observeOn(AndroidSchedulers.mainThread()) // observing results on main thread (UI thread)
+        .doOnNext {
+            // data is available here
+        }.doOnError {
+            // handle error here
+        }.subscribe()
+}
+```
+
+## Events a Data Stream can Emit
+
+In the RxJava3 framework we have these different types of objects that can be observed:
+
+### Flowable
+Emits a stream of elements
+
+- **doOnNext**
+- **doOnError**
+
+### Single
+Emits exactly one element
+
+- **doOnSuccess**  
+- **doOnError**
+
+### Completable
+Emits a "complete" event, without emitting any data type, just a success/failure
+
+- **doOnComplete**
+- **doOnError**
+
+```kotlin
+val flowableStream: Flowable<List<AmityPost>> = postRepository.getPosts()
+
+flowableStream
+    .subscribeOn(Schedulers.io())
+    .observeOn(AndroidSchedulers.mainThread())
+    .doOnNext { posts ->
+        // Handle stream of posts
+        updateUI(posts)
+    }
+    .doOnError { error ->
+        // Handle error
+        showErrorMessage(error.message)
+    }
+    .subscribe()
+```
+
+```kotlin
+val singlePost: Single<AmityPost> = postRepository.getPost(postId)
+
+singlePost
+    .subscribeOn(Schedulers.io())
+    .observeOn(AndroidSchedulers.mainThread())
+    .doOnSuccess { post ->
+        // Handle single post
+        displayPost(post)
+    }
+    .doOnError { error ->
+        // Handle error
+        showErrorMessage(error.message)
+    }
+    .subscribe()
+```
+
+```kotlin
+val deleteOperation: Completable = postRepository.deletePost(postId)
+
+deleteOperation
+    .subscribeOn(Schedulers.io())
+    .observeOn(AndroidSchedulers.mainThread())
+    .doOnComplete {
+        // Handle successful completion
+        showSuccessMessage("Operation completed")
+    }
+    .doOnError { error ->
+        // Handle error
+        showErrorMessage(error.message)
+    }
+    .subscribe()
+```
+
+## Flow functions
+
+By using the `.asFlow()` method, it enables the conversion of Flowable&lt;T&gt; functions of the Amity Android SDK into Flow functions.
+
+```kotlin
+fun getAllUsers(): Flow<PagingData<AmityUser>> {
+    return AmityCoreClient.newUserRepository()
+        .getUsers()
+        .build()
+        .query()
+        .asFlow()
+}
+```
+
+## Jetpack Compose compatibility
+
+Amity Android SDK seamlessly integrates with Jetpack Compose UI, allowing you to take full advantage of the modern UI toolkit provided by Jetpack Compose. You can effortlessly incorporate our SDK into your Jetpack Compose-based projects to enhance your app's social experience. This compatibility ensures that you can leverage the power of Jetpack Compose while benefiting from the features and capabilities our SDK provides.
+
+### Flow of PagingData in Compose
+
+In Jetpack Compose, integrating data from a `Flow<PagingData<T>>` source into your UI is made easy through the `collectAsLazyPagingItems()` function. This function allows you to seamlessly paginate and display items within your Composable functions.
+
+To start using it, add compose paging dependency in your project app level build.gradle file.
+
+```gradle
+implementation "androidx.paging:paging-compose:x.y.z"
+```
+
+Then in your Composable functions, you can collect from flow and display data, and also can observe the load state.
+
+```kotlin
+@Composable
+fun UserList(
+    modifier: Modifier = Modifier
+) {
+    //  collect data from flow using collectAsLazyPagingItems
+    val users = getAllUsers().collectAsLazyPagingItems()
+
+    //  display data in LazyColumn or LazyRow
+    LazyColumn(
+        modifier = modifier.fillMaxSize(),
+        horizontalAlignment = Alignment.CenterHorizontally,
+    ) {
+        items(
+            count = users.itemCount,
+            key = users.itemKey { it.getUserId() }
+        ) { index ->
+            //  render each item here
+            val user = users[index]
+            Text(text = "UserId: ${user?.getUserId()}")
+        }
+
+        //  handle load state on loading first page
+        when (val state = users.loadState.refresh) {
+            is LoadState.Error -> {
+                //  handle error
+                item {
+                    Text(text = "Error: ${state.error.message}")
+                }
+            }
+
+            is LoadState.Loading -> {
+                //  loading first page
+                item {
+                    Column(
+                        modifier = modifier.fillParentMaxSize(),
+                        horizontalAlignment = Alignment.CenterHorizontally,
+                        verticalArrangement = Arrangement.Center,
+                    ) {
+                        Text(text = "Refresh/First Loading")
+                        CircularProgressIndicator(color = Color.Black)
+                    }
+                }
+            }
+
+            else -> {}
+        }
+
+        //  handle load state on loading next page
+        when (val state = users.loadState.append) {
+            is LoadState.Error -> {
+                //  handle error
+                item {
+                    Text(text = "Error: ${state.error.message}")
+                }
+            }
+
+            is LoadState.Loading -> {
+                //  loading next page
+                item {
+                    Column(
+                        modifier = modifier.fillMaxWidth(),
+                        horizontalAlignment = Alignment.CenterHorizontally,
+                        verticalArrangement = Arrangement.Center,
+                    ) {
+                        Text(text = "Pagination Loading")
+                        CircularProgressIndicator(color = Color.Black)
+                    }
+                }
+            }
+
+            else -> {}
+        }
+    }
+}
+```
+
+### Flow in Compose
+
+By using `collectAsState()` method, it can deliver asynchronous data updates to your Compose UI components.
+
+```kotlin
+fun getPostAsFlow(): Flow<AmityPost> {
+    return AmitySocialClient.newPostRepository()
+        .getPost(postId = "postId")
+        .asFlow()
+}
+
+@Composable
+fun SinglePostItem() {
+    val post by getPostAsFlow().collectAsState(initial = null)
+
+    Text(text = "Post ID: ${post?.getPostId()}")
+}
+```
+
+
+## Best Practices
+
+    **Proper Disposal**: Always dispose of RxJava subscriptions to prevent memory leaks when Activities/Fragments are destroyed.
+
+    **Proper Scheduling**: Use `subscribeOn(Schedulers.io())` for background operations and `observeOn(AndroidSchedulers.mainThread())` for UI updates.
+
+    **Graceful Recovery**: Implement robust error handling with `doOnError` for all RxJava streams to prevent crashes.
+
+    **State Management**: Use `collectAsState()` for single objects and `collectAsLazyPagingItems()` for paginated collections in Compose.
+
+## Related Resources
+
+    Learn more about reactive programming concepts
+    Explore Android's official paging library
+    Build modern Android UI with declarative programming
+    Access RxJava3 source code and documentation
+
+---

package/docs-cache/social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/flutter.mdx

@@ -0,0 +1,195 @@
+# Flutter Live Objects/Collections
+
+> Live Objects are supported in the Flutter SDK with Streams and LiveCollection for real-time data synchronization
+
+In Flutter SDK, we have a concept of **Live Object** and **Live Collection**.
+
+Live Object is represented by `StreamSubscription<Object>` instance and Live Collection is represented by an instance of `LiveCollection`. LiveCollection is a generic class that encapsulates any other object and notifies the observer whenever any property of the encapsulated object changes.
+
+Live Object helps to observe changes in a single object whereas Live Collection helps to observe changes in a list of objects.
+
+Examples: `StreamSubscription<AmityPost>` for single objects or `LiveCollection<AmityMessage>` for collections.
+
+## How it Works
+
+SDK handles lots of data received from various sources. Data can be present in the local cache. It might also be queried from the server or received from some real-time events. What this means is that the same data is constantly updating. The data that you are accessing at the moment can get updated by other sources and become out of sync.
+
+Live Object and Live Collection help in syncing the data so you will always get the most recent one. Whenever the data updates, you will be notified through helper methods in the Live Object and Live Collection classes.
+
+New data gets automatically collected every time when there is an update and the user need not refresh to get the recent data.
+
+### Data Sources
+
+    Data present in local storage
+    Data queried from the server
+    Data received from real-time events
+
+## LiveObject
+
+`StreamSubscription<Object>` is a native flutter class that keeps track of a single object. It is a live object. In Flutter AmitySDK, any object which provides Stream is a Live Object.
+
+This function helps listen to Live Object. Whenever any property for the observed object changes, the listen callback will be triggered.
+
+### Example Usage
+
+```dart
+void listenPost(String postId) {
+  AmitySocialClient.newPostRepository()
+      .getPostStream(postId)
+      .stream
+      .listen((AmityPost post) {
+    //handle results
+  }).onError((error, stackTrace) {
+    //handle error
+  });
+}
+```
+
+## Live Collection
+
+`LiveCollection` is a generic class that keeps track of a collection of objects. It is a Live Collection. In Flutter SDK, any object that is encapsulated by LiveCollection class is a live collection.
+
+
+### Stream Observer
+
+`asStream` method can get triggered multiple times throughout the lifetime of the application as long as its associated `Stream<List<Object>>` is retained in memory.
+
+`asStream` method will be called from the main thread so you can perform any UI update-related task within the listen block itself.
+
+- If the requested data collection is stored locally on the device, the block will be called immediately with the local version of the data.
+- In parallel, a request is made to the server to fetch the latest version of the data. Once the data is returned, the listen block will be triggered again.
+- Any future changes to the data from any sources can trigger the listen block.
+
+### Pagination
+
+AmityCollection in SDK returns a maximum of pageSize items per page. It has `loadNext()` method to fetch more data. It also exposes `hasNext` property to check if the next page or previous page is present.
+
+```dart
+void loadNextPage() async {
+  if (liveCollection.hasNextPage()) {
+    liveCollection.loadNext();
+  }
+}
+```
+
+Once the next page is available, the same listen block gets triggered and you can access the collection as shown above. If you want to shrink the collection to the original first page, you can do so by calling `reset()` method on the same collection.
+
+### ListView Integration
+
+One typical usage of LiveCollection is in ListView. Below is an example of fetching a collection and updating its state in a Widget.
+
+```dart
+void initState(String channelId) {
+  messageLiveCollection = AmityChatClient.newMessageRepository()
+      .getMessages(channelId)
+      .stackFromEnd(true)
+      .getLiveCollection(pageSize: 20);
+
+  messageLiveCollection.getStreamController().stream.listen((event) {
+    // update latest results here
+    // setState(() {
+    //   amityMessages = event;
+    // });
+  });
+
+  //load first page when initiating widget
+  WidgetsBinding.instance.addPostFrameCallback((timeStamp) {
+    messageLiveCollection.loadNext();
+  });
+
+  scrollcontroller.addListener(paginationListener);
+}
+
+void paginationListener() {
+  if ((scrollcontroller.position.pixels >=
+          (scrollcontroller.position.maxScrollExtent - 100)) &&
+      messageLiveCollection.hasNextPage()) {
+    messageLiveCollection.loadNext();
+  }
+}
+```
+
+## Best Practices
+
+    **Always Cancel Subscriptions**: Prevent memory leaks by properly canceling StreamSubscriptions in the dispose method.
+
+```dart
+class MyWidget extends StatefulWidget {
+  @override
+  _MyWidgetState createState() => _MyWidgetState();
+}
+
+class _MyWidgetState extends State<MyWidget> {
+  late StreamSubscription<AmityPost> _postSubscription;
+  late LiveCollection<AmityMessage> _messageLiveCollection;
+
+  @override
+  void dispose() {
+    // Cancel stream subscriptions
+    _postSubscription.cancel();
+
+    // Reset live collections
+    _messageLiveCollection.reset();
+
+    super.dispose();
+  }
+}
+```
+
+    **Handle Stream Errors**: Always provide error callbacks for streams to prevent crashes.
+
+```dart
+_postSubscription = repository.getPost(postId).listen(
+  (post) {
+    // Handle success
+    setState(() {
+      _post = post;
+    });
+  },
+  onError: (error) {
+    // Handle error gracefully
+    setState(() {
+      _error = error.toString();
+    });
+  },
+);
+```
+
+    **Check hasNextPage**: Always verify if more pages are available before loading to avoid unnecessary API calls.
+
+```dart
+void loadMoreData() {
+  if (liveCollection.hasNextPage() && !_isLoading) {
+    setState(() {
+      _isLoading = true;
+    });
+    liveCollection.loadNext();
+  }
+}
+```
+
+    **Use StreamBuilder**: Leverage Flutter's StreamBuilder for efficient UI updates without manual setState calls.
+
+```dart
+StreamBuilder<AmityPost>(
+  stream: repository.getPost(postId),
+  builder: (context, snapshot) {
+    if (snapshot.hasError) {
+      return ErrorWidget(snapshot.error!);
+    }
+
+    if (!snapshot.hasData) {
+      return CircularProgressIndicator();
+    }
+
+    return PostWidget(post: snapshot.data!);
+  },
+);
+```
+
+## Related Resources
+
+    Understanding Dart Streams and StreamSubscriptions
+    Flutter's StreamBuilder for reactive UI updates
+
+---