@amityco/ts-sdk 0.0.1-02f0fa3.0

package/src/client/api/connectClient.ts

@@ -0,0 +1,63 @@
+import { getDeviceId } from '~/core/device'
+import { proxyWebsocketEvents } from '~/core/events'
+
+import { getActiveClient } from './activeClient'
+
+import { getToken } from './getToken'
+
+/**
+ * ```js
+ * import { connectClient } from '@amityco/ts-sdk/client/api'
+ * const success = await connectClient({
+ *   userId: 'XYZ123456789',
+ * })
+ * ```
+ *
+ * Connects an {@link Amity.Client} instance to ASC servers
+ *
+ * @param userId the user ID for the current session
+ * @param displayName the user's displayName for the current session
+ * @param deviceId Manual override of the user's device id (for device management)
+ * @param authToken The authentication token - necessary when network option is set to secure
+ * @returns a success boolean if connected
+ *
+ * @category Client API
+ * @async
+ */
+export const connectClient = async (params: {
+  userId: Amity.User['userId'],
+  displayName?: Amity.User['displayName'],
+  authToken?: string,
+  deviceId?: Amity.Device['deviceId'],
+}): Promise<boolean> => {
+  const client = getActiveClient()
+  client.log('client/api/connectClient', {apiKey: client.apiKey, ...params})
+
+  // default values
+  params.displayName ??= params.userId
+  params.deviceId ??= getDeviceId()
+
+  // @ts-ignore: in that particular case, typing can be
+  // ignored since we enforce default values just before.
+  const { accessToken } = await getToken(params)
+
+  // manually setup the token for http transport
+  client.http.defaults.headers.common['Authorization'] = `Bearer ${accessToken}`
+
+  // manually setup the token for ws transport
+  client.ws.io.opts.query = {token: accessToken}
+
+  // wire websocket events to our event emitter
+  proxyWebsocketEvents(client.ws, client.emitter)
+
+  // TODO: in phase 2, this should not be necessary. we should have WS
+  // to be connected "on demand" rather than "by default"
+  await new Promise(resolve => {
+    client.ws.once('connect', resolve)
+    client.ws.open()
+  })
+
+  client.userId = params.userId
+
+  return client.ws.connected
+}

package/src/client/api/createClient.ts

@@ -0,0 +1,56 @@
+import { createLogger } from '~/core/debug'
+
+import {
+  createHttpTransport,
+  createWebsocketTransport,
+} from '~/core/transports'
+
+import { createEventEmitter } from '~/core/events'
+
+import {
+  getActiveClient,
+  setActiveClient,
+} from './activeClient'
+
+/**
+ * ```js
+ * import { createClient } from '@amityco/ts-sdk'
+ * const client = createClient(apiKey, 'https://asc.server/', 'myClient')
+ * ```
+ *
+ * Creates a new {@link Amity.Client} instance
+ *
+ * @param apiKey for the {@link Amity.Client} instance
+ * @param apiEndpoint endpoint to connect to
+ * @param debugSession session's identifier for the client's logger instance
+ * @returns A {@link Amity.Client} instance
+ *
+ * @category Client API
+ **/
+export const createClient = (
+  apiKey: string,
+  apiEndpoint: string = 'https://api.amity.co',
+  debugSession: string = 'amity',
+): Amity.Client => {
+  const log = createLogger(debugSession)
+
+  log('client/api/createClient', {
+    apiKey: apiKey.replace(/.{5}$/g, 'xxxxx'),
+    apiEndpoint,
+  })
+
+  const http = createHttpTransport(apiEndpoint)
+  const ws = createWebsocketTransport(apiEndpoint)
+
+  const emitter = createEventEmitter()
+
+  const client = {
+    apiKey, log, http, ws, emitter,
+    use: () => setActiveClient(client),
+  }
+
+  try { getActiveClient() }
+  catch { setActiveClient(client) }
+
+  return client
+}

package/src/client/api/disconnectClient.ts

