@amityco/ts-sdk 0.0.1-beta.1 → 0.0.1-beta.13

package/src/community/api/joinCommunity.ts

@@ -0,0 +1,41 @@
+import { getActiveClient } from '~/client/api'
+
+import { ingestInCache } from '~/cache/api/ingestInCache'
+import { fireEvent } from '~/core/events'
+
+/**
+ * ```js
+ * import { joinCommunity } from '@amityco/ts-sdk'
+ * const isJoined = await joinCommunity('foobar')
+ * ```
+ *
+ * Joins a {@link Amity.Community} object
+ *
+ * @param communityId the {@link Amity.Community} to join
+ * @returns A success boolean if the {@link Amity.Community} was joined
+ *
+ * @category Community API
+ * @async
+ */
+export const joinCommunity = async (
+  communityId: Amity.Community['communityId']
+): Promise<boolean> => {
+  const client = getActiveClient()
+  client.log('community/joinCommunity', communityId)
+
+  const { data } = await client.http.post<Amity.CommunityMembershipPayload>(
+    `/api/v3/communities/${communityId}/join`,
+  )
+
+  const cachedAt = client.cache && Date.now()
+  if (client.cache) ingestInCache(data, { cachedAt })
+
+  fireEvent('community.joined', data)
+
+  const { communityUsers } = data
+
+  return !!communityUsers.find(communityUser => (
+    communityUser.communityId === communityId
+    && communityUser.communityMembership === 'member'
+  ))
+}

package/src/community/api/leaveCommunity.ts

@@ -0,0 +1,41 @@
+import { getActiveClient } from '~/client/api'
+
+import { ingestInCache } from '~/cache/api/ingestInCache'
+import { fireEvent } from '~/core/events'
+
+/**
+ * ```js
+ * import { leaveCommunity } from '@amityco/ts-sdk'
+ * const isLeft = await leaveCommunity('foobar')
+ * ```
+ *
+ * Leaves a {@link Amity.Community} object
+ *
+ * @param communityId the {@link Amity.Community} to leave
+ * @returns A success boolean if {@link Amity.Community} was left
+ *
+ * @category Community API
+ * @async
+ */
+export const leaveCommunity = async (
+  communityId: Amity.Community['communityId']
+): Promise<boolean> => {
+  const client = getActiveClient()
+  client.log('community/leaveCommunity', communityId)
+
+  const { data } = await client.http.delete<Amity.CommunityMembershipPayload>(
+    `/api/v3/communities/${communityId}/leave`,
+  )
+
+  const cachedAt = client.cache && Date.now()
+  if (client.cache) ingestInCache(data, { cachedAt })
+
+  fireEvent('community.left', data)
+
+  const { communityUsers } = data
+
+  return !!communityUsers.find(communityUser => (
+    communityUser.communityId === communityId
+    && communityUser.communityMembership !== 'member'
+  ))
+}

package/src/community/api/queryCommunities.ts

@@ -0,0 +1,98 @@
+import { getActiveClient } from '~/client/api'
+
+import { toPage, toToken } from '~/core/query'
+import { pushToCache } from '~/cache/api'
+import { ingestInCache } from '~/cache/api/ingestInCache'
+import { getResolver } from '~/core/model'
+
+/**
+ * ```js
+ * import { queryCommunities } from '@amityco/ts-sdk'
+ * const communities = await queryCommunities()
+ * ```
+ *
+ * Queries a paginable list of {@link Amity.Community} objects
+ * Search is performed by displayName such as `.startsWith(search)`
+ *
+ * @param query The query parameters
+ * @returns A page of {@link Amity.Community} objects
+ *
+ * @category Community API
+ * @async
+ */
+export const queryCommunities = async (
+  query?: {
+    displayName?: string
+    membership?: 'all' | 'member' | 'notMember'
+    categoryId?: Amity.Category['categoryId'],
+    isDeleted?: Amity.Community['isDeleted'],
+    hasFlag?: boolean,
+    tags?: Amity.Taggable['tags'],
+    sortBy?: ('displayName' | 'firstCreated' | 'lastCreated')
+    page?: Amity.Page
+  }
+): Promise<Amity.Cached<Amity.Paged<Amity.Community>>> => {
+  const client = getActiveClient()
+  client.log('channel/queryCommunities', query)
+
+  // safe decapsulation
+  const {
+    page,
+    displayName,
+    membership,
+    ...params
+  } = query ?? {}
+
+  // API-FIX: parameters should be querystring.
+  // API-FIX: backend doesnt answer Amity.Response
+  // const { data } = await client.http.get<Amity.Response<Amity.PagedResponse<CommunityPayload>>>(
+  const { data } = await client.http.get<Amity.CommunityPayload & Amity.Pagination>(
+    `/api/v3/communities`, { params: {
+      ...params,
+      keyword: displayName,
+      filter: membership,
+      options: {
+        token: toToken(page, 'skiplimit')
+      }
+    } }
+  )
+
+  const { paging, ...payload } = data
+  const { communities } = payload
+
+  const cachedAt = client.cache && Date.now()
+
+  if (client.cache) {
+    ingestInCache(payload as Amity.CommunityPayload, { cachedAt })
+
+    const cacheKey = ['community', 'query', { ...params, options: { ...page } } as Amity.Serializable]
+    pushToCache(cacheKey, { communities: communities.map(getResolver('community')), paging })
+  }
+
+  const nextPage = toPage(paging.next)
+  const prevPage = toPage(paging.previous)
+
+  return { data: communities, cachedAt, prevPage, nextPage }
+}
+
+/**
+ * ```js
+ * import { queryCommunities } from '@amityco/ts-sdk'
+ * const communities = queryCommunities.locally()
+ * ```
+ *
+ * Queries a paginable list of {@link Amity.Community} objects from cache
+ *
+ * @param query The query parameters
+ * @returns communities
+ *
+ * @category Community API
+ */
+queryCommunities.locally = (
+  query: Parameters<typeof queryCommunities>[0],
+) => {
+  const client = getActiveClient()
+  client.log('community/queryCommunities.locally', query)
+
+  // TODO
+}

