@amityco/ts-sdk 0.0.1-be4fc2f.0 → 0.0.1-bef76fa.0

package/src/cache/api/tests/pushToCache.test.ts

@@ -0,0 +1,57 @@
+import { getActiveClient } from '~/client/api';
+import { connectClient, disconnectClient, user11 } from '~/utils/tests';
+
+import { pushToCache, enableCache, disableCache, pullFromCache } from '..';
+import { encodeKey } from '../../utils';
+
+describe('pushToCache', () => {
+  beforeAll(connectClient);
+  afterAll(disconnectClient);
+
+  describe('- cache enabled', () => {
+    beforeEach(enableCache);
+    afterEach(disableCache);
+
+    const cacheKey = ['user', 'get', user11.userId];
+
+    test('it should return true if data added to cache', () => {
+      const recieved = pushToCache(cacheKey, user11);
+
+      expect(recieved).toBe(true);
+    });
+
+    test('it should add data to cache', () => {
+      const returned = pushToCache(cacheKey, user11);
+      const recieved = pullFromCache(cacheKey)?.data;
+
+      expect(returned).toBe(true);
+      expect(recieved).toBe(user11);
+    });
+
+    test('it should persist data offline', () => {
+      const { cache } = getActiveClient();
+      const encodedKey = encodeKey(cacheKey);
+      const options = { offline: true, cachedAt: Date.now() };
+
+      const addedUser = pushToCache(cacheKey, user11, options);
+
+      const expected = {
+        key: cacheKey,
+        data: user11,
+        ...options,
+      };
+      const recieved = cache?.data[encodedKey];
+
+      expect(addedUser).toBe(true);
+      expect(recieved).toStrictEqual(expected);
+    });
+  });
+
+  describe('- no cache', () => {
+    test('it should return false if no cache', () => {
+      const recieved = pushToCache(['model', 'key', 'modleId'], {});
+
+      expect(recieved).toBe(false);
+    });
+  });
+});

package/src/cache/api/tests/upsertInCache.test.ts

@@ -0,0 +1,60 @@
+import { connectClient, disconnectClient, post11, message11, channel11 } from '~/utils/tests';
+
+import { upsertInCache, enableCache, disableCache, pullFromCache } from '..';
+
+describe('upsertInCache', () => {
+  beforeAll(connectClient);
+  afterAll(() => {
+    disableCache();
+    disconnectClient();
+  });
+
+  const cacheKey = ['post', 'get', 'test-candidate-id'];
+
+  test('it should add candidate to cache if non-existent', () => {
+    enableCache();
+
+    expect(upsertInCache(cacheKey, post11)).toBe(true);
+    expect(pullFromCache(cacheKey)?.data).toBe(post11);
+
+    disableCache();
+  });
+
+  test('it should return false if cache disabled', () => {
+    disableCache();
+
+    expect(upsertInCache(cacheKey, post11)).toBe(false);
+  });
+
+  test('it should update cachedAt value', () => {
+    enableCache();
+
+    const now = Date.now();
+
+    expect(upsertInCache(cacheKey, post11, { cachedAt: now })).toBe(true);
+    expect(pullFromCache(cacheKey)?.cachedAt).toBe(now);
+
+    disableCache();
+  });
+
+  // create table of tests for message, post, channel
+  const cases: [string, Amity.CacheKey, Record<string, unknown>][] = [
+    ['post', ['post', 'get', post11.postId], post11],
+    ['message', ['message', 'get', message11.messageId], message11],
+    ['channel', ['channel', 'get', channel11.channelId], channel11],
+    ['post', ['post', 'get', post11.postId], { ...post11, channelId: 'altered' }],
+    ['message', ['message', 'get', message11.messageId], { ...message11, userId: 'updated-user' }],
+    ['channel', ['channel', 'get', channel11.channelId], { ...channel11, displayName: 'updated' }],
+  ];
+
+  // cache is not disabled, so as to test update
+  test.each(cases)('it should update %s in cache', (type, cacheKey, expected) => {
+    enableCache();
+
+    const recieved = upsertInCache(cacheKey, expected);
+
+    expect(recieved).toBe(true);
+    expect(pullFromCache(cacheKey)?.data).toBeDefined();
+    expect(pullFromCache(cacheKey)?.data).toStrictEqual(expected);
+  });
+});

