@amityco/social-plus-vise 0.14.28 → 1.0.0

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

@@ -0,0 +1,264 @@
+# TypeScript Live Objects/Collections
+
+> Live Objects are supported in the TypeScript SDK with subscribable objects and collections for real-time data synchronization
+
+In the social.plus TypeScript SDK, we have the concept of **Live Object** and **Live Collection**.
+
+Live Object is represented by an instance of social.plus Object. It helps to observe changes in a single object whereas Live Collection is represented by an instance of social.plus LiveCollection. It helps to observe changes in a list of objects.
+
+SDK handles lots of data received from various sources. Data can be present in the local cache. It may also be queried from the server or received from 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 and become out of sync.
+
+Live Object and Live Collection help in syncing data so you will always get the most recent one. New data gets automatically collected every time when there is an update and the user need not refresh to get the recent data.
+
+Examples: `Amity.Post` for single objects or `Amity.LiveCollection<Amity.Post>` for collections.
+
+## 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.
+
+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 subscribable objects and collections.
+
+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
+
+## Live Object
+
+Although live objects were introduced prior to v6. All getter methods for singular objects (example getPost) will now return a subscribe-able object.
+
+This means that if an object gets updated and you have subscribed to real-time events, the object will get updated automatically via real-time events.
+
+If for your use case, you don't require any real-time updates, you can unsubscribe immediately.
+
+For further information about Live Object, please visit Live Object page.
+
+### Getting Real Time Updates for an Object
+
+```typescript
+import { PostRepository, subscribeTopic, getPostTopic } from '@amityco/ts-sdk';
+import { FC, useEffect, useState } from 'react';
+
+const disposers: Amity.Unsubscriber[] = [];
+
+const GetPost: FC<{ postId: string }> = ({ postId }) => {
+  const [post, setPost] = useState<Amity.Post>();
+
+  useEffect(() => {
+
+    const unsubscribePost = PostRepository.getPost(postId, ({ data }) => {
+     const { post, loading, error } = data
+
+     if (post) {
+       /*
+       * This step is important if you wish to recieve real time updates
+       * Here, you are letting the server know that you wish to recieve real time
+       * updates regarding this post
+       */
+       disposers.push(subscribeTopic(getPostTopic(post)))
+
+       setPost(post)
+     }
+    });
+
+    disposers.push(unsubscribePost);
+  }, [postId]);
+
+  return null;
+};
+```
+
+### Getting the object only once
+
+```typescript
+import { PostRepository } from '@amityco/ts-sdk';
+import { FC, useEffect, useState } from 'react';
+
+const GetPostOnce: FC<{ postId: string }> = ({ postId }) => {
+  const [post, setPost] = useState<Amity.Post>();
+
+  useEffect(() => {
+    const unsubscribePost = PostRepository.getPost(postId, ({ data }) => {
+     const { post, loading, error } = data
+
+     if (post) {       
+       setPost(post)
+     }
+    });
+
+    unsubscribePost()
+  }, [postId]);
+
+  return null;
+};
+
+## Live Collection
+
+Although live collections were introduced prior to v6. All query methods for the collection of objects (example getPosts) will now return a subscribe-able collection.
+
+This means that if an object in the collection gets updated and you have subscribed to real-time events, the collection will get updated automatically via real-time events.
+
+If for your use case, you don't require any real-time updates, you can unsubscribe immediately. Similar to the live objects above.
+
+<Info>
+For further information about Live Collection, please visit Live Collection page.
+</Info>
+
+### Getting Real-Time updates for a collection
+
+```typescript
+  PostRepository,
+  subscribeTopic,
+  getUserTopic,
+  getCommunityTopic,
+  SubscriptionLevels,
+} from '@amityco/ts-sdk';
+
+const disposers: Amity.Unsubscriber[] = [];
+
+const GetPosts: FC<{ targetId: string; targetType: string }> = 
+({ targetId, targetType }) => {
+  const [posts, setPosts] = useState<Amity.Post[]>();
+
+  useEffect(() => {
+    const unsubscribe = PostRepository.getPosts(
+      { targetId, targetType },
+      ({ data: posts, onNextPage, hasNextPage, loading, error }) => {
+        setPosts(posts);
+        /*
+         * this is only required if you want real time updates for each
+         * post in the collection
+         */
+        subscribePostTopic(targetType, targetId);
+      },
+    );
+
+    disposers.push(unsubscribe);
+
+    return () => {
+      disposers.forEach(fn => fn());
+    };
+  });
+
+  return null;
+};
+
+const subscribePostTopic = (targetType: string, targetId: string) => {
+  if (isSubscribed) return;
+
+  if (targetType === 'user') {
+    const user = {} as Amity.User; // use getUser to get user by targetId
+    disposers.push(
+      subscribeTopic(getUserTopic(user, SubscriptionLevels.POST), () => {
+        // use callback to handle errors with event subscription
+      }),
+    );
+    return;
+  }
+
+  if (targetType === 'community') {
+    // use getCommunity to get community by targetId
+    const community = {} as Amity.Community; 
+    disposers.push(
+      subscribeTopic(getCommunityTopic(community, SubscriptionLevels.POST), () => {
+        // use callback to handle errors with event subscription
+      }),
+    );
+  }
+};
+```
+
+### Getting paginated collection without real-time updates
+
+```typescript
+  PostRepository,
+  subscribeTopic,
+  getUserTopic,
+  getCommunityTopic,
+  SubscriptionLevels,
+} from '@amityco/ts-sdk';
+
+const GetPosts: FC<{ targetId: string; targetType: string }> = 
+({ targetId, targetType }) => {
+  const [posts, setPosts] = useState<Amity.Post[]>();
+
+  useEffect(() => {
+    const unsubscribe = PostRepository.getPosts(
+      { targetId, targetType },
+      ({ data: posts, onNextPage, hasNextPage, loading, error }) => {
+        if (posts)
+          setPosts(posts);
+
+        // to get next page use onNextPage()
+      },
+    );
+
+    unsubscribe()
+  });
+
+  return null;
+};
+
+## Best Practices
+
+    **Always Clean Up**: Prevent memory leaks by properly disposing of subscriptions and unsubscribers.
+
+```typescript
+// Use a disposer pattern
+const disposers: Amity.Unsubscriber[] = [];
+
+useEffect(() => {
+  // Add subscriptions
+  disposers.push(PostRepository.getPost(postId, callback));
+  disposers.push(subscribeTopic(getPostTopic(post)));
+
+  return () => {
+    // Clean up all subscriptions
+    disposers.forEach(dispose => dispose());
+  };
+}, []);
+```
+
+    **Subscribe Selectively**: Only subscribe to real-time events when you need live updates to optimize performance.
+
+```typescript
+// For static content, unsubscribe immediately
+const unsubscribe = PostRepository.getPost(postId, callback);
+unsubscribe(); // No real-time updates needed
+
+// For live content, keep subscription active
+const unsubscribe = PostRepository.getPost(postId, callback);
+disposers.push(unsubscribe); // Keep for real-time updates
+```
+
+    **Handle Subscription Errors**: Always provide error callbacks for topic subscriptions.
+
+```typescript
+disposers.push(
+  subscribeTopic(getPostTopic(post), (error) => {
+    if (error) {
+      console.error('Subscription failed:', error);
+      // Handle fallback or retry logic
+    }
+  })
+);
+```
+
+    **Debounce Updates**: For frequently updating collections, consider debouncing UI updates.
+
+```typescript
+import { debounce } from 'lodash';
+
+const debouncedSetPosts = debounce(setPosts, 300);
+
+PostRepository.getPosts(query, ({ data: posts }) => {
+  if (posts) {
+    debouncedSetPosts(posts);
+  }
+});
+```
+
+---