package/src/community/api/queryCommunityMembers.ts

@@ -0,0 +1,77 @@
+import { getActiveClient } from '~/client/api'
+
+import { toPage, toToken } from '~/core/query'
+import { ingestInCache } from '~/cache/api/ingestInCache'
+
+/**
+ * ```js
+ * import { queryCommunityMembers } from '@amityco/ts-sdk'
+ * const communityMembers = await queryCommunityMembers({ communityId: 'foo' })
+ * ```
+ *
+ * Queries a paginable list of {@link Amity.CommunityUser} objects
+ *
+ * @param query The query parameters
+ * @returns A page of {@link Amity.CommunityUser} objects
+ *
+ * @category Community API
+ * @async
+ **/
+export const queryCommunityMembers = async (query: {
+  communityId: string
+  membership?: ('banned' | 'member')[]
+  roles?: string[]
+  sortBy?: 'firstCreated' | 'lastCreated'
+  page?: Amity.Page
+}): Promise<Amity.Cached<Amity.Paged<Amity.Membership<"community">>>> => {
+  const client = getActiveClient()
+  client.log('community/queryCommunityMembers', query)
+
+  const { page, communityId, ...params } = query ?? {}
+
+  const { data } = await client.http.get<
+    Amity.CommunityMembershipPayload & Amity.Pagination
+  >(`/api/v3/communities/${communityId}/users`, {
+    params: {
+      ...params,
+      options: {
+        token: toToken(page, 'skiplimit'),
+      },
+    },
+  })
+
+  const { paging, ...payload } = data
+  const { communityUsers } = payload
+
+  const cachedAt = client.cache && Date.now()
+  if (client.cache) {
+    ingestInCache(payload as Amity.CommunityMembershipPayload, { cachedAt })
+  }
+
+  const nextPage = toPage(paging.next)
+  const prevPage = toPage(paging.previous)
+
+  return { data: communityUsers, nextPage, prevPage }
+}
+
+/**
+ * ```js
+ * import { queryCommunityMembers } from '@amityco/ts-sdk'
+ * const communityMembers = await queryCommunityMembers(query)
+ * ```
+ *
+ * Queries a paginable list of {@link Amity.Post} objects from cache
+ *
+ * @param query The query parameters
+ * @returns posts
+ *
+ * @category Post API
+ */
+queryCommunityMembers.locally = (
+  query: Parameters<typeof queryCommunityMembers>[0]
+) => {
+  const client = getActiveClient()
+  client.log('community/queryCommunityMembers', query)
+
+  // TODO
+}

package/src/community/api/removeCommunityMembers.ts

