@amityco/ts-sdk 0.0.1-beta.2 → 0.0.1-beta.22

package/src/channel/events/onChannelMemberAdded.ts

@@ -0,0 +1,32 @@
+import { getActiveClient } from '~/client/api';
+import { createEventSubscriber } from '~/core/events';
+
+import { ingestInCache } from '~/cache/api/ingestInCache';
+
+/**
+ * ```js
+ * import { onChannelMemberAdded } from '@amityco/ts-sdk'
+ * const dispose = onChannelMemberAdded((channel, member) => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when any {@link Amity.User} has been added to any {@link Amity.Channel}
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Channel Events
+ */
+export const onChannelMemberAdded = (
+  callback: (channel: Amity.Channel, member: Amity.Membership<'channel'>) => void,
+) => {
+  const client = getActiveClient();
+
+  const filter = (payload: Amity.ChannelMembershipPayload) => {
+    ingestInCache(payload);
+    callback(payload.channels[0], payload.channelUsers[0]);
+  };
+
+  return createEventSubscriber(client, 'onChannelMemberAdded', 'v3.channel.didAddUsers', filter);
+};

package/src/channel/events/onChannelMemberRemoved.ts

@@ -0,0 +1,37 @@
+import { getActiveClient } from '~/client/api';
+import { createEventSubscriber } from '~/core/events';
+
+import { ingestInCache } from '~/cache/api/ingestInCache';
+
+/**
+ * ```js
+ * import { onChannelMemberRemoved } from '@amityco/ts-sdk'
+ * const dispose = onChannelMemberRemoved((channel, member) => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when any {@link Amity.User} has been removed from any {@link Amity.Channel}
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Channel Events
+ */
+export const onChannelMemberRemoved = (
+  callback: (channel: Amity.Channel, member: Amity.Membership<'channel'>) => void,
+) => {
+  const client = getActiveClient();
+
+  const filter = (payload: Amity.ChannelMembershipPayload) => {
+    ingestInCache(payload);
+    callback(payload.channels[0], payload.channelUsers[0]);
+  };
+
+  return createEventSubscriber(
+    client,
+    'onChannelMemberRemoved',
+    'v3.channel.didRemoveUsers',
+    filter,
+  );
+};

package/src/channel/events/onChannelUpdated.ts

@@ -0,0 +1,30 @@
+import { getActiveClient } from '~/client/api';
+import { createEventSubscriber } from '~/core/events';
+
+import { ingestInCache } from '~/cache/api/ingestInCache';
+
+/**
+ * ```js
+ * import { onChannelUpdated } from '@amityco/ts-sdk'
+ * const dispose = onChannelUpdated(channel => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when any {@link Amity.Channel} have been updated
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category Channel Events
+ */
+export const onChannelUpdated = (callback: Amity.Listener<Amity.Channel>) => {
+  const client = getActiveClient();
+
+  const filter = (payload: Amity.ChannelPayload) => {
+    ingestInCache(payload);
+    callback(payload.channels[0]);
+  };
+
+  return createEventSubscriber(client, 'onChannelUpdated', 'v3.channel.didUpdate', filter);
+};

package/src/channel/observers/observeChannel.ts

@@ -0,0 +1,84 @@
+import { createQuery, runQuery } from '~/core/query/query';
+
+import { getActiveClient } from '~/client/api';
+
+import { getChannel } from '../api';
+
+import {
+  onChannelUpdated,
+  onChannelDeleted,
+  onChannelJoined,
+  onChannelLeft,
+  onChannelMemberAdded,
+  onChannelMemberRemoved,
+} from '../events';
+
+/**
+ * ```js
+ * import { observeChannel } from '@amityco/ts-sdk'
+ *
+ * let channel = {}
+ * const dispose = observeChannel(channelId, ({ data }) => channel = data)
+ * ```
+ *
+ * Observe all mutation on a given {@link Amity.Channel}
+ *
+ * @param channelId the ID of the channel 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 channel
+ *
+ * @category Channel Observer
+ */
+export const observeChannel = <
+  Events extends [
+    'onFetch',
+    'onUpdate',
+    'onDelete',
+    'onJoin',
+    'onLeft',
+    'onMemberAdded',
+    'onMemberRemoved',
+  ],
+>(
+  channelId: string,
+  callback: Amity.ObjectListener<Amity.Snapshot<Amity.Channel>, Events>,
+): Amity.Unsubscriber => {
+  const { log } = getActiveClient();
+
+  const timestamp = Date.now();
+  log(`observeChannel(tmpid: ${timestamp}) > listen`);
+
+  // wrapper function to make sure
+  const router = (result: Amity.Snapshot<Amity.Channel>, action: Events[number]) => {
+    // filter function
+    if (result.data?.channelId !== channelId) return;
+
+    if (callback instanceof Function) return callback(result);
+
+    if (action !== 'onFetch') callback.onEvent?.(action, result);
+
+    callback[action]?.(result);
+  };
+
+  const disposers: Amity.Unsubscriber[] = [];
+
+  disposers.push(
+    onChannelUpdated(data => router({ data, loading: false, origin: 'event' }, 'onUpdate')),
+    onChannelDeleted(data => router({ data, loading: false, origin: 'event' }, 'onDelete')),
+    onChannelJoined(data => router({ data, loading: false, origin: 'event' }, 'onJoin')),
+    onChannelLeft(data => router({ data, loading: false, origin: 'event' }, 'onLeft')),
+    onChannelMemberAdded(data =>
+      router({ data, loading: false, origin: 'event' }, 'onMemberAdded'),
+    ),
+    onChannelMemberRemoved(data =>
+      router({ data, loading: false, origin: 'event' }, 'onMemberRemoved'),
+    ),
+  );
+
+  runQuery(createQuery(getChannel, channelId), result => result.data && router(result, 'onFetch'));
+
+  return () => {
+    log(`observeChannel(tmpid: ${timestamp}) > dispose`);
+    disposers.forEach(fn => fn());
+  };
+};

