@amityco/ts-sdk 1.0.0-8aae813.0 → 6.0.0-beta01

package/src/@types/domains/stream.ts

@@ -1,4 +1,4 @@
-export {}
+export {};
 
 declare global {
   namespace Amity {
@@ -16,54 +16,52 @@ declare global {
     }
 
     type MultiFormat<T> = {
-      flv?: T
-      mp4?: T
-      m3u8?: T
-    }
+      flv?: T;
+      mp4?: T;
+      m3u8?: T;
+    };
 
     type StreamPlatform = {
-      name: string
-      version: string
-    }
+      name: string;
+      version: string;
+    };
 
     type StreamEndpoint = {
-      url: string
+      url: string;
       components: {
-        origin: string
-        appName: string
-        streamName: string
-        query: string
-      }
-    }
+        origin: string;
+        appName: string;
+        streamName: string;
+        query: string;
+      };
+    };
 
     type StreamRecording = {
-      url: string
-      duration: number
-      startTime: number
-      stopTime: number
-    }
+      url: string;
+      duration: number;
+      startTime: number;
+      stopTime: number;
+    };
 
     type Stream = {
-      streamId: string
-      title: string
-      thumbnailFileId?: Amity.File<'image'>['fileId']
-      description?: string
-      status: StreamStatus
-      platform: StreamPlatform
+      streamId: string;
+      title: string;
+      thumbnailFileId?: Amity.File<'image'>['fileId'];
+      description?: string;
+      status: StreamStatus;
+      platform: StreamPlatform;
 
-      isLive?: boolean
-      endedAt: timestamp
-      startedAt: timestamp
-      userId: User['userId']
-      resolution: StreamResolution
+      isLive?: boolean;
+      endedAt: Amity.timestamp;
+      startedAt: Amity.timestamp;
+      userId: Amity.User['userId'];
+      resolution: StreamResolution;
 
-      streamerUrl: StreamEndpoint
-      watcherUrl: MultiFormat<StreamEndpoint>
-      recordings: MultiFormat<StreamRecording>[]
-    }
-    & Amity.Metadata
-    & Amity.Timestamps
-    & Amity.SoftDelete
-    & Amity.Syncable
+      streamerUrl: StreamEndpoint;
+      watcherUrl: MultiFormat<StreamEndpoint>;
+      recordings: MultiFormat<StreamRecording>[];
+    } & Amity.Metadata &
+      Amity.Timestamps &
+      Amity.SoftDelete;
   }
 }

package/src/@types/domains/subChannel.ts

@@ -0,0 +1,50 @@
+export {};
+
+declare global {
+  namespace Amity {
+    type RawSubChannel = {
+      channelId: string;
+      channelPublicId: string;
+      channelType: Amity.ChannelType;
+      childCount: number;
+      creatorId: string;
+      creatorPublicId: string;
+      editedAt?: Amity.timestamp;
+      isDeleted: boolean;
+      messageFeedId: string;
+      lastMessageId: string;
+      lastMessageTimestamp: Amity.timestamp;
+      name: string;
+    } & Amity.Timestamps &
+      Amity.Subscribable;
+
+    type SubChannel = {
+      channelId: string;
+      creatorId: string;
+      displayName: string;
+      editedAt?: Amity.timestamp;
+      isDeleted: boolean;
+      messageCount: number;
+      lastActivity: Amity.timestamp;
+      latestMessageId: string;
+      subChannelId: string;
+      isUnreadCountSupport: boolean;
+      unreadCount: number;
+    } & Amity.Timestamps &
+      Amity.Subscribable;
+
+    type QuerySubChannels = {
+      channelId: Amity.Channel['channelId'];
+      excludeDefaultSubChannel?: boolean;
+      includeDeleted?: boolean;
+      page?: Amity.Page;
+    };
+
+    type SubChannelLiveCollection = Amity.LiveCollectionParams<Omit<QuerySubChannels, 'page'>>;
+
+    type SubChannelLiveCollectionCache = Amity.LiveCollectionCache<
+      Amity.SubChannel,
+      Pick<QuerySubChannels, 'page'>
+    >;
+  }
+}

package/src/@types/domains/user.ts

