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

package/src/community/observers/index.ts

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

package/src/community/observers/observeCommunity.ts

@@ -0,0 +1,86 @@
+import { createQuery, runQuery } from '~/core/query/query'
+
+import { getActiveClient } from '~/client/api'
+
+import { getCommunity } from '../api'
+
+import {
+  onCommunityUpdated,
+  onCommunityDeleted,
+  onCommunityJoined,
+  onCommunityLeft,
+  onCommunityUserAdded,
+  onCommunityUserRemoved,
+  onCommunityUserBanned,
+  onCommunityUserUnbanned
+} from '../events'
+
+/**
+ * ```js
+ * import { observeCommunity } from '@amityco/ts-sdk'
+ *
+ * let community = {}
+ * const dispose = observeCommunity(communityId, updated => community = updated)
+ * ```
+ *
+ * Observe all mutation on a given {@link Amity.Community}
+ *
+ * @param communityId the ID of the community to observe
+ * @param callback the function to call when new data are available
+ * @returns An {@link Amity.Unsubscriber} function to run when willing to stop observing the community
+ *
+ * @category Community Observer
+ */
+export const observeCommunity = <Events extends ['onFetch', 'onUpdate', 'onDelete', 'onJoin', 'onLeft', 'onUserAdded', 'onUserRemoved', 'onUserBanned', 'onUserUnbanned']>(
+  communityId: string,
+  callback: Amity.ObjectListener<Amity.Snapshot<Amity.Community | undefined>, Events>
+): Amity.Unsubscriber => {
+  const { log } = getActiveClient()
+
+  const timestamp = Date.now()
+  log(`observeCommunity(tmpid: ${timestamp}) > listen`)
+
+  // wrapper function to make sure
+  const router = (
+    result: Amity.Snapshot<Amity.Community | undefined>,
+    action: Events[number]
+  ) => {
+    if (callback instanceof Function) return callback(result)
+
+    if (action !== 'onFetch') callback.onEvent?.(action, result)
+
+    callback[action]?.(result)
+  }
+
+  const realtimeRouter = (
+    result: Amity.Snapshot<Amity.Community>,
+    action: Events[number]
+  ) => {
+    if (result.data?.communityId !== communityId) return
+
+    router(result, action)
+  }
+
+  const disposers: Amity.Unsubscriber[] = []
+
+  disposers.push(
+    onCommunityUpdated(data => realtimeRouter({ data, loading: false, origin: 'event' }, 'onUpdate')),
+    onCommunityDeleted(data => realtimeRouter({ data, loading: false, origin: 'event' }, 'onDelete')),
+    onCommunityJoined(data => realtimeRouter({ data, loading: false, origin: 'event' }, 'onJoin')),
+    onCommunityLeft(data => realtimeRouter({ data, loading: false, origin: 'event' }, 'onLeft')),
+    onCommunityUserAdded(data => realtimeRouter({ data, loading: false, origin: 'event' }, 'onUserAdded')),
+    onCommunityUserRemoved(data => realtimeRouter({ data, loading: false, origin: 'event' }, 'onUserRemoved')),
+    onCommunityUserBanned(data => realtimeRouter({ data, loading: false, origin: 'event' }, 'onUserBanned')),
+    onCommunityUserUnbanned(data => realtimeRouter({ data, loading: false, origin: 'event' }, 'onUserUnbanned')),
+  )
+
+  runQuery(
+    createQuery(getCommunity, communityId),
+    result => (result.data || result.error) && router(result, 'onFetch')
+  )
+
+  return () => {
+    log(`observeCommunity(tmpid: ${timestamp}) > dispose`)
+    disposers.forEach(fn => fn())
+  }
+}

package/src/core/debug.ts

@@ -0,0 +1,26 @@
+import debug from 'debug'
+
+/**
+ * Creates a pre-configured logger instance
+ *
+ * @param session The name of the debug session
+ * @returns A pre-configured logger function
+ *
+ * @category Debug
+ * @hidden
+ */
+export const createLogger = (session?: string) => {
+  const active = (
+      `${session?.trim()}`.length > 0
+    && process?.env?.NODE_ENV !== 'production'
+  )
+
+  const logger = debug(session!)
+
+  const print = (topic: string, ...args: any[]) => {
+    active && logger(topic, args)
+  }
+
+  print.__instance__ = logger
+  return print
+}

package/src/core/device.ts