@@ -0,0 +1,31 @@
+import { getActiveClient } from './activeClient'
+
+/**
+ * ```js
+ * import { disconnectClient } from '@amityco/ts-sdk'
+ * const success = await disconnectClient()
+ * ```
+ *
+ * Disconnects an {@link Amity.Client} instance from ASC servers
+ *
+ * @param client The {@link Amity.Client} instance to disconnect
+ * @returns a success boolean if disconnected
+ *
+ * @category Client API
+ * @async
+ */
+export const disconnectClient = async (): Promise<boolean> => {
+  const client = getActiveClient()
+  client.log('client/api/disconnectClient')
+
+  await new Promise(resolve => {
+    client.ws.once('disconnect', resolve)
+    client.ws.disconnect()
+  })
+
+  client.emitter.all.clear()
+  client.ws.removeAllListeners()
+  client.userId = undefined
+
+  return !client.ws.connected
+}

package/src/client/api/enableCache.ts

@@ -0,0 +1,35 @@
+import { getActiveClient } from './activeClient'
+
+import { createCache } from '~/core/cache'
+import { memoryStores } from '~/core/stores'
+
+/**
+ * ```js
+ * import { enableCache } from '@amityco/ts-sdk'
+ * enableCache()
+ * ```
+ *
+ * Adds a new {@link Amity.Cache} object to an {@link Amity.Client} instance
+ *
+ * @param stores a partial dictionary of stores to be used for caching
+ *
+ * @category Client API
+ */
+export const enableCache = (
+  stores: Parameters<typeof createCache>[0] = memoryStores(
+    'user', 
+    'file', 
+    'channel', 
+    'message', 
+    'community', 
+    'post', 
+    'comment', 
+    'communityUsers', 
+    'channelUsers'
+  ),
+) => {
+  const client = getActiveClient()
+  client.log('client/api/enableCache')
+
+  client.cache = createCache(stores)
+}

package/src/client/api/getToken.ts

@@ -0,0 +1,35 @@
+import { getActiveClient } from './activeClient'
+
+import { getDeviceId, getDeviceInfo } from '~/core/device'
+
+/**
+ * Retrieves a pair of {@link Amity.Tokens} necessary for connection
+ *
+ * @param userId The userId to use to issue a token
+ * @param displayName The user's displayName
+ * @param deviceId The user's device Id (can be manually set for native users)
+ * @param authToken The authentication token - necessary when network option is set to secure
+ * @return The accessToken for the given userId
+ *
+ * @category Client API
+ * @hidden
+ */
+export const getToken = async (params: {
+  userId: Amity.User['userId'],
+  displayName: Amity.User['displayName'],
+  authToken?: string,
+  deviceId: Amity.Device['deviceId'],
+}) => {
+  const client = getActiveClient()
+  client.log('client/api/getToken', params)
+
+  const deviceInfo = await getDeviceInfo()
+
+  const { data } = await client.http.post<Amity.Tokens>('/v1/device', {
+    ...params, deviceInfo,
+  } , {
+    headers: { 'X-API-Key': client.apiKey }
+  })
+
+  return data
+}

package/src/client/api/index.ts

@@ -0,0 +1,7 @@
+export { getActiveClient } from './activeClient'
+export * from './createClient'
+export * from './connectClient'
+export * from './disconnectClient'
+export * from './isConnected'
+export * from './enableCache'
+export * from './clearCache'

package/src/client/api/isConnected.ts

@@ -0,0 +1,24 @@
+import { getActiveClient } from './activeClient'
+
+/**
+ * ```js
+ * import { isConnected } from '@amityco/ts-sdk'
+ * const connected = isConnected()
+ * ```
+ *
+ * Checks if a {@link Amity.Client} instance is connected to ASC servers
+ *
+ * @returns a success boolean if connected
+ *
+ * @category Client API
+ */
+export const isConnected = (): boolean => {
+  const client = getActiveClient()
+  client.log('client/api/isConnected', client)
+
+  return !!(
+       client.userId
+    && client.http.defaults.headers.common?.['Authorization']?.length
+    && client.ws.connected
+  )
+}

package/src/client/events/index.ts

@@ -0,0 +1 @@
+export * from './onClientDisconnected'

package/src/client/events/onClientDisconnected.ts

@@ -0,0 +1,29 @@
+import { getActiveClient } from '~/client/api'
+
+import { createEventSubscriber } from '~/core/events'
+
+/**
+ * ```js
+ * import { onClientDisconnected } from '@amityco/ts-sdk'
+ * const dispose = onClientDisconnected(reason => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when any {@link Amity.Client} have been disconnected
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Client Events
+ */
+export const onClientDisconnected = (
+  callback: Amity.Listener<void>,
+): Amity.Unsubscriber => {
+  return createEventSubscriber(
+    getActiveClient(),
+    'client/onClientDisconnected',
+    'disconnected',
+    () => callback(),
+  )
+}

