@amityco/ts-sdk 0.0.1-003998f.0

package/src/user/api/getUsers.ts

@@ -0,0 +1,77 @@
+import { getActiveClient } from '~/client/api';
+
+import { pullFromCache } from '~/cache/api';
+import { ingestInCache } from '~/cache/api/ingestInCache';
+import { fireEvent } from '~/core/events';
+
+/**
+ * ```js
+ * import { getUsers } from '@amityco/ts-sdk'
+ * const { data: users } = await getUsers(['foo', 'bar'])
+ * ```
+ *
+ * Fetches a collection of {@link Amity.User} objects
+ *
+ * @param userIds the IDs of the {@link Amity.User} to fetch
+ * @returns the associated collection of {@link Amity.User} objects
+ *
+ * @category User API
+ * @async
+ */
+export const getUsers = async (
+  userIds: Amity.User['userId'][],
+): Promise<Amity.Cached<Amity.User[]>> => {
+  const client = getActiveClient();
+  client.log('user/getUsers', userIds);
+
+  const encodedUserIds = userIds.map(userId => encodeURIComponent(userId));
+
+  // API-FIX: endpoint should not be /list, parameters should be querystring.
+  const { data } = await client.http.get<Amity.UserPayload>(`/api/v3/users/list`, {
+    params: { userIds: encodedUserIds },
+  });
+
+  const cachedAt = client.cache && Date.now();
+  if (client.cache) ingestInCache(data, { cachedAt });
+
+  fireEvent('user.fetched', data);
+
+  return {
+    data: data.users,
+    cachedAt,
+  };
+};
+
+/**
+ * ```js
+ * import { getUsers } from '@amityco/ts-sdk'
+ * const { data: users } = getUsers.locally!(['foo', 'bar'])
+ * ```
+ *
+ * Fetches a collection of {@link Amity.User} objects from cache
+ *
+ * @param userIds the IDs of the {@link Amity.User} to fetch
+ * @returns the associated collection of {@link Amity.User} objects
+ *
+ * @category User API
+ */
+getUsers.locally = (userIds: Amity.User['userId'][]): Amity.Cached<Amity.User[]> | undefined => {
+  const client = getActiveClient();
+  client.log('user/getUsers.locally', userIds);
+
+  if (!client.cache) return;
+
+  const cached = userIds
+    .map(userId => pullFromCache<Amity.User>(['user', 'get', userId])!)
+    .filter(Boolean);
+
+  const users = cached.map(({ data }) => data);
+  const oldest = cached.sort((a, b) => (a.cachedAt! < b.cachedAt! ? -1 : 1))?.[0];
+
+  if (cached?.length < userIds.length) return;
+
+  return {
+    data: users,
+    cachedAt: oldest.cachedAt,
+  };
+};

package/src/user/api/index.ts

@@ -0,0 +1,5 @@
+export { getUser } from './getUser';
+export { getUsers } from './getUsers';
+export { queryUsers } from './queryUsers';
+
+export { updateUser } from './updateUser';

package/src/user/api/queryUsers.ts