@@ -0,0 +1,38 @@
+// TODO: find a way to uniquely identify the device
+// import { getStorage } from './storage'
+
+/** @hidden */
+const VERSION = '11.0.0'
+
+/** @hidden */
+export const getDeviceId = () => {
+  // here maybe put some auto detection of the device id based on if it's react or not?
+  // anyhow we let consumer branch out if they want, but it doesn't mean we shouldn't try to be nice
+  // and do things automatically
+  // https://www.npmjs.com/package/react-native-device-info#getuniqueid
+  // how to make sure that the react native package will not be included when build is for web
+  return `ascWebSdk#${Math.random().toString(16)}`
+}
+
+/** @hidden */
+export const getDeviceModel = () => {
+  if (process?.versions?.node)
+    return process.versions.node
+
+  if (navigator)
+    return `${navigator.product.toLowerCase()}#${navigator.userAgent ?? 'unknown_agent'}`
+
+  return 'unknown_model'
+}
+
+/** @hidden */
+export const getDeviceInfo = (): Amity.Device['deviceInfo'] => {
+  const model = getDeviceModel()
+
+  return {
+    version: VERSION,
+    // TODO: replace with: kind: process.versions ? 'node' : 'web', when backend has fixed this
+    kind: 'web',
+    model,
+  }
+}

package/src/core/errors.ts

@@ -0,0 +1,92 @@
+/**
+ * Generic ASC error
+ * @category Errors
+ */
+export class ASCError extends Error {
+  readonly type: string = 'ASC'
+  readonly timestamp: number = Date.now()
+
+  /**
+   * @param message A custom error message
+   * @param code A normalized error code
+   * @param level A normalized failure level descriptor
+   */
+  constructor(
+    message: string,
+    public readonly code: Amity.ErrorCode,
+    public readonly level: Amity.ErrorLevel,
+  ) {
+    super(`Amity SDK (${code}): ${message}`)
+
+    if (Error.captureStackTrace)
+      Error.captureStackTrace(this, ASCError)
+  }
+}
+
+/**
+ * API level error
+ * @category Errors
+ */
+export class ASCApiError extends ASCError {
+  /**
+   * @param code A normalized error code
+   * @param level A normalized failure level descriptor
+   */
+  constructor(
+    message: string,
+    code: Amity.ErrorCode,
+    level: Amity.ErrorLevel,
+  ) {
+    super(message, code, level)
+  }
+}
+
+/**
+ * Unexpected error
+ * @category Errors
+ */
+export class ASCUnknownError extends ASCError {
+  /**
+   * @param code A normalized error code
+   * @param level A normalized failure level descriptor
+   */
+  constructor(
+    code: Amity.ErrorCode = Amity.ClientError.UNKNOWN_ERROR,
+    level: Amity.ErrorLevel = Amity.ErrorLevel.FATAL,
+  ) {
+    super('Unexpected error', code, level)
+  }
+}
+
+/**
+ * Network related error
+ * @category Errors
+ */
+export class ASCConnectionError extends ASCError {
+  /**
+   * @param message A custom error message
+   */
+  constructor(
+    public readonly event: string,
+    message: string = 'SDK client is having connection issues',
+  ) {
+    super(
+      `${message} (${event})`,
+      event === 'disconnected' ? Amity.ClientError.DISCONNECTED : Amity.ClientError.CONNECTION_ERROR,
+      Amity.ErrorLevel.ERROR,
+    )
+  }
+}
+
+/**
+ * Input sanitization related error
+ * @category Errors
+ */
+export class ASCInvalidParameterError extends ASCError {
+  /**
+   * @param message A custom error message
+   */
+  constructor(message: string) {
+    super(message, Amity.ClientError.INVALID_PARAMETERS, Amity.ErrorLevel.ERROR)
+  }
+}

package/src/core/events.ts