package/src/cache/api/upsertInCache.ts

@@ -0,0 +1,37 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { pullFromCache } from './pullFromCache';
+import { pushToCache } from './pushToCache';
+import { mergeInCache } from './mergeInCache';
+
+/**
+ * ```js
+ * import { upsertInCache } from '@amityco/ts-sdk'
+ * upsertInCache<Amity.User>(["user", "foobar"], user)
+ * ```
+ *
+ * Insert or update any provided value as {@link Amity.CacheEntry} for
+ * the matching {@link Amity.CacheKey}
+ *
+ * @param key the key to save the object to
+ * @param data the object to save
+ * @param options customisation object around cache behavior (default gives a 2mn lifespan)
+ * @returns a success boolean if the object was saved in cache
+ *
+ * @category Cache API
+ * @hidden
+ */
+export const upsertInCache = <T extends Record<string, unknown>>(
+  key: Amity.CacheKey,
+  data: T,
+  options: Amity.CacheOptions = { cachedAt: Date.now() },
+): boolean => {
+  const { log, cache } = getActiveClient();
+
+  if (!cache) return false;
+  log('cache/api/upsertInCache', { key, data, options });
+
+  const cached = pullFromCache<T>(key);
+
+  return cached ? mergeInCache<T>(key, data, options) : pushToCache(key, data, options);
+};

package/src/cache/api/wipeCache.ts

@@ -0,0 +1,34 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+import { getActiveClient } from '~/client/api/activeClient';
+
+/**
+ * ```js
+ * import { wipeCache } from '@amityco/ts-sdk'
+ * const success = await wipeCache()
+ * ```
+ *
+ * Wipes a persistent storage for the current {@link Amity.Cache} instance.
+ *
+ * The strategy for persistent storage will depend on the runtime,
+ * which is supported by @react-native-async-storage/async-storage.
+ *
+ * The current userId will be appended to the given storageKey to avoid
+ * collision between multiple client instances over time.
+ *
+ * @param storageKey the name of the persistent storage
+ * @returns a success boolean if the persistent cache was wiped.
+ *
+ * @category Cache API
+ */
+export const wipeCache = async (storageKey = 'amitySdk') => {
+  const { log, cache, userId } = getActiveClient();
+
+  if (!cache) return false;
+  log('cache/api/wipeCache', { storageKey });
+
+  cache.data = {};
+  await AsyncStorage.setItem(`${storageKey}#${userId}`, '{}');
+
+  return true;
+};

package/src/cache/utils/index.ts