@@ -1,18 +1,42 @@
-export {}
+export {};
 
 declare global {
   namespace Amity {
+    type UserActionType =
+      | 'onFetch'
+      | 'onUpdate'
+      | 'onDelete'
+      | 'onFlagged'
+      | 'onUnflagged'
+      | 'onFlagCleared';
+
     type User = {
-      userId: string
-      displayName?: string
-      avatarFileId?: Amity.File<'image'>['fileId']
-      description?: string
-    }
-    & Amity.Metadata
-    & Amity.Taggable
-    & Amity.Flaggable
-    & Amity.Accredited
-    & Amity.Timestamps
-    & Amity.Syncable
+      _id: string;
+      userId: string;
+      displayName?: string;
+      avatarFileId?: Amity.File<'image'>['fileId'];
+      avatarCustomUrl?: string;
+      description?: string;
+    } & Amity.Metadata &
+      Amity.Taggable &
+      Amity.Flaggable &
+      Amity.Accredited &
+      Amity.Timestamps &
+      Amity.SoftDelete &
+      Amity.Subscribable;
+
+    type QueryUsers = {
+      displayName?: Amity.User['displayName'];
+      filter?: 'all' | 'flagged';
+      sortBy?: 'displayName' | 'firstCreated' | 'lastCreated';
+      page?: Amity.Page;
+    };
+
+    type UserLiveCollection = Amity.LiveCollectionParams<Omit<QueryUsers, 'page'>>;
+
+    type UserLiveCollectionCache = Amity.LiveCollectionCache<
+      Amity.User['userId'],
+      Pick<QueryUsers, 'page'>
+    >;
   }
 }

package/src/@types/global.ts

@@ -1,25 +1,65 @@
-export {}
+export {};
 
 declare global {
-  type Writeable<T> = { -readonly [P in keyof T]: T[P] }
+  type Writeable<T> = { -readonly [P in keyof T]: T[P] };
 
-  type Patch<T, K extends keyof T> = Partial<Pick<T, K>>
+  type Patch<T, K extends keyof T> = Partial<Pick<T, K>>;
 
-  type Unwrap<T> = (
-    T extends Promise<infer U> ? U :
-    T extends (...args: any) => Promise<infer U> ? U :
-    T extends (...args: any) => infer U ? U :
-    T
-  )
+  type Unwrap<T> = T extends Promise<infer U>
+    ? U
+    : T extends (...args: any) => Promise<infer U>
+    ? U
+    : T extends (...args: any) => infer U
+    ? U
+    : T;
+
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  type ObjectKeys<T> = T extends object
+    ? (keyof T)[]
+    : T extends number
+    ? []
+    : T extends Array<any> | string
+    ? string[]
+    : never;
 
   interface ObjectConstructor {
-    keys<T>(o: T): ObjectKeys<T>
+    keys<T>(o: T): ObjectKeys<T>;
+  }
+
+  type ValueOf<T extends Record<any, any>> = T[keyof T];
+
+  /**
+   *  Make properties required otherwise optional
+   */
+  type MakeRequired<T, K extends keyof T> = Required<Pick<T, K>> & Partial<T>;
+
+  /**
+   *  Make properties optional otherwise required
+   */
+  type MakeOptional<T, K extends keyof T> = Partial<Pick<T, K>> & Required<T>;
+}
+
+/*
+ * Extented to pass token expiry into request config, for internal use only.
+ * Since it's in the request config, it does not get sent for the server, and
+ * allows us to intercept the tokenExpiry value to check if the token has not
+ * expired & cancel the request if yes.
+ *
+ */
+declare module 'axios' {
+  interface MetaData {
+    tokenExpiry: string;
+    isGlobalBanned: boolean;
+    isUserDeleted: boolean;
   }
 
-  type ObjectKeys<T> =  (
-    T extends object ? (keyof T)[] :
-    T extends number ? [] :
-    T extends Array<any> | string ? string[] :
-    never
-  )
+  export interface AxiosDefaults {
+    // expires at iso string for access token
+    metadata?: MetaData;
+  }
+
+  export interface AxiosRequestConfig {
+    // expires at iso string for access token
+    metadata?: MetaData;
+  }
 }