package/src/client/api/activeClient.ts

@@ -0,0 +1,33 @@
+import { ASCError } from '~/core/errors';
+
+let activeClient: Amity.Client | null = null;
+
+/**
+ * Get the active client
+ *
+ * @returns the active client instance
+ *
+ * @hidden
+ */
+export const getActiveClient = () => {
+  if (!activeClient) {
+    throw new ASCError(
+      'There is no active client',
+      Amity.ClientError.UNKNOWN_ERROR,
+      Amity.ErrorLevel.FATAL,
+    );
+  }
+
+  return activeClient!;
+};
+
+/**
+ * Sets the active client
+ *
+ * @param client the client to assume as currently active client
+ *
+ * @hidden
+ */
+export const setActiveClient = (client: Amity.Client) => {
+  activeClient = client;
+};

package/src/client/api/activeUser.ts

@@ -0,0 +1,26 @@
+import { ASCError } from '~/core/errors';
+
+let activeUser: Pick<Amity.User, '_id' | 'userId' | 'path'> | null = null;
+
+/**
+ * for internal use
+ */
+export const getActiveUser = () => {
+  if (!activeUser) {
+    throw new ASCError(
+      'Connect client first',
+      Amity.ClientError.UNKNOWN_ERROR,
+      Amity.ErrorLevel.FATAL,
+    );
+  }
+
+  return activeUser!;
+};
+
+export const setActiveUser = (user: Amity.User) => {
+  activeUser = {
+    _id: user._id,
+    userId: user.userId,
+    path: user.path,
+  };
+};

package/src/client/api/connectClient.ts