@@ -0,0 +1,129 @@
+import { getActiveClient } from '~/client/api';
+
+import { toPage, toToken } from '~/core/query';
+
+import { pullFromCache, pushToCache } from '~/cache/api';
+import { ingestInCache } from '~/cache/api/ingestInCache';
+import { getResolver } from '~/core/model';
+import { fireEvent } from '~/core/events';
+
+/**
+ * ```js
+ * import { queryUsers } from '@amityco/ts-sdk'
+ * const { data: users, prevPage, nextPage } = await queryUsers({ displayName: 'foo' })
+ * ```
+ *
+ * Queries a paginable list of {@link Amity.User} objects
+ * Search is performed by displayName such as `.startsWith(search)`
+ *
+ * @param query The query parameters
+ * @returns A page of {@link Amity.User} objects
+ *
+ * @category User API
+ * @async
+ */
+export const queryUsers = async (
+  query: {
+    displayName?: Amity.User['displayName'];
+    filter?: 'all' | 'flagged';
+    sortBy?: 'displayName' | 'firstCreated' | 'lastCreated';
+    page?: Amity.Page;
+  } = {},
+): Promise<Amity.Cached<Amity.Paged<Amity.User>>> => {
+  const client = getActiveClient();
+  client.log('user/queryUsers', query);
+
+  const {
+    page = { limit: 10 },
+    displayName,
+    filter = 'all',
+    sortBy = 'displayName',
+    ...params
+  } = query;
+
+  const { data } = await client.http.get<Amity.UserPayload & Amity.Pagination>(`/api/v3/users`, {
+    params: {
+      ...params,
+      keyword: displayName,
+      filter,
+      sortBy,
+      options: {
+        token: toToken(page, 'skiplimit'),
+      },
+    },
+  });
+
+  // unpacking
+  const { paging, ...payload } = data;
+  const { users } = payload;
+
+  const cachedAt = client.cache && Date.now();
+
+  if (client.cache) {
+    ingestInCache(payload as Amity.UserPayload, { cachedAt });
+
+    /*
+     * using query as cache key over params because if the keyword, filter, sort
+     * change the API will NOT cache results, when it should
+     */
+    const cacheKey = ['user', 'query', { ...query, options: { ...page } } as Amity.Serializable];
+    pushToCache(cacheKey, { users: users.map(getResolver('user')), paging });
+  }
+
+  fireEvent('user.fetched', data);
+
+  const prevPage = toPage(paging.previous);
+  const nextPage = toPage(paging.next);
+
+  return { data: users, cachedAt, prevPage, nextPage };
+};
+
+/**
+ * ```js
+ * import { queryUsers } from '@amityco/ts-sdk'
+ * const { data: users } = queryUsers.locally({ keyword: 'foo' })
+ * ```
+ *
+ * Queries a paginable list of {@link Amity.User} objects from cache
+ * Search is performed by displayName such as `.startsWith(search)`
+ *
+ * @param query The query parameters
+ * @returns A page of {@link Amity.User} objects
+ *
+ * @category User API
+ */
+queryUsers.locally = (
+  query: Parameters<typeof queryUsers>[0] = {},
+): Amity.Cached<Amity.Paged<Amity.User>> | undefined => {
+  const client = getActiveClient();
+  client.log('user/queryUsers.locally', query);
+
+  if (!client.cache) return;
+
+  const { page = { limit: 10 } } = query ?? {};
+
+  const cacheKey = [
+    'user',
+    'query',
+    {
+      ...query,
+      options: { ...page },
+    } as Amity.Serializable,
+  ];
+
+  const { data, cachedAt } =
+    pullFromCache<{ users: Pick<Amity.User, 'userId'>[] } & Amity.Pagination>(cacheKey) ?? {};
+
+  const users: Amity.User[] =
+    data?.users
+      .map(userId => pullFromCache<Amity.User>(['user', 'get', userId])!)
+      .filter(Boolean)
+      .map(({ data }) => data) ?? [];
+
+  const prevPage = toPage(data?.paging.previous);
+  const nextPage = toPage(data?.paging.next);
+
+  return users.length > 0 && users.length === data?.users?.length
+    ? { data: users, cachedAt, prevPage, nextPage }
+    : undefined;
+};

package/src/user/api/tests/queryUsers.test.ts