package/src/comment/api/createComment.ts

@@ -0,0 +1,43 @@
+import { getActiveClient } from '~/client/api'
+
+import { decoratePayload } from '~/core/query'
+import { ingestInCache, mutateCache } from '~/core/cache'
+import { fireEvent } from '~/core/events'
+
+import { getPost } from '~/post/api/getPost'
+
+/**
+ * ```js
+ * import { createComment } from '@amityco/ts-sdk'
+ * const newComment = await createComment(bundle)
+ * ```
+ *
+ * Creates an {@link Amity.Comment}
+ *
+ * @param bundle The data necessary to create a new {@link Amity.Comment}
+ * @returns The newly created {@link Amity.Comment}
+ *
+ * @category Comment API
+ * @async
+ */
+export const createComment = async <T extends Amity.CommentContentType>(
+  bundle: Pick<Amity.Comment<T>, 'referenceType' | 'referenceId' | 'parentId' | 'data' | 'metadata'>,
+) => {
+  const client = getActiveClient()
+  client.log('comment/createComment', bundle)
+
+  const { data } = await client.http.post<Amity.CommentPayload>(
+    '/api/v3/comments', bundle,
+  )
+
+  decoratePayload(data)
+  ingestInCache(data)
+
+  const post = await getPost(bundle.referenceId)
+
+  fireEvent('v3.post.didUpdate', { posts: [post] })
+  fireEvent('v3.comment.didCreate', data)
+
+  const { comments } = data
+  return comments[0]
+}

package/src/comment/api/deleteComment.ts

@@ -0,0 +1,40 @@
+import { getActiveClient } from '~/client/api'
+import { fireEvent } from '~/core/events'
+
+import { getComment } from './getComment'
+
+import { getPost } from '~/post/api/getPost'
+
+/**
+ * ```js
+ * import { deleteComment } from '@amityco/ts-sdk'
+ * const success = await deleteComment('foobar')
+ * ```
+ *
+ * Deletes a {@link Amity.Comment}
+ *
+ * @param commentId The {@link Amity.Comment} ID to delete
+ * @return A success boolean if the {@link Amity.Comment} was deleted
+ *
+ * @category Comment API
+ * @async
+ */
+export const deleteComment = async (
+  commentId: Amity.Comment['commentId'],
+) => {
+  const client = getActiveClient()
+  client.log('comment/deleteComment', commentId)
+
+  // API-FIX: This endpoint has not been implemented yet.
+  await client.http.delete<{ success: boolean }>(
+    `/api/v3/comments/${commentId}`,
+  )
+
+  const deleted = await getComment(commentId)
+  const post = await getPost(deleted.referenceId)
+
+  fireEvent('v3.post.didUpdate', { posts: [post] })
+  fireEvent('v3.comment.didDelete', { comments: [deleted] })
+
+  return deleted
+}

package/src/comment/api/getComment.ts

@@ -0,0 +1,59 @@
+import { getActiveClient } from '~/client/api'
+
+import { ingestInCache, pullFromCache } from '~/core/cache'
+import { decoratePayload } from '~/core/query'
+
+/**
+ * ```js
+ * import { getComment } from '@amityco/ts-sdk'
+ * const comment = await getComment('foobar')
+ * ```
+ *
+ * Fetches a {@link Amity.Comment} object
+ *
+ * @param commentId the ID of the {@link Amity.Comment} to fetch
+ * @returns the associated {@link Amity.Comment} object
+ *
+ * @category Comment API
+ * @async
+ */
+export const getComment = async (
+  commentId: Amity.Comment['commentId']
+) => {
+  const client = getActiveClient()
+  client.log('comment/getComment', commentId)
+
+  // API-FIX: endpoint should not be /list, parameters should be querystring.
+  const { data } = await client.http.get<Amity.CommentPayload>(
+    `/api/v3/comments/${commentId}`,
+  )
+
+  decoratePayload(data)
+  ingestInCache(data)
+
+  const { comments } = data
+  return comments.find(comment => comment.commentId === commentId)!
+}
+
+/**
+ * ```js
+ * import { getComment } from '@amityco/ts-sdk'
+ * const comment = getComment.locally('foobar')
+ * ```
+ *
+ * Fetches a {@link Amity.Comment} object
+ *
+ * @param commentId the ID of the {@link Amity.Comment} to fetch
+ * @returns the associated {@link Amity.Comment} object
+ *
+ * @category Comment API
+ */
+getComment.locally = (
+  commentId: Amity.Comment['commentId']
+) => {
+  const client = getActiveClient()
+  client.log('comment/getComment.locally', commentId)
+
+  const [comment] = pullFromCache('comment', commentId) ?? []
+  return comment
+}