@@ -0,0 +1,43 @@
+import { getActiveClient } from '~/client/api'
+
+import { ingestInCache } from '~/cache/api/ingestInCache'
+import { fireEvent } from '~/core/events'
+
+/**
+ * ```js
+ * import { removeCommunityMembers } from '@amityco/ts-sdk'
+ * const updated = await removeCommunityMembers(communityId, ['foo', 'bar'])
+ * ```
+ *
+ * Removes a list of {@link Amity.User} from a {@link Amity.Channel}
+ *
+ * @param communityId The ID of the {@link Amity.Community} to edit
+ * @param userIds The list of IDs {@link Amity.User} to remove
+ * @returns A success boolean if the list of {@link Amity.User} were removed from the {@link Amity.Community}
+ *
+ * @category Community API
+ * @async
+ */
+export const removeCommunityMembers = async (
+  communityId: Amity.Community['communityId'],
+  userIds: Amity.User['userId'][]
+): Promise<boolean> => {
+  const client = getActiveClient()
+  client.log('community/removeCommunityMembers', communityId, userIds)
+
+  const { data } = await client.http.delete<Amity.CommunityMembershipPayload>(
+    `/api/v3/communities/${communityId}/users`,
+    { data: { communityId, userIds } }
+  )
+
+  if (client.cache) ingestInCache(data)
+
+  fireEvent('community.userRemoved', data)
+
+  const { communityUsers } = data
+  return !!communityUsers.find(
+    communityUser =>
+      communityUser.communityId === communityId &&
+      communityUser.communityMembership !== 'member'
+  )
+}

package/src/community/api/removeCommunityMembersRole.ts

@@ -0,0 +1,41 @@
+import { getActiveClient } from '~/client/api'
+
+import { ingestInCache } from '~/cache/api/ingestInCache'
+
+/**
+ * ```js
+ * import { removeCommunityMembersRole } from '@amityco/ts-sdk'
+ * const updated = await removeCommunityMembersRole(communityId,  'foo', ['bar'])
+ * ```
+ *
+ * Removes an {@link Amity.Role} from a list of {@link Amity.User} on a {@link Amity.Community}
+ *
+ * @param communityId The ID of the {@link Amity.Community} to perform
+ * @param role The ID of the {@link Amity.Role} to apply
+ * @param userId Array of IDs of the {@link Amity.User} to perform
+ * @returns A success boolean if the {@link Amity.Role} were removed from list of {@link Amity.User} in the {@link Amity.Community}
+ *
+ * @category Community API
+ * @async
+ */
+export const removeCommunityMembersRole = async (
+  communityId: Amity.Community['communityId'],
+  roleId: Amity.Role['roleId'],
+  userIds: Amity.User['userId'][]
+): Promise<boolean> => {
+  const client = getActiveClient()
+  client.log('community/removeCommunityMembersRole', communityId, roleId, userIds)
+
+  const { data } = await client.http.delete<Amity.CommunityMembershipPayload>(
+    `/api/v3/communities/${communityId}/users/roles`,
+    { data: { communityId, role: roleId, userIds } }
+  )
+
+  if (client.cache) ingestInCache(data)
+
+  const { communityUsers } = data
+  return !!communityUsers.find(
+    communityUser =>
+    communityUser.communityId === communityId && !communityUser.roles.includes(roleId)
+  )
+}

package/src/community/api/updateCommunity.ts

@@ -0,0 +1,43 @@
+import { getActiveClient } from '~/client/api'
+
+import { ingestInCache } from '~/cache/api/ingestInCache'
+import { fireEvent } from '~/core/events'
+
+/**
+ * ```js
+ * import { updateCommunity } from '@amityco/ts-sdk'
+ * const updated = await updateCommunity(communityId, { displayName: 'foobar' })
+ * ```
+ *
+ * Updates an {@link Amity.Community}
+ *
+ * @param communityId The ID of the {@link Amity.Community} to edit
+ * @param patch The patch data to apply
+ * @returns the updated {@link Amity.Community} object
+ *
+ * @category Community API
+ * @async
+ */
+export const updateCommunity = async (
+  communityId: Amity.Community['communityId'],
+  patch: Patch<Amity.Community, 'displayName' | 'description' | 'avatarFileId' | 'tags' | 'metadata'>,
+): Promise<Amity.Cached<Amity.Community>> => {
+  const client = getActiveClient()
+  client.log('community/updateCommunity', communityId, patch)
+
+  const { data } = await client.http.put<Amity.CommunityPayload>(
+    `/api/v3/communities/${communityId}`, patch,
+  )
+
+  const cachedAt = client.cache && Date.now()
+  if (client.cache) ingestInCache(data, { cachedAt })
+
+  fireEvent('community.updated', data)
+
+  const { communities } = data
+
+  return {
+    data: communities.find(community => community.communityId === communityId)!,
+    cachedAt,
+  }
+}

package/src/community/events/index.ts