package/docs-cache/social-plus-sdk/core-concepts/realtime-communication/push-notifications/register-and-unregister-push-notifications-on-a-device.mdx

@@ -0,0 +1,191 @@
+# Device Registration & Management
+
+> Complete guide to registering and managing push notification devices across iOS, Android, React Native, Flutter, and Web platforms
+
+Manage push notification device registrations to ensure users receive timely updates across all their devices. Handle registration, unregistration, and device lifecycle management with proper error handling and state management.
+
+Device registration requires an active AmityClient instance and a valid push notification token. The SDK uses a "last write wins" strategy for device management.
+
+## Overview
+
+Device registration is essential for delivering push notifications to your users. The social.plus SDK provides comprehensive device management capabilities across all platforms, ensuring reliable notification delivery while maintaining security and user privacy.
+
+### Key Concepts
+
+- **Device Token**: Unique identifier for each app installation (FCM token for Android, APNs token for iOS)
+- **User Association**: Each device can be associated with only one user at a time
+- **Token Lifecycle**: Tokens can change and require re-registration
+- **Platform Differences**: Each platform has unique token requirements and behaviors
+
+
+**Platform Setup Required**: Complete the platform-specific push notification setup before implementing device registration:
+
+- **iOS**: [iOS Setup Guide](./setup/ios-setup)
+- **Android**: [Android Setup Guide](./setup/android-setup)  
+- **React Native**: [React Native Setup Guide](./setup/react-native-setup)
+- **Flutter**: [Flutter Setup Guide](./setup/flutter-setup)
+- **Web**: [Web Setup Guide](./setup/web-setup)
+
+## Device Registration
+
+### Prerequisites
+
+Before registering a device, ensure you have:
+
+    AmityClient instance properly initialized and authenticated
+    Platform-specific push notification token obtained
+    Push notification permissions granted by user
+    Active internet connection for registration
+
+### Platform-Specific Registration
+
+
+```swift iOS
+do {
+    let result = try await client.registerPushNotification(withDeviceToken: "<token>")
+} catch {
+    // Handle error here
+}
+```
+
+```kotlin Android
+fun registerNotification(fcmToken: String) {
+    AmityCoreClient.registerPushNotification()
+        .doOnComplete {
+            // Void
+        }
+        .doOnError {
+            // Exception
+        }
+        .subscribe()
+}
+```
+```dart Flutter
+void registerNotification(String fcmToken) {
+  /* 
+  ************ IMPORTANT ************
+  Example of getting token from firebase.
+  Please check the platform before getting the token and send token as per platform. 
+    FirebaseMessaging messaging = FirebaseMessaging.instance;
+    if (Platform.isIOS) {
+      final fcmToken = await messaging.getAPNSToken();
+    } else {
+      final fcmToken = await messaging.getToken();
+    }
+
+  */
+  AmityCoreClient.registerDeviceNotification(fcmToken)
+      .then((value) => {
+            //success
+          })
+      .onError((error, stackTrace) => {
+            //handle error
+          });
+}
+```
+
+
+## Device Unregistration
+
+### When to Unregister
+
+Unregister devices in these scenarios:
+
+    When user logs out of the app
+    When user deletes their account
+    When user disables notifications
+    Before app uninstallation (if possible)
+
+### Unregistration Implementation
+
+Unlike the registration, unregistering for push does not require the AmityClient instance to be associated with any user, therefore you can unregister the device from receiving push notifications as soon as the AmityClient has been initialized with a valid API key.
+
+- if a valid `userId` is passed, social.plus's backend will stop sending push notifications to this device only if the currently active push notification associated with this device is also associated with that user. No action is taken otherwise.
+- if no `userId` is passed, social.plus's backend will stop sending push notifications to this device.
+
+
+{/* doc-as-test: skip (truly-illustrative: contains '...' ellipsis placeholder — pseudocode scaffold, not compilable Swift) */}
+```swift iOS
+// unregister from receiving push notifications for the user with id `userId`
+client.unregisterDeviceForPushNotification(forUserId: userId) { [weak self] _, success, error in
+  ...
+}
+
+// unregister from receiving push notifications for this device
+client.unregisterDeviceForPushNotification(forUserId: nil) { [weak self] _, success, error in
+  ...
+}
+```
+
+```kotlin Android
+fun unregisterPushNotification(userId: String) {
+    AmityCoreClient.unregisterPushNotification()
+        .doOnComplete {
+            // Void
+        }
+        .doOnError {
+            // Exception
+        }
+        .subscribe()
+}
+```
+
+```dart Flutter
+void unregisterNotification() {
+  AmityCoreClient.unregisterDeviceNotification()
+      .then((value) => {
+            //success
+          })
+      .onError((error, stackTrace) => {
+            //handle error
+          });
+}
+```
+
+
+## Troubleshooting
+
+    **Common Registration Issues**:
+
+    1. **Invalid Token**: Ensure token is properly formatted and not expired
+    2. **Network Issues**: Implement retry logic with exponential backoff
+    3. **Authentication**: Verify AmityClient is properly authenticated
+
+
+    **Token-Related Problems**:
+
+    1. **Token Refresh**: Handle token changes properly
+    2. **Platform Differences**: iOS requires APNs token availability
+    3. **Timing Issues**: Ensure token is available before registration
+    4. **Storage Issues**: Verify token persistence works correctly
+
+    **iOS Specific**:
+    - Requires APNs token before FCM token
+    - Simulator doesn't support push notifications
+    - Debug builds may have limitations
+
+    **Android Specific**:
+    - FCM service account required
+    - Android 13+ runtime permissions
+    - Google Play Services dependency
+
+    **React Native**:
+    - Platform-specific token handling
+    - Background message handling
+    - Proper cleanup of listeners
+
+    **Flutter**:
+    - Platform channel communication
+    - Firebase plugin configuration
+    - State management across rebuilds
+
+## Related Resources
+
+    Complete iOS APNs certificate setup and configuration
+    Android FCM configuration and implementation
+    Cross-platform React Native push notification setup
+    Flutter push notification implementation guide
+
+**Important**: Always test device registration and token refresh scenarios thoroughly before production deployment. Each platform has unique requirements and edge cases.
+
+---