@@ -0,0 +1,96 @@
+// cache constants
+export const CACHE_KEY_GET = 'get';
+export const CACHE_KEY_QUERY = 'query';
+export const CACHE_KEY_TOMBSTONE = 'dead';
+export const CACHE_KEY_COLLECTION = 'collection';
+
+export const CACHE_LIFESPAN = 1 * 60 * 1000; // 1 minute
+export const CACHE_LIFESPAN_TOMBSTONE = 3 * 60 * 1000; // 3 minutes
+
+/**
+ * Shallow-clones an object and sort its keys
+ *
+ * @param source a plain object to clone
+ * @returns a clone of source, with keys sorted with default javascript sorting
+ *
+ * @category Cache
+ * @hidden
+ */
+const normalize = (
+  source: Record<string, Amity.Serializable>,
+): Record<string, Amity.Serializable> =>
+  Object.keys(source)
+    .sort()
+    .reduce((acc, key) => ({ ...acc, [key]: source[key] }), {});
+
+/**
+ * Encodes a given {@link Amity.CacheKey} to a plain string
+ *
+ * @param key the key to encode
+ * @returns an encoded string
+ *
+ * @category Cache
+ * @hidden
+ */
+export const encodeKey = (key: Amity.CacheKey): string =>
+  JSON.stringify(key, (_, val) => (typeof val === 'object' ? normalize(val) : val));
+
+/**
+ * Decodes a string back into a {@link Amity.CacheKey}
+
+ *
+ * @param key the string key to decode
+ * @returns a plain Amity.CacheKey object.
+ *
+ * @category Cache
+ * @hidden
+ */
+export const decodeKey = (key: string): Amity.CacheKey => JSON.parse(key);
+
+/**
+ * Performs a recursive partial deep equal check on two objects.
+ *
+ * @param predicate the reference object containing the partial information
+ * @param candidate the object to check against
+ * @returns true if the candidate contains all the values of the predicate
+ *
+ * @category Cache
+ */
+export const partialMatch = (predicate: any, candidate: any): boolean => {
+  if (predicate === candidate) return true;
+
+  // if one or the other is nullish, there can't be equality
+  if (!predicate || !candidate) return false;
+
+  // we only perform recursive check on objects
+  if (typeof predicate !== 'object') {
+    return false;
+  }
+
+  // recursively call for partial match based on the predicate
+  return Object.keys(predicate).every(key => partialMatch(predicate[key], candidate[key]));
+};
+
+/**
+ * Type guard to check and cast that a given predicate matched {@link Amity.Cached} shape
+ *
+ * @param obj any {@link Amity.Cached}-like object
+ * @returns success boolean if the given object is of {@link Amity.Cached} shape
+ *
+ * @category Cache
+ */
+export const isCached = <T extends unknown>(obj?: any): obj is Amity.Cached<T> =>
+  ['data', 'cachedAt'].every(prop => obj?.hasOwnProperty(prop));
+
+/**
+ * checks if passed error code is included in
+ * Tombstone errors list
+ *
+ * @param errorCode as {@link Amity.ServerError}
+ * @returns success boolean if the given errorCode
+ * is included in Tombstone errors list
+ *
+ * @category Cache
+ */
+export const checkIfShouldGoesToTombstone = (errorCode: Amity.ServerError): boolean =>
+  [Amity.ServerError.ITEM_NOT_FOUND, Amity.ServerError.FORBIDDEN].includes(errorCode);

package/src/category/api/getCategory.ts

@@ -1,12 +1,12 @@
-import { getActiveClient } from '~/client/api/activeClient'
+import { getActiveClient } from '~/client/api/activeClient';
 
-import { decoratePayload } from '~/core/query'
-import { ingestInCache } from '~/core/cache'
+import { pullFromCache, dropFromCache } from '~/cache/api';
+import { ingestInCache } from '~/cache/api/ingestInCache';
 
 /**
  * ```js
  * import { getCategory } from '@amityco/ts-sdk'
- * const category = await getCategory('foo')
+ * const { data: category } = await getCategory('foo')
  * ```
  *
  * Fetches a {@link Amity.Category} object
@@ -18,18 +18,53 @@ import { ingestInCache } from '~/core/cache'
  * @async
  */
 export const getCategory = async (
-  categoryId: Amity.Category['categoryId']
-) => {
-  const client = getActiveClient()
-  client.log('category/getCategory', categoryId)
+  categoryId: Amity.Category['categoryId'],
+): Promise<Amity.Cached<Amity.Category>> => {
+  const client = getActiveClient();
+  client.log('category/getCategory', categoryId);
 
   const { data } = await client.http.get<Amity.CategoryPayload>(
-    `/api/v3/community-categories/${categoryId}`
-  )
+    `/api/v3/community-categories/${encodeURIComponent(categoryId)}`,
+  );
 
-  decoratePayload(data)
-  ingestInCache(data)
+  const cachedAt = client.cache && Date.now();
+  if (client.cache) ingestInCache(data, { cachedAt });
 