@@ -0,0 +1,11 @@
+export * from './onCommunityCreated'
+export * from './onCommunityUpdated'
+export * from './onCommunityDeleted'
+
+export * from './onCommunityJoined'
+export * from './onCommunityLeft'
+
+export * from './onCommunityUserAdded'
+export * from './onCommunityUserRemoved'
+export * from './onCommunityUserBanned'
+export * from './onCommunityUserUnbanned'

package/src/community/events/onCommunityCreated.ts

@@ -0,0 +1,19 @@
+import { createCommunityEventSubscriber } from './utils'
+
+/**
+ * ```js
+ * import { onCommunityCreated } from '@amityco/ts-sdk'
+ * const dispose = onCommunityCreated(community => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when a {@link Amity.Community} have been created
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Community Events
+ */
+export const onCommunityCreated = (callback: Amity.Listener<Amity.Community>) =>
+  createCommunityEventSubscriber('community.created', callback)

package/src/community/events/onCommunityDeleted.ts

@@ -0,0 +1,19 @@
+import { createCommunityEventSubscriber } from './utils'
+
+/**
+ * ```js
+ * import { onCommunityDeleted } from '@amityco/ts-sdk'
+ * const dispose = onCommunityDeleted(community => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when a {@link Amity.Community} has been deleted
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Community Events
+ */
+export const onCommunityDeleted = (callback: Amity.Listener<Amity.Community>) =>
+  createCommunityEventSubscriber('community.deleted', callback)

package/src/community/events/onCommunityJoined.ts

@@ -0,0 +1,19 @@
+import { createCommunityMemberEventSubscriber } from './utils'
+
+/**
+ * ```js
+ * import { onCommunityJoined } from '@amityco/ts-sdk'
+ * const dispose = onCommunityJoined((community, member) => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when a {@link Amity.Community} has been joined
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Community Events
+ */
+export const onCommunityJoined = (callback: (community: Amity.Community, member: Amity.Membership<'community'>) => void) =>
+  createCommunityMemberEventSubscriber('community.joined', callback)

package/src/community/events/onCommunityLeft.ts

@@ -0,0 +1,19 @@
+import { createCommunityMemberEventSubscriber } from './utils'
+
+/**
+ * ```js
+ * import { onCommunityLeft } from '@amityco/ts-sdk'
+ * const dispose = onCommunityLeft((community, member) => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when a {@link Amity.Community} has been left
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Community Events
+ */
+export const onCommunityLeft = (callback: (community: Amity.Community, member: Amity.Membership<'community'>) => void) =>
+  createCommunityMemberEventSubscriber('community.left', callback)

package/src/community/events/onCommunityUpdated.ts

@@ -0,0 +1,19 @@
+import { createCommunityEventSubscriber } from './utils'
+
+/**
+ * ```js
+ * import { onCommunityUpdated } from '@amityco/ts-sdk'
+ * const dispose = onCommunityUpdated(community => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when a {@link Amity.Community} has been updated
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Community Events
+ */
+export const onCommunityUpdated = (callback: Amity.Listener<Amity.Community>) =>
+  createCommunityEventSubscriber('community.updated', callback)

package/src/community/events/onCommunityUserAdded.ts

@@ -0,0 +1,19 @@
+import { createCommunityMemberEventSubscriber } from './utils'
+
+/**
+ * ```js
+ * import { onCommunityUserAdded } from '@amityco/ts-sdk'
+ * const dispose = onCommunityUserAdded((community, member) => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when a user has been added to a {@link Amity.Community}
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Community Events
+ */
+export const onCommunityUserAdded = (callback: (community: Amity.Community, member: Amity.Membership<'community'>) => void) =>
+  createCommunityMemberEventSubscriber('community.userAdded', callback)

package/src/community/events/onCommunityUserBanned.ts

@@ -0,0 +1,19 @@
+import { createCommunityMemberEventSubscriber } from './utils'
+
+/**
+ * ```js
+ * import { onCommunityUserBanned } from '@amityco/ts-sdk'
+ * const dispose = onCommunityUserBanned((community, member) => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when a user has been banned from a {@link Amity.Community}
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Community Events
+ */
+export const onCommunityUserBanned = (callback: (community: Amity.Community, member: Amity.Membership<'community'>) => void) =>
+  createCommunityMemberEventSubscriber('community.userBanned', callback)

package/src/community/events/onCommunityUserRemoved.ts

