@amityco/ts-sdk 0.0.1-be4fc2f.0 → 0.0.1-beta.10

package/src/@types/core/paging.ts

@@ -0,0 +1,75 @@
+export {}
+
+declare global {
+  namespace Amity {
+    type SkipLimitPagination = {
+      skip?: number
+      limit?: number
+    }
+
+    /*
+      WARNING:
+      in traditional "before/after" pagination, 'before' and 'after'
+      normally should be strings representing the unique id of the
+      resource. for some reason, our backend uses a number instead,
+      bound to "channelSegment" (for message) and "segmentNumber" (
+      for comments). so we have to cast this as number.
+    */
+    type AfterBeforePagination = {
+      before?: number
+      after?: number
+      first?: number
+      last?: number
+    }
+
+    type PrevPage = {
+      after?: never
+      before?: number
+      limit: number
+    }
+
+    type NextPage = {
+      after?: number
+      before?: never
+      limit: number
+    }
+
+    type Page = (PrevPage | NextPage)
+
+    type Pages = {
+      nextPage?: Page | null
+      prevPage?: Page | null
+    }
+
+    type Paged<T> = { data: T[] } & Pages
+
+    type AfterBeforeRawPagination = {
+      before?: string
+      after?: string
+      updatedAt?: string
+    }
+
+    type PrevPageRaw = {
+      after?: never
+      before?: string
+      limit: number
+      updatedAt?: string
+    }
+
+    type NextPageRaw = {
+      after?: string
+      before?: never
+      limit: number
+      updatedAt?: string
+    }
+
+    type PageRaw = (PrevPageRaw | NextPageRaw)
+
+    type PagesRaw = {
+      nextPage?: PageRaw | null
+      prevPage?: PageRaw | null
+    }
+
+    type PagedRaw<T> = { data: T[] } & PagesRaw
+  }
+}

package/src/@types/core/permissions.ts

@@ -71,6 +71,5 @@ declare global {
     }
     & Amity.Timestamps
     & Amity.SoftDelete
-    & Amity.Syncable
   }
 }

package/src/@types/core/query.ts