-  const { categories } = data
-  return categories[0]
-}
+  const { categories } = data;
+
+  return {
+    data: categories.find(category => category.categoryId === categoryId)!,
+    cachedAt,
+  };
+};
+
+/**
+ * ```js
+ * import { getCategory } from '@amityco/ts-sdk'
+ * const { data: category } = getCategory.locally('foobar')
+ * ```
+ *
+ * Fetches a {@link Amity.Category} object from cache
+ *
+ * @param categoryId the ID of the {@link Amity.Category} to fetch
+ * @returns the associated {@link Amity.Category} object
+ *
+ * @category Category API
+ */
+getCategory.locally = (
+  categoryId: Amity.Category['categoryId'],
+): Amity.Cached<Amity.Category> | undefined => {
+  const client = getActiveClient();
+  client.log('category/getCategory.locally', categoryId);
+
+  if (!client.cache) return;
+
+  const cached = pullFromCache<Amity.Category>(['category', 'get', categoryId]);
+
+  if (!cached) return;
+
+  return {
+    data: cached.data,
+    cachedAt: cached.cachedAt,
+  };
+};

package/src/category/api/index.ts

@@ -1,2 +1,2 @@
-export * from './queryCategories'
-export * from './getCategory'
+export * from './queryCategories';
+export * from './getCategory';

package/src/category/api/queryCategories.ts

@@ -1,13 +1,15 @@
-import { getActiveClient } from '~/client/api/activeClient'
+import { getActiveClient } from '~/client/api/activeClient';
 
-import { decoratePayload, toPage, toToken } from '~/core/query'
-import { ingestInCache } from '~/core/cache'
-import { toRecord } from '~/core/model'
+import { toToken, toPage } from '~/core/query';
+
+import { pullFromCache, pushToCache } from '~/cache/api';
+import { ingestInCache } from '~/cache/api/ingestInCache';
+import { getResolver } from '~/core/model';
 
 /**
  * ```js
  * import { queryCategories } from '@amityco/ts-sdk'
- * const categories = await queryCategories()
+ * const { data: categories, prevPage, nextPage } = await queryCategories()
  * ```
  *
  * Queries a paginable list of {@link Amity.Category} objects
@@ -15,35 +17,93 @@ import { toRecord } from '~/core/model'
  * @param query The query parameters
  * @returns A page of {@link Amity.Category} objects
  *
- * @category Community API
+ * @category Category API
  * @async
- **/
+ * */
 export const queryCategories = async (query?: {
-  sortBy?: 'lastCreated' | 'firstCreated' | 'name'
-  isDeleted?: Amity.Category['isDeleted']
-  page?: Amity.Page
-}) => {
-  const client = getActiveClient()
-  client.log('category/queryCategories', query)
+  sortBy?: 'lastCreated' | 'firstCreated' | 'name';
+  isDeleted?: Amity.Category['isDeleted'];
+  page?: Amity.Page;
+}): Promise<Amity.Cached<Amity.Paged<Amity.Category, Amity.Page>>> => {
+  const client = getActiveClient();
+  client.log('category/queryCategories', query);
 
-  const { page, ...params } = query ?? {}
+  const { page = { limit: 10 }, ...params } = query ?? {};
 
   const { data } = await client.http.get<Amity.CategoryPayload & Amity.Pagination>(
-    `/api/v3/community-categories`, { params : {
-      ...params,
-      options: {
-        token: toToken(page, 'skiplimit')
-      }
-    } })
+    `/api/v3/community-categories`,
+    {
+      params: {
+        ...params,
+        options: {
+          token: toToken(page, 'skiplimit'),
+        },
+      },
+    },
+  );
+
+  const { paging, ...payload } = data;
+  const { categories } = payload;
+
+  const cachedAt = client.cache && Date.now();
+
+  if (client.cache) {
+    ingestInCache(payload as Amity.CategoryPayload, { cachedAt });
+
+    const cacheKey = [
+      'category',
+      'query',
+      { ...params, options: { ...page } } as Amity.Serializable,
+    ];
+    pushToCache(cacheKey, { categories: categories.map(getResolver('category')), paging });
+  }
+
+  const nextPage = toPage(paging.next);
+  const prevPage = toPage(paging.previous);
+
+  return { data: categories, cachedAt, prevPage, nextPage };
+};
+
+/**
+ * ```js
+ * import { queryCategories } from '@amityco/ts-sdk'
+ * const { data: categories, prevPage, nextPage } = queryCategories.locally()
+ * ```
+ *
+ * Queries a paginable list of {@link Amity.Category} objects from cache
+ *
+ * @param query The query parameters
+ * @returns categories
+ *
+ * @category category API
+ */
+queryCategories.locally = (
+  query: Parameters<typeof queryCategories>[0],
+): Amity.Cached<Amity.Paged<Amity.Category, Amity.Page>> | undefined => {
+  const client = getActiveClient();
+  client.log('category/queryCategories.locally', query);
+
+  if (!client.cache) return;
+
+  const { page = { limit: 10 }, ...params } = query ?? {};
+
+  const queryKey = ['category', 'query', { ...params, options: { ...page } } as Amity.Serializable];
+  const { data, cachedAt } =
+    pullFromCache<{ categories: Pick<Amity.Category, 'categoryId'>[] } & Amity.Pagination>(
+      queryKey,
+    ) ?? {};
 
-  const { paging, ...response } = data
+  if (!data?.categories.length) return;
 
-  decoratePayload(response as unknown as Record<string, any[]>)
-  ingestInCache(response as unknown as Record<string, any[]>)
+  const categories: Amity.Category[] = data.categories
+    .map(categoryId => pullFromCache<Amity.Category>(['category', 'get', categoryId])!)
+    .filter(Boolean)
+    .map(({ data }) => data);
 
-  const prevPage = toPage(paging?.previous)
-  const nextPage = toPage(paging?.next)
+  const prevPage = toPage(data?.paging.previous);
+  const nextPage = toPage(data?.paging.next);
 
-  const { categories } = response
-  return [toRecord(categories), { prevPage, nextPage }] as const
-}
+  return categories.length === data?.categories?.length
+    ? { data: categories, cachedAt, prevPage, nextPage }
+    : undefined;
+};

