Amity Social Cloud Typescript SDK

Getting Started

• With npm: npm install @amityco/ts-sdk
• With yarn: yarn add @amityco/ts-sdk

Runtime support

• Modern browsers (es2017 compliant)
• NodeJS (via esm imports)
• React-Native

Creating a client instance

To connect your users to our platform, you need to create a client instance and connect it.

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

(async () => {
  const sessionHandler: Amity.SessionHandler = {
    sessionWillRenewAccessToken(renewal: Amity.Renewal) {
      renewal.renew();
      /*
       * If using an auth token
       *
       * try {
       *  renew.renewWithAuthToken(authToken)
       * } catch() {
       *  sdk will try to renew again at a later time
       *
       *  renew.unableToRetrieveAuthToken()
       * }
       */
    },
  };
  const client = Client.createClient(API_KEY, API_REGION);

  let isConnected = await Client.login({ userId: USER_ID }, sessionHandler);
})();

The API_KEY and API_REGION are given at the time you create an application in the Amity Portal.

You can listen to disconnection by using the onClientDisconnected function:

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

const unsub = Client.onClientDisconnected(() => (isConnected = false));

The unsub's return value is a dispose function which is used to clean the memory of your client's application. It's been designed to fit perfectly with React, in a useEffect such as:

useEffect(() => onClientConnected(() => setConnected(false)), [])

## Going further

### Domain types

All the necessary types are automatically exposed in the `Amity` namespace. As long as you import the SDK once, the namespace will be available in your workspace. You can start to type `Amity.` and see the list of types in your intellisense after having imported the SDK in any file of your project.

### Subscribing to real time events

We expose a couple of functions for your to receive simply the events that could fire from our servers, for example, if another user would change their display name, or if a channel would receive a new message.

The `subscribeTopic` method retuns an unsubscriber that can be called on clean up to stop recieving further events.

```ts
import { subscribeTopic, getUserTopic } from '@amityco/ts-sdk'

const unsub = subscribeTopic(getUserTopic({} as Amity.User))

Observe an object using Live Object

For an 'all-in-one' approach, we expose live objects, which allow to fetch an object and register to its changes all at once. This has been designed to fit with React's useState and useEffect:

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

const Component = ({ userId }: { userId: string }) => {
  const [user, setUser] = useState<Amity.User>({})

  useEffect(() => UserRepository.getUser(userId, ({ data: user, loading, error }) => {
    // ensure you call unsub() on cleanup or unmount
    const unsub = subscribeTopic(getUserTopic(user))

    setUser(user)
  }), [userId])

  return <div>{JSON.stringify(user, null, 2)}
}

Observe a collection using Live Collection

Similar to the concept of live object, we expose live collection, which allow to fetch a collection and register to its changes all at once. This has been designed to fit with React's useState and useEffect:

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

const Component = () => {
  const [users, setUsers] = useState<Amity.User[]>({})

  useEffect(() => UserRepository.getUsers({}, ({ data, loading, error, nextPage, hasNextPage }) => {
    // ensure you call unsub() on cleanup or unmount
    // Subscribe to each user in collection for getting real time updates

    setUsers(users)
  }), [userId])

  return <div>{JSON.stringify(user, null, 2)}
}

Documentation

To see the comprehensive documentation please visit our documentation page.

If you have any questions, you can visit our forum.