@@ -0,0 +1,19 @@
+import { createCommunityMemberEventSubscriber } from './utils'
+
+/**
+ * ```js
+ * import { onCommunityUserRemoved } from '@amityco/ts-sdk'
+ * const dispose = onCommunityUserRemoved((community, member) => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when a user has been removed from a {@link Amity.Community}
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Community Events
+ */
+export const onCommunityUserRemoved = (callback: (community: Amity.Community, member: Amity.Membership<'community'>) => void) =>
+  createCommunityMemberEventSubscriber('community.userRemoved', callback)

package/src/community/events/onCommunityUserUnbanned.ts

@@ -0,0 +1,19 @@
+import { createCommunityMemberEventSubscriber } from './utils'
+
+/**
+ * ```js
+ * import { onCommunityUserUnbanned } from '@amityco/ts-sdk'
+ * const dispose = onCommunityUserUnbanned((community, member) => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when a user has been unbanned from a {@link Amity.Community}
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Community Events
+ */
+export const onCommunityUserUnbanned = (callback: (community: Amity.Community, member: Amity.Membership<'community'>) => void) =>
+  createCommunityMemberEventSubscriber('community.userUnbanned', callback)

package/src/community/events/utils.ts

@@ -0,0 +1,100 @@
+import { getActiveClient } from '~/client/api'
+import { ingestInCache } from '~/cache/api/ingestInCache'
+import { createEventSubscriber } from '~/core/events'
+import { pullFromCache } from '~/cache/api'
+import { getResolver } from '~/core/model'
+
+export const createCommunityEventSubscriber = (
+  event: keyof Amity.MqttCommunityMessageEvents,
+  callback: Amity.Listener<Amity.Community>
+) => {
+  const client = getActiveClient()
+
+  const filter = (payload: Amity.CommunityPayload) => {
+    if (!client.cache) {
+      // TODO: here we are missing specific properties here!
+      callback(payload.communities[0])
+    } else {
+      ingestInCache(payload)
+
+      const community = pullFromCache<Amity.Community>(['community', 'get', payload.communities[0].communityId])!
+
+      callback(community.data)
+    }
+  }
+
+  return createEventSubscriber(
+    client,
+    event,
+    event,
+    filter
+  )
+}
+
+function hasPermission(member: Amity.Membership<'community'>, payload: Amity.CommunityMembershipPayload, permission: string) {
+  if (member.permissions.some(x => x === permission)) {
+    return true;
+  }
+
+  return payload.users!
+    .find(user => user.userId === member.userId)!
+    .permissions.some(x => x === permission)
+}
+
+function getEventRelatedMember(
+  event: keyof Amity.MqttCommunityUserMessageEvents,
+  payload: Amity.CommunityMembershipPayload
+)  {
+  if (event === 'community.joined' || event === 'community.left') {
+    return payload.communityUsers![0];
+  }
+
+  // NOTE: backend returns the one who took the action and the one on whom
+  // the action was taken. We need the 2nd one
+  if (event === 'community.userRemoved') {
+    return payload.communityUsers!.filter(x => x.communityMembership === 'none')[0]
+  }
+
+  if (event === 'community.userBanned') {
+    return payload.communityUsers!.filter(x => x.communityMembership === 'banned')[0]
+  }
+
+  // NOTE: it might be that in certain edge cases permission check won't be enough
+  if (event === 'community.userUnbanned') {
+    return payload.communityUsers!.filter(x => !hasPermission(x, payload, 'BAN_COMMUNITY_USER'))[0]
+  }
+
+  return payload.communityUsers!.filter(x => !hasPermission(x, payload, 'ADD_COMMUNITY_USER'))[0]
+}
+
+export const createCommunityMemberEventSubscriber = (
+  event: keyof Amity.MqttCommunityUserMessageEvents,
+  callback: (community: Amity.Community, member: Amity.Membership<'community'>) => void,
+) => {
+  const client = getActiveClient()
+
+  const filter = (payload: Amity.CommunityMembershipPayload) => {
+    if (!client.cache) {
+      // TODO: here we are missing specific properties here!
+      callback(payload.communities[0], getEventRelatedMember(event, payload))
+    } else {
+      ingestInCache(payload)
+
+      const community = pullFromCache<Amity.Community>(['community', 'get', payload.communities[0].communityId])!
+      const member = pullFromCache<Amity.Membership<'community'>>([
+        'communityUsers',
+        'get',
+        getResolver('communityUsers')(getEventRelatedMember(event, payload))
+      ])!
+
+      callback(community.data, member.data)
+    }
+  }
+
+  return createEventSubscriber(
+    client,
+    event,
+    event,
+    filter
+  )
+}