package/src/comment/api/getComments.ts

@@ -0,0 +1,63 @@
+import { getActiveClient } from '~/client/api'
+
+import { decoratePayload } from '~/core/query'
+import { ingestInCache, pullFromCache } from '~/core/cache'
+import { toRecord } from '~/core/model'
+
+/**
+ * ```js
+ * import { getComments } from '@amityco/ts-sdk'
+ * const comments = await getComments(['foo', 'bar'])
+ * ```
+ *
+ * Fetches a collection of {@link Amity.Comment} objects
+ *
+ * @param commentIds the IDs of the {@link Amity.Comment} to fetch
+ * @returns the associated collection of {@link Amity.Comment} objects
+ *
+ * @category Comment API
+ * @async
+ */
+export const getComments = async (
+  commentIds: Amity.Comment['commentId'][],
+) => {
+  const client = getActiveClient()
+  client.log('comment/getComments', commentIds)
+
+  // API-FIX: endpoint should not be /list, parameters should be querystring.
+  const { data } = await client.http.get<Amity.CommentPayload>(
+    `/api/v3/comments/list`,
+    { params: { commentIds } },
+  )
+
+  decoratePayload(data)
+  ingestInCache(data)
+
+  const { comments } = data
+  return toRecord(comments)
+}
+
+/**
+ * ```js
+ * import { getComments } from '@amityco/ts-sdk'
+ * const comments = getComments.locally(['foo', 'bar'])
+ * ```
+ *
+ * Fetches a collection of {@link Amity.Comment} objects from cache
+ *
+ * @param commentIds the IDs of the {@link Amity.Comment} to fetch
+ * @returns the associated collection of {@link Amity.Comment} objects
+ *
+ * @category Comment API
+ */
+getComments.locally = (
+  commentIds: Amity.Comment['commentId'][]
+) => {
+  const client = getActiveClient()
+  client.log('comment/getComments.locally', commentIds)
+
+  const cached = pullFromCache('comment', ...commentIds) ?? []
+
+  if (cached?.length === commentIds.length)
+    return toRecord(cached)
+}

package/src/comment/api/index.ts

@@ -0,0 +1,7 @@
+export * from './queryComments'
+export * from './getComments'
+export * from './getComment'
+
+export * from './createComment'
+export * from './updateComment'
+export * from './deleteComment'

package/src/comment/api/queryComments.ts