@@ -0,0 +1,138 @@
+import mitt from 'mitt'
+
+import { getActiveClient } from '~/client/api/activeClient'
+
+// need to sync up the list
+const WS_EVENTS = [
+  'disconnected',
+  'error',
+  'connect_error',
+  'reconnect_error',
+  'reconnect_failed',
+
+  'v3.channel.didUpdate',
+  'v3.channel.didUpdate',
+  'v3.channel.didJoin',
+  'v3.channel.didLeave',
+  'v3.channel.didAddUsers',
+  'v3.channel.didRemoveUsers',
+  'v3.channel.didBan',
+  'v3.channel.didUnban',
+
+  'v3.message.didCreate',
+  'v3.message.didUpdate',
+  'v3.message.didDelete',
+] as const
+
+const MQTT_EVENTS = [
+  'connect',
+  'message',
+  'disconnect',
+  'error',
+  'close',
+  'end',
+  'reconnect'
+] as const;
+
+/** @hidden */
+export const createEventEmitter = () => {
+  return mitt<Amity.Events>()
+}
+
+/**
+ * Wraps the websocket events into the client's event emitter for
+ * abstraction of transport.
+ *
+ * @param ws A websocket connection to listen from
+ * @param emitter An event emitter to wire the events to
+ *
+ * @category Transport
+ * @hidden
+ */
+export const proxyWebsocketEvents = (ws: Amity.Client['ws'], emitter: Amity.Client['emitter']) => {
+  WS_EVENTS.forEach(event => {
+    ws.on(event, (param: Amity.Events[typeof event]) => emitter.emit(event, param))
+  })
+}
+
+export const proxyMqttEvents = (mqttClient: Amity.Client['mqtt'], emitter: Amity.Client['emitter']) => {
+  MQTT_EVENTS.forEach(event => {
+    mqttClient.on(event, (...params: any[]) => emitter.emit(event, params.length === 1 ? params[0] : params))
+  })
+
+  // @ts-ignore
+  mqttClient.on('message', (topic: string, payload: Buffer) => {
+    const message = JSON.parse(payload.toString());
+
+    emitter.emit(message.eventType, message.data)
+  })
+}
+
+/**
+ * Standardize the subscription of SSE through web sockets
+ *
+ * @param client The current client for which to subscribe the event to
+ * @param namespace A unique name for the logger
+ * @param event The websocket event name
+ * @param fn A wrapper for the callback.
+ * @returns A dispose function to unsubscribe to the event
+ *
+ * @category Transport
+ * @hidden
+ */
+export const createEventSubscriber = <T extends keyof Amity.Events>(
+  client: Amity.Client,
+  namespace: string,
+  event: T,
+  fn: Amity.Listener<Amity.Events[T]>,
+): Amity.Unsubscriber => {
+  const { log, emitter } = client
+
+  const timestamp = Date.now()
+  log(`${namespace}(tmpid: ${timestamp}) > listen`)
+
+  const handler = (...payload: Parameters<typeof fn>) => {
+    log(`${namespace}(tmpid: ${timestamp}) > trigger`, payload)
+    fn(...payload)
+  }
+
+  emitter.on(event, handler)
+
+  return () => {
+    log(`${namespace}(tmpid: ${timestamp}) > dispose`)
+    emitter.off(event, handler)
+  }
+}
+
+export const createMqttMessageSubscriber = <T extends keyof Amity.Events>(
+  client: Amity.Client,
+  namespace: string,
+  event: string,
+  fn: (params: Object) => void,
+): Amity.Unsubscriber => {
+  return createEventSubscriber(
+    client,
+    namespace,
+    'message',
+    ([topic, message]) => {
+      const payload = JSON.parse(message.toString());
+
+      if (payload.eventType === event) {
+        fn(payload.data);
+      }
+    }
+  )
+}
+
+/**
+ * Wrapper around dispatch event
+ *
+ * @hidden
+ */
+export const fireEvent = <T extends keyof Amity.Events>(
+  event: T,
+  payload: Amity.Events[T],
+) => {
+  const { emitter } = getActiveClient()
+  setTimeout(() => { emitter.emit(event, payload) }, 0)
+}

package/src/core/model/idResolvers.ts

@@ -0,0 +1,37 @@
+/**
+ * Manually computed type which links each key with a function
+ * used to return the object's unique id. The type is computed
+ * to avoid using any and give some typing security at the
+ * resolver's level.
+ */
+ type Resolvers<T extends Amity.Domain[] = Amity.Domain[]> = {
+  [K in T[number]]: (model: Amity.Minimal[K]) => string
+}
+
+/** @hidden */
+const idResolvers: Resolvers = {
+  user: ({ userId }) => userId,
+  file: ({ fileId }) => fileId,
+  role: ({ roleId }) => roleId,
+
+  channel: ({ channelId }) => channelId,
+  channelUsers: ({ channelId, userId }) => `${channelId}#${userId}`,
+  message: ({ messageId }) => messageId,
+
+  community: ({ communityId }) => communityId,
+  communityUsers: ({ communityId, userId }) => `${communityId}#${userId}`,
+  post: ({ postId }) => postId,
+  comment: ({ commentId }) => commentId,
+
+  stream: ({ streamId }) => streamId,
+}
+
+/**
+ * Retrieve the id resolver matching a domain name
+ *
+ * @param name the domain name for the resolve
+ * @returns an idResolver function for the given domain name
+ */
+ export const getResolver = <T extends Amity.Domain>(name: T) => (
+  idResolvers[name]
+)