@@ -0,0 +1,84 @@
+/* eslint-disable no-param-reassign */
+/* eslint-disable require-atomic-updates */
+import { disconnectClient } from '~/client/api/disconnectClient';
+import { getDeviceId } from '~/core/device';
+import { proxyWebsocketEvents } from '~/core/events';
+
+import { getActiveClient } from './activeClient';
+import { setActiveUser } from './activeUser';
+
+import { getToken } from './getToken';
+import { onClientBanned } from '../events';
+import { getNetworkTopic, subscribeTopic } from '~/core/subscription';
+import { onUserDeleted } from '~/user/events/onUserDeleted';
+
+/**
+ * ```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 params the connect parameters
+ * @param params.userId the user ID for the current session
+ * @param params.displayName the user's displayName for the current session
+ * @param params.deviceId Manual override of the user's device id (for device management)
+ * @param params.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.deviceId ??= getDeviceId();
+
+  // @ts-ignore: in that particular case, typing can be
+  // ignored since we enforce default values just before.
+  const { accessToken, users } = 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 };
+
+  // FIXME: events are duplicated if connectClient is called few times without disconnectClient
+  // 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;
+  client.accessToken = accessToken;
+
+  setActiveUser(users[0]);
+
+  subscribeTopic(getNetworkTopic());
+
+  const subscriptions = [
+    onClientBanned(() => {
+      disconnectClient();
+      subscriptions.forEach(fn => fn());
+    }),
+    onUserDeleted(() => null),
+  ];
+
+  return client.ws.connected;
+};

package/src/client/api/createClient.ts

@@ -0,0 +1,68 @@
+import { VERSION } from '~/version';
+
+import { createLogger } from '~/core/debug';
+
+import { API_REGIONS, computeUrl } from '~/client/utils/endpoints';
+import {
+  createHttpTransport,
+  createMqttTransport,
+  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 apiRegion 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,
+  apiRegion: typeof API_REGIONS[keyof typeof API_REGIONS] = API_REGIONS.SG,
+  debugSession = 'amity',
+): Amity.Client => {
+  const log = createLogger(debugSession);
+
+  log('client/api/createClient', {
+    apiKey: apiKey.replace(/.{5}$/g, 'xxxxx'),
+    apiRegion,
+  });
+
+  const http = createHttpTransport(computeUrl('http', apiRegion));
+  const ws = createWebsocketTransport(computeUrl('http', apiRegion));
+  const mqtt = createMqttTransport(computeUrl('mqtt', apiRegion));
+
+  const emitter = createEventEmitter();
+
+  const client = {
+    version: `${VERSION}`,
+
+    apiKey,
+    log,
+    http,
+    ws,
+    mqtt,
+    emitter,
+    use: () => setActiveClient(client),
+  };
+
+  try {
+    getActiveClient();
+  } catch {
+    setActiveClient(client);
+  }
+
+  return client;
+};

package/src/client/api/disconnectClient.ts

@@ -0,0 +1,35 @@
+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.mqtt.disconnect();
+  });
+
+  client.emitter.all.clear();
+  // FIXME: it removes listener in ws.ts, it breaks global ban event
+  client.ws.removeAllListeners();
+  client.mqtt.removeAllListeners();
+  client.userId = undefined;
+  client.accessToken = undefined;
+
+  return !client.ws.connected;
+};

package/src/client/api/getToken.ts

@@ -0,0 +1,41 @@
+import { getActiveClient } from './activeClient';
+
+import { 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 & { users: Amity.User[] }>(
+    '/v1/device',
+    {
+      ...params,
+      deviceInfo,
+    },
+    {
+      // @ts-ignore
+      headers: { 'X-API-Key': client.apiKey },
+    },
+  );
+
+  return data;
+};

package/src/client/api/index.ts

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

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,4 @@
+export * from './onConnectionError';
+
+export * from './onClientDisconnected';
+export * from './onClientBanned';

package/src/client/events/onClientBanned.ts

@@ -0,0 +1,22 @@
+import { onConnectionError } from './onConnectionError';
+
+/**
+ * ```js
+ * import { onClientBanned } from '@amityco/ts-sdk'
+ * const dispose = onClientBanned(() => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when any {@link Amity.Client} have been banned from the platform
+ *
+ * @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 onClientBanned = (callback: Amity.Listener<void>): Amity.Unsubscriber => {
+  return onConnectionError(({ code }) => {
+    code === Amity.ServerError.GLOBAL_BAN && callback();
+  });
+};

package/src/client/events/onClientDisconnected.ts

@@ -0,0 +1,22 @@
+import { onConnectionError } from './onConnectionError';
+
+/**
+ * ```js
+ * import { onClientDisconnected } from '@amityco/ts-sdk'
+ * const dispose = onClientDisconnected(() => {
+ *   // ...
+ * })
+ * ```
+ *
+ * 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 onConnectionError(({ code }) => {
+    code === Amity.ClientError.DISCONNECTED && callback();
+  });
+};

package/src/client/events/onConnectionError.ts

@@ -0,0 +1,46 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { createEventSubscriber } from '~/core/events';
+
+import { ASCError, ASCConnectionError } from '~/core/errors';
+
+const EVENTS = [
+  'disconnected',
+  'error',
+  'connect_error',
+  'reconnect_error',
+  'reconnect_failed',
+] as const;
+
+/**
+ * ```js
+ * import { onConnectionError } from '@amityco/ts-sdk'
+ * const dispose = onClientBanned(() => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when any {@link Amity.Client} have been banned from the platform
+ *
+ * @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 onConnectionError = (callback: Amity.Listener<ASCError>): Amity.Unsubscriber => {
+  const client = getActiveClient();
+
+  const subscribers = EVENTS.map(event =>
+    createEventSubscriber(client, `client/onConnectionError(${event})`, event, response => {
+      const error = response?.code
+        ? new ASCError(response.message, response.code, Amity.ErrorLevel.FATAL)
+        : new ASCConnectionError(event);
+
+      callback(error);
+    }),
+  );
+
+  return () => {
+    subscribers.forEach(fn => fn());
+  };
+};

package/src/client/utils/endpoints.ts

@@ -0,0 +1,14 @@
+export const API_REGIONS = {
+  EU: 'eu',
+  SG: 'sg',
+  US: 'us',
+} as const;
+
+const URLS = {
+  http: 'https://api.{region}.amity.co',
+  mqtt: 'wss://sse.{region}.amity.co:443/mqtt',
+} as const;
+
+export function computeUrl(type: keyof typeof URLS, region: string) {
+  return URLS[type].replace('{region}', region);
+}

package/src/comment/api/createComment.ts

@@ -0,0 +1,46 @@
+import { getActiveClient } from '~/client/api';
+
+import { ingestInCache } from '~/cache/api/ingestInCache';
+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' | 'mentionees'
+  >,
+): Promise<Amity.Cached<Amity.Comment>> => {
+  const client = getActiveClient();
+  client.log('comment/createComment', bundle);
+
+  const { data } = await client.http.post<Amity.CommentPayload>('/api/v3/comments', bundle);
+
+  const cachedAt = client.cache && Date.now();
+  if (client.cache) ingestInCache(data, { cachedAt });
+
+  const post = await getPost(bundle.referenceId);
+
+  fireEvent('post.updated', { posts: [post.data] });
+  fireEvent('comment.created', data);
+
+  const { comments } = data;
+  return {
+    data: comments[0],
+    cachedAt,
+  };
+};