TS SDK v6.0.0 Migration Guide

This guide is to provide information about breaking changes and how to migrate to the Amity TS SDK 6.0.0 version.

Installation

Using NPM

npm i @amityco/ts-sdk@^6.0.0

Using Yarn

yarn add @amityco/ts-sdk@^6.0.0

Deprecation of RunQuery / CreateQuery

Starting from 6.0.0 we recommend to use API's asynchronously. As it will soon be deprecated. Example:

// before
import { updatePost, runQuery, createQuery } from '@amityco/ts-sdk';

const query = createQuery(updatePost, 'postId', { ...updatedPost });

runQuery(query, callback);

// after v6.0.0
import { PostRepository } from '@amityco/ts-sdk'

const updatedPost = await PostRepository.updatePost('postId', { ...updatedPost });

Real Time Events

The real time events are supported via MQTT, which has a crucial difference in how it works compared to web sockets. This is, events are not broadcast-ed to all users. So this means that you only get real time event updates to those topics that you subscribe to.

Note: Some exceptions to this are message events and smart feed events. If you are unsure if subscription is required for a particular topic, check the code-snippet for that particular API for details.

There are also other limitations to getting RTE's, example: you cannot subscribe to events for a community that you are not a member of. Check documentation for full details.

You can read more about MQTT here: https://mqtt.org/

/*
 * Whenever you notice similar code block in the code snippets it indicates that you 
 * subscribing to a particular topic, which in turn let's the server know that you
 * would require real time events for this topic
*/

subscribeTopic(getUserTopic(user, SubscriptionLevels.POST), () => {
    // use callback to handle errors with event subscription
}),

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

import { PostRepository, subscribeTopic, getPostTopic } from '@amityco/ts-sdk';
import { FC, useEffect, useState } from 'react';

const disposer: 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

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 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 live objects above. For further information about Live Object, please visit Live Collection page.

Getting Real Time updates for a collection

import {
  PostRepository,
  subscribeTopic,
  getUserTopic,
  getCommunityTopic,
  SubscriptionLevels,
} from '@amityco/ts-sdk';
import { FC, useEffect, useState } from 'react';

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 and real time updates

import {
  PostRepository,
  subscribeTopic,
  getUserTopic,
  getCommunityTopic,
  SubscriptionLevels,
} from '@amityco/ts-sdk';
import { FC, useEffect, useState } from 'react';

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;
};

Introducing Repositories

Starting from 6.0.0, you will no longer be able to import individual SDK API's. You'll need to import the required API from it's respective Repositories.

Client

import { Client } from '@amityco/ts-sdk

Method	Changed To
createClient	Client.createClient
connectClient	Client.login
disconnectClient	Client.logout
subscribeTopic	Client.SubscribeTopic

UserRepository

import { UserRepository } from '@amityco/ts-sdk

Method	Changed To	Type
liveUser	UserRepository.getUser	Live Object
liveUsers	UserRepository.getUsers	Live Collection
updateUser	UserRepository.updateUser
createReport	UserRepository.flagUser
deleteReport	UserRepository.unFlagUser
liveFollowers	UserRepository.Relationship.getFollowers	Live Collection
liveFollowings	UserRepository.Relationship.getFollowings	Live Collection
liveFollowInfo	UserRepository.Relationship.getFollowInfo	Live Object
acceptFollower	UserRepository.Relationship.acceptFollower
declineFollower	UserRepository.Relationship.declineFollower
follow	UserRepository.Relationship.follow
unfollow	UserRepository.Relationship.unfollow

FileRepository

import { FileRepository } from '@amityco/ts-sdk

Method	Changed To
getFile	FileRepository.getFile
deleteFile	FileRepository.deleteFile

ReactionRepository

import { ReactionRepository } from '@amityco/ts-sdk

Method	Changed To	Type
queryReactions	ReactionRepository.getReactions	Live Collection
addReaction	ReactionRepository.addReaction
removeReaction	ReactionRepository.removeReaction

CommunityRepository

import { CommunityRepository } from '@amityco/ts-sdk

Method	Changed To	Type
createCommunity	CommunityRepository.createCommunity
joinCommunity	CommunityRepository.joinCommunity
leaveCommunity	CommunityRepository.leaveCommunity
liveCommunity	CommunityRepository.getCommunity	Live Object
liveCommunities	CommunityRepository.getCommunities	Live Collection
updateCommunity	CommunityRepository.updateCommunity
liveCommunityMembers	CommunityRepository.Membership.getMembers	Live Collection
addCommunityMembers	CommunityRepository.Membership.addMembers
removeCommunityMembers	CommunityRepository.Membership.removeMembers
addCommunityMemberRoles	CommunityRepository.Membership.addRoles
removeCommunityMemberRoles	CommunityRepository.Membership.removeRoles
liveCategories	CommunityRepository.getCategories	Live Collection
deleteCommunity	CommunityRepository.deleteCommunity
getRecommendedCommunities	CommunityRepository.getRecommendedCommunities
getTopTrendingCommunities	CommunityRepository.getTopTrendingCommunities

StreamRepository

import { StreamRepository } from '@amityco/ts-sdk

Method	Changed To
getStream	StreamRepository.getStream
queryStreams	StreamRepository.getStreams
createStream	StreamRepository.createStream

PostRepository

import { PostRepository } from '@amityco/ts-sdk

Method	Changed To	Type
createPost	PostRepository.createPost
updatePost	PostRepository.updatePost
deletePost	PostRepository.deletePost
livePost	PostRepository.getPost	Live Object
livePosts	PostRepository.getPosts	Live Collection
approvePost	PostRepository.approvePost
declinePost	PostRepository.declinePost

CommentRepository

import { CommentRepository } from '@amityco/ts-sdk

Method	Changed To	Type
createComment	CommentRepository.createComment
updateComment	CommentRepository.updateComment
deleteComment	CommentRepository.deleteComment
liveComment	CommentRepository.getComment	Live Object
liveComments	CommentRepository.getComments	Live Collection

PollRepository

import { PollRepository } from '@amityco/ts-sdk

Method	Changed To
createPoll	PollRepository.createPoll
closePoll	PollRepository.closePoll
getPoll	PollRepository.getPoll
votePoll	PollRepository.votePoll
deletePoll	PollRepository.deletePoll

ChannelRepository

import { ChannelRepository } from '@amityco/ts-sdk

Method	ChangedTo	Type
createChannel	ChannelRepository.createChannel
liveChannel	ChannelRepository.getChannel	Live Object
liveChannels	ChannelRepository.getChannels	Live Collection
joinChannel	ChannelRepository.joinChannel
leaveChannel	ChannelRepository.leaveChannel
addChannelMembers	ChannelRepository.Membership.addMembers
removeChannelMembers	ChannelRepository.Membership.removeMembers
getChannelMembers	ChannelRepository.Membership.getMembers	Live Collection

MessageRepository

import { MessageRepository } from '@amityco/ts-sdk

Method	Changed To	Type
createMessage	MessageRepository.createMessage
updateMessage	MessageRepository.updateMessage
deleteMessage	MessageRepository.deleteMessage
liveMessage	MessageRepository.getMessage	Live Object
liveMessages	MessageRepository.getMessages	Live Collection