@@ -0,0 +1,124 @@
+import { getResolver } from '~/core/model';
+
+import { disableCache, enableCache, pushToCache } from '~/cache/api';
+import { ingestInCache } from '~/cache/api/ingestInCache';
+
+import { client, userQueryResponse } from '~/utils/tests';
+
+import { queryUsers } from '../queryUsers';
+
+describe('queryUsers', () => {
+  test('it should return users', async () => {
+    const { users: expected } = userQueryResponse.data;
+    client.http.get = jest.fn().mockResolvedValue(userQueryResponse);
+
+    const { data } = await queryUsers();
+
+    expect(data).toEqual(expected);
+  });
+
+  test('it should throw error', async () => {
+    client.http.get = jest.fn().mockRejectedValueOnce(new Error('error'));
+
+    await expect(queryUsers()).rejects.toThrow('error');
+  });
+
+  test('it should update cache upon fetching data from server', async () => {
+    enableCache();
+
+    client.http.get = jest.fn().mockResolvedValue(userQueryResponse);
+
+    const { data: expected } = await queryUsers();
+    const { data: received } = queryUsers.locally()!;
+
+    expect(received).toBeDefined();
+    expect(received).toEqual(expected);
+
+    disableCache();
+  });
+});
+
+describe('queryUsers.locally', () => {
+  const cacheKey = [
+    'user',
+    'query',
+    { options: { limit: 10, after: undefined } } as Amity.Serializable,
+  ];
+
+  test('it should fetch query locally if present in cache', () => {
+    enableCache();
+
+    const { data } = userQueryResponse;
+    const { users: expected, paging } = data;
+
+    ingestInCache(data as Amity.UserPayload);
+
+    pushToCache(cacheKey, { users: expected.map(getResolver('user')), paging });
+
+    const { data: received } = queryUsers.locally()!;
+
+    expect(received).toBeDefined();
+    expect(received).toEqual(expected);
+
+    disableCache();
+  });
+
+  test('it should return undefined if only partial data in cache', () => {
+    enableCache();
+
+    const { data } = userQueryResponse;
+    const { users, paging } = data;
+
+    // ingest incomplete data
+    ingestInCache({
+      ...data,
+      users: [data.users[0]],
+    } as Amity.UserPayload);
+
+    pushToCache(cacheKey, {
+      users: users.map(getResolver('user')),
+      paging,
+    });
+
+    const received = queryUsers.locally()!;
+
+    expect(received).toBeUndefined();
+
+    disableCache();
+  });
+
+  // added because of comment above cache key in queryUsers
+  test('it should return undefined if params do not match', () => {
+    enableCache();
+
+    const { data } = userQueryResponse;
+    const { users: expected, paging } = data;
+
+    ingestInCache(data as Amity.UserPayload);
+
+    pushToCache(cacheKey, { users: expected.map(getResolver('user')), paging });
+
+    const { data: received } = queryUsers.locally()!;
+    const received2 = queryUsers.locally({ displayName: 'test' })!;
+
+    expect(received).toBeDefined();
+    expect(received).toEqual(expected);
+    expect(received2).toBeUndefined();
+
+    disableCache();
+  });
+
+  test('it should return undefined if data not in cache', () => {
+    enableCache();
+
+    const received = queryUsers.locally();
+
+    expect(received).toBeUndefined();
+
+    disableCache();
+  });
+
+  test('it should return undefined if cache disabled', () => {
+    expect(queryUsers.locally()).toBeUndefined();
+  });
+});

package/src/user/api/updateUser.ts

@@ -0,0 +1,55 @@
+import { getActiveClient } from '~/client/api';
+
+import { fireEvent } from '~/core/events';
+import { ingestInCache } from '~/cache/api/ingestInCache';
+
+/**
+ * ```js
+ * import { updateUser } from '@amityco/ts-sdk'
+ * const updated = await updateUser(userId, { displayName: 'foobar' })
+ * ```
+ *
+ * Updates an {@link Amity.User}
+ *
+ * @param userId The ID of the {@link Amity.User} to update
+ * @param patch The patch data to apply
+ * @returns the updated {@link Amity.User} object
+ *
+ * @category User API
+ * @async
+ */
+export const updateUser = async (
+  userId: Amity.User['userId'],
+  patch: Patch<
+    Amity.User,
+    'displayName' | 'description' | 'avatarFileId' | 'avatarCustomUrl' | 'metadata'
+  >,
+): Promise<Amity.Cached<Amity.User>> => {
+  const client = getActiveClient();
+  client.log('user/updateUser', userId, patch);
+
+  // API-FIX: Endpoint is malformed, userId should be a url param.
+  /*
+    const { data } = await client.http.put<Amity.Response<UserPayload>>(
+      `/api/v3/users/${userId}`, patch,
+    )
+  */
+
+  const { data } = await client.http.put<Amity.UserPayload>(`/api/v3/users/`, {
+    userId,
+    ...patch,
+    createNewUserWhenNotFound: false,
+  });
+
+  const cachedAt = client.cache && Date.now();
+  if (client.cache) ingestInCache(data, { cachedAt });
+
+  const { users } = data;
+
+  fireEvent('user.updated', data);
+
+  return {
+    data: users.find(user => user.userId === userId)!,
+    cachedAt,
+  };
+};

package/src/user/events/index.ts

@@ -0,0 +1,7 @@
+export * from './onUserFetched';
+export * from './onUserUpdated';
+export * from './onUserDeleted';
+
+export * from './onUserFlagged';
+export * from './onUserUnflagged';
+export * from './onUserFlagCleared';

package/src/user/events/onUserDeleted.ts

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

package/src/user/events/onUserFetched.ts

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

package/src/user/events/onUserFlagCleared.ts