@@ -0,0 +1,169 @@
+import { getActiveClient } from '~/client/api'
+
+import {
+  decoratePayload,
+  filterByPropEquality,
+  sortBySegmentNumber,
+  toPage,
+  toToken,
+} from '~/core/query'
+
+import { ingestInCache, pullFromCache } from '~/core/cache'
+import { toRecord } from '~/core/model'
+
+/**
+ * ```js
+ * import { queryComments } from '@amityco/ts-sdk'
+ * const comments = await queryComments({ postId })
+ * ```
+ *
+ * Queries a paginable list of {@link Amity.Comment} objects
+ *
+ * @param query The query parameters
+ * @returns A page of {@link Amity.Comment} objects
+ *
+ * @category Comment API
+ * @async
+ */
+export const queryComments = async (query: {
+  referenceType: Amity.Comment['referenceType'],
+  referenceId: Amity.Comment['referenceId'],
+  parentId?: Amity.Comment['commentId'] | null
+  hasFlag?: boolean
+  isDeleted?: Amity.Comment['isDeleted']
+  page?: Amity.Page
+}) => {
+  const client = getActiveClient()
+  client.log('comment/queryComments', query)
+
+  const { page, ...params } = query
+
+  const filterByParentId = query.parentId !== undefined
+
+  // API-FIX: parameters should be querystring. (1)
+  // API-FIX: backend should answer Amity.Response (2)
+  // const { data } = await client.http.get<Amity.Response<Amity.PagedResponse<Amity.CommentPayload>>>(
+  const { data } = await client.http.get<Amity.CommentPayload & Amity.Pagination>(`/api/v3/comments`, {
+    params: {
+      ...params,
+      //      filterByParentId, API-FIX: backend does not support this boolean LOL. what the hell seriously.
+      options: {
+        token: toToken(page, 'afterbefore'),
+      },
+    },
+  })
+
+  // API-FIX: backend should answer Amity.Response (2)
+  // const { paging, comments } = unwrapPayload(data)
+  const { paging, ...response } = data
+
+  decoratePayload(response as unknown as Record<string, Object[]>)
+  ingestInCache(response as unknown as Record<string, Object[]>)
+
+  const prevPage = toPage(paging.previous)
+  const nextPage = toPage(paging.next)
+
+  const { comments } = response
+  return { data: toRecord(comments), prevPage, nextPage }
+}
+
+/**
+ * ```js
+ * import { queryComments } from '@amityco/ts-sdk'
+ * const comments = queryComments.locally({ postId })
+ * ```
+ *
+ * Queries a paginable list of {@link Amity.Comment} objects from cache
+ *
+ * @param query The query parameters
+ * @returns comments
+ *
+ * @category Comment API
+ */
+queryComments.locally = (
+  query: Parameters<typeof queryComments>[0],
+) => {
+  const client = getActiveClient()
+  client.log('post/queryComments.locally', query)
+
+  const {
+    referenceId,
+    referenceType,
+    parentId,
+    isDeleted,
+    page = { before: 0, limit: 5 },
+  } = query
+
+  if (isNaN(page.after!) && isNaN(page.before!))
+    page.before = 0;
+
+  if (isNaN(page.limit))
+    page.limit = 5
+
+  let comments: Amity.Comment[] = pullFromCache('comment') ?? []
+
+  // no cache
+  if (!comments.length)
+    return
+
+  // filter
+  comments = filterByPropEquality(comments, 'referenceId', referenceId)
+  comments = filterByPropEquality(comments, 'referenceType', referenceType)
+  comments = filterByPropEquality(comments, 'parentId', parentId)
+  comments = filterByPropEquality(comments, 'isDeleted', isDeleted)
+
+  // no interesting cache
+  if (!comments.length)
+    return
+
+  // sort
+  comments = comments.sort(sortBySegmentNumber)
+
+  // paging
+  // API-FIX we can't reuse proper page because the message page is done
+  // by segmentNumber which is sadly unique to the entire platform.
+  // this part is copied and adapted from sliceByPaging function
+
+  const afterIndex = !isNaN(page.after!)
+    ? comments.findIndex(({ segmentNumber }) => segmentNumber === page.after! + 1)
+    : 0
+
+  const beforeIndex = !isNaN(page.before!) && page.before !== 0
+    ? comments.findIndex(({ segmentNumber }) => segmentNumber === page.before! - 1) + 1
+    : comments.length
+
+  if (afterIndex < 0 || beforeIndex < 0)
+    return
+
+  let slice = comments.slice(
+    afterIndex !== -1 ? afterIndex : 0,
+    beforeIndex !== -1 ? beforeIndex : undefined,
+  )
+
+  // nothing left after slicing
+  if (!slice.length)
+    return
+
+  if (!isNaN(page.after!) && !isNaN(page.before!)) {
+    // do nothing
+  } else if (!isNaN(page.after!)) {
+    slice = slice.slice(0, page.limit)
+  } else if (!isNaN(page.before!)) {
+    slice = slice.slice(-page.limit)
+  }
+
+  for (let i = 0; i < slice.length - 1; i++)
+    if (slice[i].segmentNumber !== slice[i + 1].segmentNumber - 1)
+      return
+
+  const prevPage = slice[0].segmentNumber > 1
+    ? { before: slice[0].segmentNumber, limit: page.limit }
+    : undefined
+
+  const nextPage = {
+    after: slice[slice.length - 1].segmentNumber,
+    limit: page.limit,
+  }
+
+  return { data: toRecord(slice), nextPage, prevPage }
+}