package/src/channel/api/addChannelMembers.ts

@@ -1,8 +1,9 @@
-import { getActiveClient } from '~/client/api'
+import { getActiveClient } from '~/client/api';
 
-import { decoratePayload } from '~/core/query'
-import { ingestInCache } from '~/core/cache'
-import { fireEvent } from '~/core/events'
+import { ingestInCache } from '~/cache/api/ingestInCache';
+import { fireEvent } from '~/core/events';
+
+import { prepareChannelPayload } from '../utils';
 
 /**
  * ```js
@@ -21,25 +22,32 @@ import { fireEvent } from '~/core/events'
  */
 export const addChannelMembers = async (
   channelId: Amity.Channel['channelId'],
-  userIds: Amity.User['userId'][]
-) => {
-  const client = getActiveClient()
-  client.log('channel/addChannelMembers', channelId, userIds)
-
-  const { data } = await client.http.post<Amity.ChannelMembershipPayload>(
-    `/api/v3/channels/${channelId}/users`,
-    { channelId, userIds }
-  )
-
-  decoratePayload(data)
-  ingestInCache(data)
-  fireEvent('v3.channel.didAddUsers', {
-    channels: data.channels!,
-  })
-
-  const { channelUsers } = data
+  userIds: Amity.User['userId'][],
+): Promise<boolean> => {
+  const client = getActiveClient();
+  client.log('channel/addChannelMembers', channelId, userIds);
+
+  const { data: payload } = await client.http.post<Amity.ChannelMembershipPayload>(
+    `/api/v3/channels/${encodeURIComponent(channelId)}/users`,
+    { channelId, userIds },
+  );
+
+  const data = prepareChannelPayload(payload);
+
+  if (client.cache) ingestInCache(data);
+
+  /*
+   * should fire event for each user that was added
+   */
+  userIds.forEach(id =>
+    fireEvent('v3.channel.didAddUsers', {
+      ...data,
+      channelUsers: data.channelUsers.filter(u => u.userId === id),
+    }),
+  );
+
+  const { channelUsers } = data;
   return !!channelUsers.find(
-    channelUser =>
-      channelUser.channelId === channelId && channelUser.membership === 'member'
-  )
-}
+    channelUser => channelUser.channelId === channelId && channelUser.membership === 'member',
+  );
+};