package/src/@types/index.ts

@@ -1,31 +1,39 @@
-import './global' // global types (system)
+import './global'; // global types (system)
 
-import './core/errors' // global errors
-import './core/permissions' // permissions enum
+import './core/errors'; // global errors
+import './core/permissions'; // permissions enum
 
-import './core/payload' // backend payload definition
-import './core/events' // sdk events definitions
-import './core/query' // createQuery, runQuery
-import './core/store' // store definition
-import './core/cache' // cache.pull('user', ...)
+import './core/payload'; // backend payload definition
+import './core/events'; // sdk events definitions
+import './core/paging'; // createQuery, runQuery
+import './core/query'; // createQuery, runQuery
+import './core/cache'; // cache.pull('user', ...)
+import './core/live';
 
 // domains
-import './domains/client' // client definition
+import './domains/client'; // client definition
 
-import './domains/user'
-import './domains/file'
+import './domains/user';
+import './domains/follow';
 
-import './domains/partials' // small model partials (CreatedAt, etc...)
-import './domains/content' // content partial
-import './domains/reaction'
+import './domains/partials'; // small model partials (CreatedAt, etc...)
+import './domains/reaction';
 
-import './domains/group'
-import './domains/channel'
-import './domains/message'
+import './domains/group';
+import './domains/channel';
+import './domains/subChannel';
 
-import './domains/community'
-import './domains/category'
-import './domains/post'
-import './domains/comment'
+import './domains/category';
+import './domains/comment';
 
-import './domains/stream'
+import './domains/stream';
+
+import './domains/mention';
+
+import './domains/poll';
+
+export * from './domains/community';
+export * from './domains/content';
+export * from './domains/file';
+export * from './domains/message';
+export * from './domains/post';

package/src/@types/mqtt.d.ts

@@ -0,0 +1,3 @@
+declare module 'mqtt/dist/mqtt' {
+  export * from 'mqtt';
+}

package/src/cache/api/backupCache.ts

@@ -0,0 +1,48 @@
+import AsyncStorage from '@react-native-async-storage/async-storage';
+
+import { getActiveClient } from '~/client/api/activeClient';
+
+/**
+ * ```js
+ * import { backupCache } from '@amityco/ts-sdk'
+ * const success = await backupCache()
+ * ```
+ *
+ * Writes the {@link Amity.Cache} to a persistent storage.
+ *
+ * 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
+ * @param persistIf a custom function to define the persistence policy. Default
+ * will check the value of {@link Amity.CacheEntry["offline"]}, which can be
+ * defined globally when customizing {@link Amity.Cache["persistIf"]}
+ * @returns a success boolean if the cache was dumped to persistent storage
+ *
+ * @category Cache API
+ */
+export const backupCache = async (
+  storageKey = 'amitySdk',
+  persistIf = (entry: Amity.CacheEntry) => entry.offline,
+): Promise<boolean> => {
+  const { log, cache, userId } = getActiveClient();
+
+  if (!cache) return false;
+  log('cache/api/backupCache', { storageKey });
+
+  // prepare a subset of the cache where only
+  // objects to backup are there
+  const offlineEntries = Object.fromEntries(
+    Object.entries(cache.data).filter(([_, entry]) => persistIf(entry)),
+  );
+
+  // nothing to backup, abort
+  if (!Object.keys(offlineEntries).length) return false;
+
+  await AsyncStorage.setItem(`${storageKey}#${userId}`, JSON.stringify(offlineEntries));
+
+  return true;
+};

package/src/cache/api/disableCache.ts

@@ -0,0 +1,23 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+/**
+ * ```js
+ * import { disableCache } from '@amityco/ts-sdk'
+ * disableCache()
+ * ```
+ *
+ * Wipes the existing {@link Amity.Cache} object attached to
+ * an {@link Amity.Client} instance
+ *
+ * @category Cache API
+ */
+export const disableCache = () => {
+  const client = getActiveClient();
+
+  if (!client.cache) return;
+  client.log('cache/api/disableCache');
+
+  // we do this so that testing if cache is enabled
+  // is only `if (client.cache)
+  delete client.cache;
+};