@@ -2,14 +2,12 @@ export {}
 
 declare global {
   namespace Amity {
-    type Syncable = {
-      localId: string
-      syncedAt: number
+    type Cachable = {
+      cachedAt: number
     }
 
     type Local = {
-      localId: string
-      syncedAt: -1
+      cachedAt: -1
     }
 
     type AsyncFunc<Args extends any[], Returned extends any> = {
@@ -18,12 +16,12 @@ declare global {
 
     type FetcherFunc<Args extends any[], Returned extends any> = {
       (...args: Args): Promise<Returned>
-      locally: (...args: Args) => Returned
+      locally: (...args: Args) => Returned | undefined
     }
 
     type MutatorFunc<Args extends any[], Returned extends any> = {
       (...args: Args): Promise<Returned>
-      optimistically: (...args: Args) => Returned
+      optimistically: (...args: Args) => Returned | undefined
     }
 
     type OfflineFunc<Args extends any[], Returned extends any> = (
@@ -41,55 +39,16 @@ declare global {
       lifeSpan: number
     }
 
-    type QueryMetadata = {
-      origin?: 'local' | 'server',
-      loading?: boolean,
-      error?: Error,
+    type SnapshotOptions = {
+      origin: 'local' | 'server' | 'event'
+      loading: boolean
+      error?: any
     }
 
-    type QueryResult<T> = T extends Amity.Paged<infer U>
-      ? { data?: U } & Amity.Pages & QueryMetadata
-      : { data?: T } & QueryMetadata
-
-    type SkipLimitPagination = {
-      skip?: number
-      limit?: number
-    }
-
-    /*
-      WARNING:
-      in traditional "before/after" pagination, 'before' and 'after'
-      normally should be strings representing the unique id of the
-      resource. for some reason, our backend uses a number instead,
-      bound to "channelSegment" (for message) and "segmentNumber" (
-      for comments). so we have to cast this as number.
-    */
-    type AfterBeforePagination = {
-      before?: number
-      after?: number
-      first?: number
-      last?: number
-    }
-
-    type PrevPage = {
-      after?: never
-      before?: number
-      limit: number
-    }
-
-    type NextPage = {
-      after?: number
-      before?: never
-      limit: number
-    }
-
-    type Page = (PrevPage | NextPage)
-
-    type Pages = {
-      nextPage: Page | null
-      prevPage: Page | null
-    }
-
-    type Paged<T> = { data: T } & Pages
+    type Snapshot<T> = (
+      T extends Amity.Cached<infer K> ? { data: K } :
+      T extends (Amity.PagedRaw<any> | Amity.Paged<any>) ? T :
+      { data: T }
+    ) & SnapshotOptions
   }
 }

package/src/@types/core/transport.ts

@@ -1,3 +1,5 @@
+import { ASCError } from '~/core/errors'
+
 export {}
 
 declare global {
@@ -37,8 +39,8 @@ declare global {
       once: <T extends keyof Amity.MqttEvents>(event: T, handler: (payload: Amity.MqttEvents[T]) => void) => void
       off: <T extends keyof Amity.MqttEvents>(event: T, handler?: (payload: Amity.MqttEvents[T]) => void) => void
       removeAllListeners: () => void
-      subscribe: (topic: string, handler?: (error: Error, granted: Object) => void) => void
-      unsubscribe: (topic: string, handler?: (payload: Object) => void) => void
+      subscribe: (topic: string, callback?: Amity.Listener<ASCError | void>) => Amity.Unsubscriber
+      unsubscribe: (topic: string) => void
     }
   }
 }

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

@@ -10,6 +10,5 @@ declare global {
     & Amity.Metadata
     & Amity.Timestamps
     & Amity.SoftDelete
-    & Amity.Syncable
   }
 }

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

@@ -33,6 +33,5 @@ declare global {
     & Amity.Taggable
     & Amity.Timestamps
     & Amity.SoftDelete
-    & Amity.Syncable
   }
 }

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

@@ -18,6 +18,8 @@ declare global {
 
       apiKey?: string
       userId?: string
+      user?: Amity.User
+      accessToken?: string
 
       use: () => void
     }

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

@@ -21,7 +21,6 @@ declare global {
     & Amity.Reactable
     & Amity.Timestamps
     & Amity.SoftDelete
-    & Amity.Syncable
     & Amity.Subscribable
   }
 }

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

@@ -30,7 +30,6 @@ declare global {
     & Amity.Metadata
     & Amity.Timestamps
     & Amity.SoftDelete
-    & Amity.Syncable
     & Amity.Subscribable
   }
 }

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

@@ -4,30 +4,32 @@ declare global {
   namespace Amity {
     type ContentType = ('text' | 'image' | 'file' | 'video' | 'json' | string)
 
-    type ContentDataText = { text: string }
-    type ContentDataFile = { fileId: Amity.File<'file'>['fileId'] }
-    type ContentDataImage = { imageId: Amity.File<'image'>['fileId'] }
-    type ContentDataVideo = { videoId: Amity.File<'file'>['fileId'] }
+    type ContentDataText = {
+      text: string
+    }
+
+    type ContentDataFile = {
+      fileId: Amity.File<'file'>['fileId']
+    }
+
+    type ContentDataImage = {
+      imageId: Amity.File<'image'>['fileId']
+    }
+
+    type ContentDataVideo = {
+      videoId: Amity.File<'file'>['fileId']
+    }
 
     type ContentData<T extends ContentType> = (
       T extends 'text'  ? ContentDataText :
       T extends 'file'  ? ContentDataFile :
       T extends 'image' ? ContentDataImage :
       T extends 'video' ? ContentDataVideo :
-      T extends 'json'  ? object :
-      T extends string  ? any : // custom type
+      T extends 'json'  ? Record<string, unknown> :
+      T extends string  ? string | Record<string, unknown> : // custom type
       never
     )
 
-    type ContentTypeFor<T> = (
-      T extends ContentDataText ? 'text' :
-      T extends ContentDataFile ? 'file' :
-      T extends ContentDataImage ? 'image' :
-      T extends ContentDataVideo ? 'video' :
-      T extends object ? 'json' :
-      'custom'
-    )
-
     type Content<T extends ContentType, K extends 'type' | 'dataType' = 'dataType'> = (
       { [S in K]?: T } & { data: ContentData<T> }
     )

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

@@ -36,6 +36,5 @@ declare global {
     }
     & Amity.Timestamps
     & Amity.SoftDelete
-    & Amity.Syncable
   }
 }

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

