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.

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.

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

MethodChanged To

createClient

Client.createClient

connectClient

Client.login

disconnectClient

Client.logout

subscribeTopic

Client.SubscribeTopic

UserRepository

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

MethodChanged ToType

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

MethodChanged To

getFile

FileRepository.getFile

deleteFile

FileRepository.deleteFile

ReactionRepository

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

MethodChanged ToType

queryReactions

ReactionRepository.getReactions

Live Collection

addReaction

ReactionRepository.addReaction

removeReaction

ReactionRepository.removeReaction

CommunityRepository

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

MethodChanged ToType

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

MethodChanged To

getStream

StreamRepository.getStream

queryStreams

StreamRepository.getStreams

createStream

StreamRepository.createStream

PostRepository

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

MethodChanged ToType

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

MethodChanged ToType

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

MethodChanged To

createPoll

PollRepository.createPoll

closePoll

PollRepository.closePoll

getPoll

PollRepository.getPoll

votePoll

PollRepository.votePoll

deletePoll

PollRepository.deletePoll

ChannelRepository

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

MethodChangedToType

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

MethodChanged ToType

createMessage

MessageRepository.createMessage

updateMessage

MessageRepository.updateMessage

deleteMessage

MessageRepository.deleteMessage

liveMessage

MessageRepository.getMessage

Live Object

liveMessages

MessageRepository.getMessages

Live Collection

Last updated