package/docs-cache/social-plus-sdk/core-concepts/realtime-communication/push-notifications/settings/overview.mdx

@@ -0,0 +1,43 @@
+# Push Notification Settings
+
+> Configure user, channel, and community-level push notification preferences and controls.
+
+Configure push notification preferences at three levels: user, channel, and community. Settings at each level control which events trigger notifications and can be overridden or restricted by higher-level policies.
+
+## Available Settings
+
+    Personal notification preferences and user-level controls
+
+    Channel-specific notification rules and moderation settings
+
+    Community-wide notification policies and administrative controls
+
+## Settings Hierarchy
+
+Understanding the notification settings hierarchy is crucial for proper implementation:
+
+1. **Community Level**: Global policies and restrictions
+2. **Channel Level**: Channel-specific rules and preferences
+3. **User Level**: Personal preferences and overrides
+
+User settings typically have the highest priority, unless restricted by community or channel policies.
+
+## Key Features
+
+- **Granular Control**: Fine-grained notification preferences
+- **Smart Defaults**: Intelligent default settings based on user behavior
+- **Bulk Management**: Efficient settings management for administrators
+- **Real-time Updates**: Instant application of setting changes
+- **Compliance**: Privacy and regulation compliance features
+
+## Best Practices
+
+- Provide clear, user-friendly setting descriptions
+- Implement smart defaults to reduce configuration burden
+- Respect user privacy and consent preferences
+- Test notification delivery across different settings combinations
+- Monitor settings usage and optimize based on user behavior
+
+Start with [User Settings](/social-plus-sdk/core-concepts/realtime-communication/push-notifications/settings/user-settings) to understand personal preferences, then explore channel and community-level controls.
+
+---