package/src/cache/api/dropFromCache.ts

@@ -0,0 +1,41 @@
+import { getActiveClient } from '~/client/api/activeClient';
+import { decodeKey, encodeKey, partialMatch } from '../utils';
+
+/**
+ * ```js
+ * import { dropFromCache } from '@amityco/ts-sdk'
+ * const success = dropFromCache(['user', 'foobar'])
+ * ```
+ *
+ * Removes an existing {@link Amity.CacheEntry} from the {@link Amity.Client}'s
+ * {@link Amity.Cache} from a given {@link Amity.CacheKey}
+ *
+ * @param key The key of the object to delete
+ * @param exact If false, the function will delete all keys satisfying the given key
+ * @returns A success boolean if the object was deleted
+ *
+ * @category Cache API
+ */
+export const dropFromCache = (key: Amity.CacheKey, exact = false): boolean => {
+  const { log, cache } = getActiveClient();
+
+  if (!cache) return false;
+  log('cache/api/dropFromCache', { key, exact });
+
+  if (!exact) {
+    return Object.keys(cache.data)
+      .map(stringKey => decodeKey(stringKey))
+      .filter(candidate => partialMatch(key, candidate))
+      .map<boolean>(filteredKey => dropFromCache(filteredKey, true))
+      .every(returned => returned);
+  }
+
+  const encodedKey = encodeKey(key);
+
+  if (encodedKey in cache.data) {
+    delete cache.data[encodedKey];
+    return true;
+  }
+
+  return false;
+};

package/src/cache/api/enableCache.ts

@@ -0,0 +1,29 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+/**
+ * ```js
+ * import { enableCache } from '@amityco/ts-sdk'
+ * enableCache()
+ * ```
+ *
+ * Adds a new {@link Amity.Cache} object to
+ * an {@link Amity.Client} instance
+ *
+ * @param prevState a previous state of cache instance (useful for SSR)
+ * @param persistIf a function to determine if an entry inserted in cache
+ * is destined to be also saved in the persistent storage when
+ * calling {@link backupCache}
+ *
+ * @category Cache API
+ */
+export const enableCache = (
+  prevState: Amity.Cache['data'] = {},
+  persistIf?: Amity.Cache['persistIf'],
+) => {
+  const client = getActiveClient();
+
+  if (client.cache) return;
+  client.log('cache/api/enableCache');
+
+  client.cache = { data: prevState, persistIf };
+};

package/src/cache/api/index.ts

@@ -0,0 +1,24 @@
+// on/off
+export * from './enableCache';
+export * from './disableCache';
+
+// persistency
+export * from './restoreCache';
+export * from './backupCache';
+export * from './wipeCache';
+
+// fetch
+export * from './queryCache';
+export * from './pullFromCache';
+
+// mutate
+export * from './pushToCache';
+export * from './mergeInCache';
+export * from './upsertInCache';
+export * from './dropFromCache';
+
+/*
+ * ingestInCache and syncInCache and isInTombstone
+ * and pushToTombstone are not exported ;
+ * we don't want it as part of the sdk's public api.
+ */

package/src/cache/api/ingestInCache.ts

@@ -0,0 +1,29 @@
+import { PAYLOAD2MODEL, getResolver } from '~/core/model';
+
+import { upsertInCache } from './upsertInCache';
+
+/**
+ * Ingest a payload (v3) into the cache
+ *
+ * @param payload a "backend v3" payload object
+ * @param options caching options like cachedAt or offline
+ *
+ * @category Cache
+ * @hidden
+ */
+export const ingestInCache = (
+  payload: Record<keyof typeof PAYLOAD2MODEL, Amity.Model[]> = {},
+  options?: Amity.CacheOptions,
+) => {
+  Object.entries(payload).forEach(([key, models]) => {
+    const type = PAYLOAD2MODEL[key];
+    if (!type) return;
+
+    const resolver = getResolver(type);
+    if (!resolver) return;
+
+    models.forEach(model => {
+      upsertInCache([type, 'get', resolver(model)], model, options);
+    });
+  });
+};

package/src/cache/api/isInTombstone.ts