package/src/core/model/identifyModel.ts

@@ -0,0 +1,53 @@
+/**
+ * Manually computed type which links each key with array
+ * of matching keys as values. The type is computed rather
+ * than letting string[] to help identifying mistakes while
+ * adding new models.
+ * @hidden
+ */
+ type Criterias<T extends Amity.Domain[] = Amity.Domain[]> = {
+  [K in T[number]]: (keyof Amity.Model[K])[]
+}
+
+/**
+ * Identification criterias
+ *
+ * As key, the name of the identified model ;
+ * As value, the list of properties to consider a given model as of type
+ *
+ * Used as source of truth for {@link identifyModel}
+ *
+ * @hidden
+ */
+const CRITERIAS: Criterias  = {
+  file: ['fileId', 'attributes'],
+  user: ['userId', 'avatarFileId'],
+  role: ['roleId'],
+  channel: ['channelId', 'rateLimit'],
+  channelUsers: ['channelId', 'userId', 'membership'],
+  message: ['messageId'],
+  community: ['communityId', 'onlyAdminCanPost'],
+  communityUsers: ['userId', 'communityId', 'communityMembership'],
+  post: ['postId', 'feedId'],
+  comment: ['commentId', 'referenceId'],
+  stream: ['streamId'],
+}
+
+/** @hidden */
+const hasKeys = (object: Record<string, unknown>, needles: string[]) => {
+  const haystack = Object.keys(object)
+  return needles.every(needle => haystack.includes(needle))
+}
+
+/**
+ * Finds the name of the store for a given unknown model
+ *
+ * @param model one of the {@link Amity.Model} to identify
+ * @returns the name of the corresponding store
+ */
+export const identifyModel = (model: Record<string, unknown>) => {
+  // we cannot avoid "as" in here because Object.entries does not
+  // allow anything else than "string" as key in the iterator type
+  const criterias = Object.entries(CRITERIAS) as [Amity.Domain, string[]][]
+  return criterias.find(([_, keys]) => hasKeys(model, keys))?.[0]
+}

package/src/core/model/index.ts

@@ -0,0 +1,23 @@
+export * from './idResolvers'
+export * from './identifyModel'
+
+/**
+ * A map of v3 response keys to a store name.
+ * @hidden
+ */
+ export const PAYLOAD2MODEL: Record<string, Amity.Domain> = {
+  users: 'user',
+  files: 'file',
+  roles: 'role',
+
+  channels: 'channel',
+  channelUsers: 'channelUsers',
+  messages: 'message',
+
+  communities: 'community',
+  communityUsers: 'communityUsers',
+  posts: 'post',
+  postChildren: 'post',
+  comments: 'comment',
+  videoStreamings: 'stream',
+}

package/src/core/network.ts

@@ -0,0 +1,14 @@
+export const API_ENDPOINT = {
+  EU: 'eu',
+  SG: 'sg',
+  US: 'us',
+} as const
+
+export enum UrlTemplate {
+  HTTP = 'https://api.{region}.amity.co',
+  MQTT = 'wss://sse.{region}.amity.co:443/mqtt',
+}
+
+export const getUrlFromTemplate = ( template: UrlTemplate, region: string ) => {
+  return template.replace( '{region}', region);
+}

package/src/core/query/filtering.ts

@@ -0,0 +1,17 @@
+// Note:
+// this file should contain a suite of filtering utilities to help the
+// local version of the query functions.
+
+/**
+ * Filter a given collection with strict equality against a param
+ *
+ * @param collection the collection to filter
+ * @param key the key of the collection's items to challenge
+ * @param value the expected value
+ * @returns a filtered collection with items only matching the criteria
+ *
+ * @hidden
+ */
+export const filterByPropEquality = <T = {}>(collection: T[], key: keyof T, value: any) => (
+  value !== undefined ? collection.filter(item => item[key] === value) : collection
+)

package/src/core/query/index.ts

@@ -0,0 +1,4 @@
+export * from './query'
+export * from './filtering'
+export * from './sorting'
+export * from './paging'