@@ -0,0 +1,19 @@
+import { createUserEventSubscriber } from './utils';
+
+/**
+ * ```js
+ * import { onUserFlagCleared } from '@amityco/ts-sdk'
+ * const dispose = onUserFlagCleared(user => {
+ *   // ...
+ * })
+ * ```
+ *
+ * Fired when flags have been cleared for a {@link Amity.User}
+ *
+ * @param callback The function to call when the event was fired
+ * @returns an {@link Amity.Unsubscriber} function to stop listening
+ *
+ * @category User Events
+ */
+export const onUserFlagCleared = (callback: Amity.Listener<Amity.User>) =>
+  createUserEventSubscriber('user.flagCleared', callback);

package/src/user/events/onUserFlagged.ts

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

package/src/user/events/onUserUnflagged.ts

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

package/src/user/events/onUserUpdated.ts

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

package/src/user/events/utils.ts

@@ -0,0 +1,21 @@
+import { getActiveClient } from '~/client/api/activeClient';
+import { createEventSubscriber } from '~/core/events';
+
+import { ingestInCache } from '~/cache/api/ingestInCache';
+
+export const createUserEventSubscriber = (
+  event: keyof Amity.MqttUserMessageEvents,
+  callback: Amity.Listener<Amity.User>,
+) => {
+  const client = getActiveClient();
+
+  const filter = (payload: Amity.UserPayload) => {
+    if (client.cache) {
+      ingestInCache(payload);
+    }
+
+    callback(payload.users[0]);
+  };
+
+  return createEventSubscriber(client, event, event, filter);
+};

package/src/user/observers/index.ts

@@ -0,0 +1,2 @@
+export { liveUser } from './liveUser';
+export { observeUser } from './observeUser';

package/src/user/observers/liveUser.ts

@@ -0,0 +1,89 @@
+import { getActiveClient } from '~/client/api';
+import { createQuery, runQuery } from '~/core/query';
+
+import { LIVE_OBJECT_ENABLE_CACHE_MESSAGE } from '~/utils/constants';
+
+import {
+  onUserFetched,
+  onUserDeleted,
+  onUserUpdated,
+  onUserFlagCleared,
+  onUserFlagged,
+  onUserUnflagged,
+} from '../events';
+import { getUser } from '../api';
+
+/**
+ * ```js
+ * import { liveUser } from '@amityco/ts-sdk'
+ *
+ * let users = []
+ * const unsub = liveUser(userId, response => merge(users, response.data))
+ * ```
+ *
+ * Observe all mutation on a given {@link Amity.User}
+ *
+ * @param userId the ID of the user 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 users
+ *
+ * @category Message Live Object
+ */
+export const liveUser = (
+  userId: Amity.User['userId'],
+  callback: Amity.LiveObjectCallback<Amity.User>,
+): Amity.Unsubscriber => {
+  const { log, cache } = getActiveClient();
+  let user: Amity.User;
+
+  if (!cache) {
+    console.log(LIVE_OBJECT_ENABLE_CACHE_MESSAGE);
+  }
+
+  const timestamp = Date.now();
+  log(`liveUser(tmpid: ${timestamp}) > listen`);
+
+  const disposers: Amity.Unsubscriber[] = [];
+
+  const dispatcher = (data: Amity.LiveObject<Amity.User>) => {
+    // we check updatedAt to see if the current snapshot is new so
+    // we won't send old data back, only fresh new data
+    if (user && data.data?.updatedAt === user?.updatedAt && data.origin !== 'server') return;
+
+    callback(data);
+    user = data.data;
+  };
+
+  const realtimeRouter = (user: Amity.User, action: Amity.UserActionType) => {
+    dispatcher({ loading: false, data: user, origin: 'event' });
+  };
+
+  const onFetch = () => {
+    const query = createQuery(getUser, userId, true);
+
+    runQuery(query, ({ loading, data, error, origin }) => {
+      dispatcher({ loading, data, origin, error });
+
+      if (error) {
+        // Terminate observe functionality on error
+        disposers.forEach(fn => fn());
+      }
+    });
+  };
+
+  disposers.push(
+    onUserFetched(user => realtimeRouter(user, 'onFetch')),
+    onUserUpdated(user => realtimeRouter(user, 'onUpdate')),
+    onUserDeleted(user => realtimeRouter(user, 'onDelete')),
+    onUserFlagged(user => realtimeRouter(user, 'onFlagged')),
+    onUserUnflagged(user => realtimeRouter(user, 'onUnflagged')),
+    onUserFlagCleared(user => realtimeRouter(user, 'onFlagCleared')),
+  );
+
+  onFetch();
+
+  return () => {
+    log(`liveUser(tmpid: ${timestamp}) > dispose`);
+    disposers.forEach(fn => fn());
+  };
+};