@@ -13,12 +13,12 @@ declare global {
     } & (
       T extends 'channel' ? {
         channelId: Amity.Channel['channelId']
-        membership: 'member' | 'notMember' | 'banned'
+        membership: 'member' | 'none' | 'banned'
         readToSegment: number
       } :
       T extends 'community' ? {
         communityId: Amity.Community['communityId']
-        communityMembership: 'member' | 'notMember' | 'banned'
+        communityMembership: 'member' | 'none' | 'banned'
       } :
       never
     )
@@ -33,6 +33,5 @@ declare global {
     }
     & Member<T>
     & Amity.Accredited
-    & Amity.Syncable
   }
 }

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

@@ -21,7 +21,6 @@ declare global {
     & Amity.Metadata
     & Amity.Timestamps
     & Amity.SoftDelete
-    & Amity.Syncable
     & Amity.Reactable
   }
 }

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

@@ -20,13 +20,13 @@ declare global {
       hasFlaggedChildren: false
       hasFlaggedComment: false
       editedAt: timestamp,
-    } & Amity.Content<T, 'dataType'> &
-      Amity.Metadata &
-      Amity.Flaggable &
-      Amity.Reactable &
-      Amity.Timestamps &
-      Amity.SoftDelete &
-      Amity.Syncable
-      & Amity.Subscribable
+    }
+    & Amity.Content<T, 'dataType'>
+    & Amity.Metadata
+    & Amity.Flaggable
+    & Amity.Reactable
+    & Amity.Timestamps
+    & Amity.SoftDelete
+    & Amity.Subscribable
   }
 }

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

@@ -64,6 +64,5 @@ declare global {
     & Amity.Metadata
     & Amity.Timestamps
     & Amity.SoftDelete
-    & Amity.Syncable
   }
 }

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

@@ -3,6 +3,7 @@ export {}
 declare global {
   namespace Amity {
     type User = {
+      _id: string
       userId: string
       displayName?: string
       avatarFileId?: Amity.File<'image'>['fileId']
@@ -13,7 +14,6 @@ declare global {
     & Amity.Flaggable
     & Amity.Accredited
     & Amity.Timestamps
-    & Amity.Syncable
     & Amity.Subscribable
   }
 }

package/src/@types/index.ts

@@ -5,8 +5,8 @@ import './core/permissions' // permissions enum
 
 import './core/payload' // backend payload definition
 import './core/events' // sdk events definitions
+import './core/paging' // createQuery, runQuery
 import './core/query' // createQuery, runQuery
-import './core/store' // store definition
 import './core/cache' // cache.pull('user', ...)
 
 // domains

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,53 @@
+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: string = 'amitySdk',
+  persistIf = (entry: Amity.CacheEntry) => entry.offline,
+) => {
+  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,44 @@
+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: boolean = 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,23 @@
+// 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 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,33 @@
+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 order the order of the keys to process (in case of need)
+ *
+ * @category Cache
+ * @hidden
+ */
+export const ingestInCache = (
+  payload: Record<string, Record<string, unknown>[]> = {},
+  options?: Amity.CacheOptions,
+) => {
+  Object.entries(payload)
+    .forEach(([key, models]) => {
+      const type = PAYLOAD2MODEL[key];
+      if (!type) return
+
+      const resolver = getResolver(type);
+      models.forEach(model => {
+        upsertInCache(
+          // eslint-disable @typescript-eslint no-explicit-any
+          [type, 'get', resolver(model as any)], // this 'any' cannot be avoided, sorry.
+          model,
+          options,
+        );
+      })
+    })
+}

package/src/cache/api/mergeInCache.ts

@@ -0,0 +1,45 @@
+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 {}>(
+  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;
+};