package/src/channel/api/addChannelMembersRole.ts

@@ -1,7 +1,8 @@
-import { getActiveClient } from '~/client/api'
+import { getActiveClient } from '~/client/api';
 
-import { decoratePayload } from '~/core/query'
-import { ingestInCache } from '~/core/cache'
+import { ingestInCache } from '~/cache/api/ingestInCache';
+
+import { prepareChannelPayload } from '../utils';
 
 /**
  * ```js
@@ -22,22 +23,22 @@ import { ingestInCache } from '~/core/cache'
 export const addChannelMembersRole = async (
   channelId: Amity.Channel['channelId'],
   roleId: Amity.Role['roleId'],
-  userIds: Amity.User['userId'][]
-) => {
-  const client = getActiveClient()
-  client.log('channel/addChannelMembersRole', channelId, roleId, userIds)
+  userIds: Amity.User['userId'][],
+): Promise<boolean> => {
+  const client = getActiveClient();
+  client.log('channel/addChannelMembersRole', channelId, roleId, userIds);
+
+  const { data: payload } = await client.http.post<Amity.ChannelMembershipPayload>(
+    `/api/v3/channels/${encodeURIComponent(channelId)}/users/roles`,
+    { channelId, role: roleId, userIds },
+  );
 
-  const { data } = await client.http.post<Amity.ChannelMembershipPayload>(
-    `/api/v3/channels/${channelId}/users/roles`,
-    { channelId, role: roleId, userIds }
-  )
+  const data = prepareChannelPayload(payload);
 
-  decoratePayload(data)
-  ingestInCache(data)
+  if (client.cache) ingestInCache(data);
 
-  const { channelUsers } = data
+  const { channelUsers } = data;
   return !!channelUsers.find(
-    channelUser =>
-      channelUser.channelId === channelId && channelUser.roles.includes(roleId)
-  )
-}
+    channelUser => channelUser.channelId === channelId && channelUser.roles.includes(roleId),
+  );
+};

package/src/channel/api/banChannelMembers.ts

@@ -0,0 +1,47 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { ingestInCache } from '~/cache/api/ingestInCache';
+import { prepareMembershipPayload } from '~/group/utils';
+
+import { prepareChannelPayload } from '../utils';
+
+/**
+ * ```js
+ * import { banChannelMembers } from '@amityco/ts-sdk'
+ *
+ * await banChannelMembers('channel-id-1', ['userId1', 'userId2'])
+ * ```
+ *
+ * @param channelId of {@link Amity.Channel} from which the users should be banned
+ * @param userIds of the {@link Amity.User}'s to be banned
+ * @returns the updated {@link Amity.Membership}'s object
+ *
+ * @category Channel API
+ * @async
+ * */
+export const banChannelMembers = async (
+  channelId: Amity.Channel['channelId'],
+  userIds: Amity.User['userId'][],
+): Promise<Amity.Cached<Amity.Membership<'channel'>[]>> => {
+  const client = getActiveClient();
+  client.log('channel/banChannelMembers', { userIds, channelId });
+
+  const { data: payload } = await client.http.put<Amity.ChannelPayload>(
+    `/api/v3/channels/${channelId}/users/ban`,
+    {
+      userIds,
+    },
+  );
+
+  const channelPayload = prepareChannelPayload(payload);
+  const preparedPayload = prepareMembershipPayload(channelPayload, 'channelUsers');
+  const { channelUsers } = preparedPayload;
+
+  const cachedAt = client.cache && Date.now();
+  if (client.cache) ingestInCache(preparedPayload, { cachedAt });
+
+  return {
+    data: channelUsers?.filter(user => user.membership === 'banned')!,
+    cachedAt,
+  };
+};