@@ -0,0 +1,41 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { ASCApiError } from '~/core/errors';
+import { pullFromCache } from '~/cache/api';
+import { isFresh, queryOptions } from '~/core/query';
+import { CACHE_KEY_TOMBSTONE, CACHE_LIFESPAN_TOMBSTONE } from '~/cache/utils';
+
+/**
+ * ```js
+ * import { isInTombstone } from '@amityco/ts-sdk'
+ * const user = isInTombstone(["message", "messageId"])
+ * ```
+ *
+ * Checks if the {@link Amity.TombstoneCacheOptions} exists
+ * in cache and it's not expired means it's in tombstone
+ * and we throw an Error
+ *
+ * @param model the model to check
+ * @param modelId the object id to check
+ * @returns the matching cache entry, or undefined.
+ *
+ * @category Cache API
+ */
+export const isInTombstone = (model: Amity.Domain, modelId: string) => {
+  const { log, cache } = getActiveClient();
+  const key = [model, CACHE_KEY_TOMBSTONE, modelId];
+
+  if (!cache) return;
+  log('cache/api/isInTombstone', key);
+
+  const isInTombstone = pullFromCache<Amity.TombstoneCacheOptions>(key);
+  const { lifeSpan } = queryOptions('cache_then_server', CACHE_LIFESPAN_TOMBSTONE);
+
+  if (isInTombstone && isFresh(isInTombstone.data, lifeSpan)) {
+    throw new ASCApiError(
+      'Item not found!',
+      Amity.ServerError.ITEM_NOT_FOUND,
+      Amity.ErrorLevel.ERROR,
+    );
+  }
+};

package/src/cache/api/mergeInCache.ts

@@ -0,0 +1,43 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { pullFromCache } from './pullFromCache';
+import { pushToCache } from './pushToCache';
+
+/**
+ * ```js
+ * import { mergeInCache } from '@amityco/ts-sdk'
+ *
+ * mergeInCache(
+ *   ["foo", "bar"],
+ *   (oldVal) => ({ ...oldVal, ...newVal }).
+ * )
+ * ```
+ *
+ * Merges a new {@link Amity.Cache} object to an {@link Amity.Client} instance
+ *
+ * @param key the key matching the object to retrieve from cache
+ * @param mutation either a plain object to shallow merge, or a function.
+ * @returns a success boolean if the object was updated
+ *
+ * @category Cache API
+ */
+export const mergeInCache = <T extends Record<string, unknown>>(
+  key: Amity.CacheKey,
+  mutation: Partial<T> | ((oldVal: T) => T),
+  options?: Amity.CacheOptions,
+): boolean => {
+  const { log, cache } = getActiveClient();
+
+  if (!cache) return false;
+  log('cache/api/mergeInCache', { key, mutation });
+
+  const oldVal = pullFromCache<T>(key);
+
+  if (!oldVal) return false;
+
+  const newVal =
+    typeof mutation === 'function' ? mutation(oldVal.data) : { ...oldVal.data, ...mutation };
+
+  pushToCache(key, newVal, options);
+  return true;
+};

package/src/cache/api/pullFromCache.ts

@@ -0,0 +1,31 @@
+import { getActiveClient } from '~/client/api/activeClient';
+
+import { encodeKey } from '../utils';
+
+/**
+ * ```js
+ * import { pullFromCache } from '@amityco/ts-sdk'
+ * const user = pullFromCache<Amity.User>(["user", "foobar"])
+ * ```
+ *
+ * Retrieves a {@link Amity.CacheEntry} object matching a given
+ * {@link Amity.CacheKey}. The cache entry is not typed, so the
+ * expected returned type must be passed manually.
+ *
+ * @param key the key matching the object to retrieve from cache
+ * @returns the matching cache entry, or undefined.
+ *
+ * @category Cache API
+ */
+export const pullFromCache = <T extends unknown>(
+  key: Amity.CacheKey,
+): Amity.CacheEntry<T> | undefined => {
+  const { log, cache } = getActiveClient();
+
+  if (!cache) return;
+  log('cache/api/pullFromCache', key);
+
+  const str = encodeKey(key);
+
+  return cache.data[str] ? (cache.data[str] as Amity.CacheEntry<T>) : undefined;
+};