@ohbug/core 1.1.7 → 2.0.0

package/src/client.ts

@@ -0,0 +1,210 @@
+import type {
+  OhbugAction,
+  OhbugClient,
+  OhbugClientConstructor,
+  OhbugClientConstructorValues,
+  OhbugConfig,
+  OhbugCreateEvent,
+  OhbugEventWithMethods,
+  OhbugExtension,
+  OhbugGetDevice,
+  OhbugLoggerConfig,
+  OhbugMetaData,
+  OhbugNotifier,
+  OhbugSDK,
+  OhbugUser,
+} from '@ohbug/types'
+import { isObject, isString } from '@ohbug/utils'
+
+import { schema as baseSchema } from './config'
+import { createEvent, handleEventCreated, isEvent } from './event'
+import { notify } from './notify'
+import { Action } from './action'
+import { verifyConfig } from './lib/verifyConfig'
+import { getConfigErrorMessage, getErrorMessage } from './lib/getErrorMessage'
+import { addMetaData, deleteMetaData, getMetaData } from './lib/metaData'
+
+export const Client: OhbugClientConstructor = class Client
+implements OhbugClient {
+  readonly __sdk: OhbugSDK
+
+  readonly __config: OhbugConfig
+
+  readonly __logger: OhbugLoggerConfig
+
+  readonly __device: OhbugGetDevice
+
+  readonly __notifier: OhbugNotifier
+
+  readonly __extensions: OhbugExtension[]
+
+  readonly __actions: OhbugAction[]
+
+  __user: OhbugUser
+
+  readonly __metaData: OhbugMetaData
+
+  constructor({
+    sdk,
+    config: baseConfig,
+    schema = baseSchema,
+    device,
+    notifier,
+  }: OhbugClientConstructorValues) {
+    const { config, errors } = verifyConfig(baseConfig, schema)
+
+    // initialization
+    this.__sdk = sdk
+    this.__config = config
+    this.__logger = config.logger
+    this.__device = device
+    this.__notifier = notifier
+
+    this.__extensions = []
+
+    this.__actions = []
+    this.__user = config.user
+    this.__metaData = {}
+    if (isObject(config.metaData)) {
+      Object.keys(config.metaData).forEach((key) => {
+        this.addMetaData(key, config.metaData[key])
+      })
+    }
+
+    if (Object.keys(errors).length)
+      this.__logger.warn(getConfigErrorMessage(errors, baseConfig))
+  }
+
+  /**
+   * Load extension
+   * 加载扩展
+   *
+   * @param extension
+   */
+  use(extension: OhbugExtension): OhbugClient {
+    this.__extensions.push(extension)
+    extension.setup?.(this)
+    return this
+  }
+
+  /**
+   * Create an event, you will get a data body containing device actions and other information
+   * 创建事件，将会得到一个含有 device actions 等信息的数据体
+   *
+   * @param value
+   */
+  createEvent<D = any>(value: OhbugCreateEvent<D>): OhbugEventWithMethods<D> | null {
+    const event = createEvent(value, this)
+
+    return handleEventCreated(event, this)
+  }
+
+  /**
+   * Used to trigger the reporting interface
+   * 用于触发上报接口
+   *
+   * @param eventLike
+   * @param beforeNotify
+   */
+  notify<D = any>(
+    eventLike: any,
+    beforeNotify?: (
+      event: OhbugEventWithMethods<D> | null
+    ) => OhbugEventWithMethods<D> | null,
+  ): Promise<any | null> {
+    let event: OhbugEventWithMethods<D> | null
+    if (Boolean(eventLike) && !isEvent(eventLike))
+      event = this.createEvent(eventLike)
+    else
+      event = eventLike
+
+    if (beforeNotify) event = beforeNotify(event)
+
+    return notify<D>(event, this)
+  }
+
+  /**
+   * Add an action.
+   * Once the threshold is reached, the oldest breadcrumbs will be deleted.
+   * 新增一个动作。
+   * 一旦达到阈值，最老的 Action 将被删除。
+   *
+   * @param message
+   * @param data
+   * @param type
+   * @param timestamp
+   */
+  addAction(
+    message: string,
+    data: Record<string, any>,
+    type: string,
+    timestamp?: string,
+  ): void {
+    const actions = this.__actions
+
+    const targetMessage = isString(message) ? message : ''
+    const targetData = data || {}
+    const targetType = isString(type) ? type : ''
+
+    const action = new Action(targetMessage, targetData, targetType, timestamp)
+    if (actions.length >= this.__config.maxActions!)
+      actions.shift()
+
+    actions.push(action)
+  }
+
+  /**
+   * Get current user information
+   * 获取当前的用户信息
+   */
+  getUser(): OhbugUser | undefined {
+    return this.__user
+  }
+
+  /**
+   * Set current user information
+   * 设置当前的用户信息
+   */
+  setUser(user: OhbugUser): OhbugUser | undefined {
+    if (isObject(user) && Object.keys(user).length <= 6) {
+      this.__user = { ...this.__user, ...user }
+      return this.getUser()
+    }
+    this.__logger.warn(getErrorMessage(
+      'setUser should be an object and have up to 6 attributes',
+      user,
+    ))
+    return undefined
+  }
+
+  /**
+   * Add metaData
+   * 新增 metaData
+   *
+   * @param section
+   * @param data
+   */
+  addMetaData(section: string, data: any) {
+    return addMetaData(this.__metaData, section, data)
+  }
+
+  /**
+   * Get metaData
+   * 获取 metaData
+   *
+   * @param section
+   */
+  getMetaData(section: string) {
+    return getMetaData(this.__metaData, section)
+  }
+
+  /**
+   * Delete metaData
+   * 删除 metaData
+   *
+   * @param section
+   */
+  deleteMetaData(section: string) {
+    return deleteMetaData(this.__metaData, section)
+  }
+}

package/src/config.ts

@@ -0,0 +1,75 @@
+import { isFunction, isNumber, isObject, isString, logger } from '@ohbug/utils'
+import type { OhbugEventWithMethods, OhbugSchema } from '@ohbug/types'
+
+export const schema: OhbugSchema = {
+  // base
+  apiKey: {
+    defaultValue: undefined,
+    message: 'is required',
+    validate: value => Boolean(value) && isString(value),
+  },
+  appVersion: {
+    defaultValue: undefined,
+    message: 'should be a string',
+    validate: value => value === undefined || isString(value),
+  },
+  appType: {
+    defaultValue: undefined,
+    message: 'should be a string',
+    validate: value => value === undefined || isString(value),
+  },
+  releaseStage: {
+    defaultValue: 'production',
+    message: 'should be a string',
+    validate: value => value === undefined || isString(value),
+  },
+  endpoint: {
+    defaultValue: 'http://localhost:6660',
+    message: 'should be a string',
+    validate: value => value === undefined || isString(value),
+  },
+  maxActions: {
+    defaultValue: 30,
+    message: 'should be a number between 0 and 100',
+    validate: value =>
+      value === undefined || (isNumber(value) && value >= 1 && value <= 100),
+  },
+  // hooks
+  created: {
+    defaultValue: (event: OhbugEventWithMethods<any>) => event,
+    message: 'should be a function',
+    validate: value => value === undefined || isFunction(value),
+  },
+  notified: {
+    defaultValue: () => {},
+    message: 'should be a function',
+    validate: value => value === undefined || isFunction(value),
+  },
+  // utils
+  logger: {
+    defaultValue: logger,
+    message:
+      'should be null or an object with methods { log, info, warn, error }',
+    validate: value =>
+      value === undefined
+      || (value
+        && ['log', 'info', 'warn', 'error'].reduce<boolean>(
+          (accumulator, method) =>
+            accumulator && typeof value[method] === 'function',
+          true,
+        )),
+  },
+  // data
+  user: {
+    defaultValue: undefined,
+    message: 'should be an object and have up to 6 attributes',
+    validate: value =>
+      value === undefined
+      || (isObject(value) && Object.keys(value).length <= 6),
+  },
+  metaData: {
+    defaultValue: undefined,
+    message: 'should be an object',
+    validate: value => value === undefined || isObject(value),
+  },
+}

package/src/event.ts

@@ -0,0 +1,276 @@
+import type {
+  OhbugAction,
+  OhbugCategory,
+  OhbugClient,
+  OhbugCreateEvent,
+  OhbugDevice,
+  OhbugEvent,
+  OhbugEventWithMethods,
+  OhbugMetaData,
+  OhbugReleaseStage,
+  OhbugSDK,
+  OhbugUser,
+} from '@ohbug/types'
+
+import { isFunction, isObject, isString } from '@ohbug/utils'
+import { Action } from './action'
+import { getErrorMessage } from './lib/getErrorMessage'
+import { addMetaData, deleteMetaData, getMetaData } from './lib/metaData'
+
+export class Event<D> implements OhbugEventWithMethods<D> {
+  readonly apiKey: string
+
+  readonly appVersion?: string
+
+  readonly appType?: string
+
+  readonly timestamp: string
+
+  readonly category?: OhbugCategory
+
+  readonly type: string
+
+  readonly sdk: OhbugSDK
+
+  readonly device: OhbugDevice
+
+  readonly detail: D
+
+  user?: OhbugUser
+
+  readonly actions?: OhbugAction[]
+
+  readonly metaData: OhbugMetaData
+
+  readonly releaseStage?: OhbugReleaseStage
+
+  readonly __client?: OhbugClient
+
+  constructor(values: OhbugEvent<D>, client?: OhbugClient) {
+    const {
+      apiKey,
+      appVersion,
+      appType,
+      releaseStage,
+      timestamp,
+      category,
+      type,
+      sdk,
+
+      detail,
+      device,
+      user,
+      actions,
+      metaData,
+    } = values
+    this.apiKey = apiKey
+    this.appVersion = appVersion
+    this.appType = appType
+    this.releaseStage = releaseStage
+    this.timestamp = timestamp
+    this.category = category
+    this.type = type
+    this.sdk = sdk
+
+    this.detail = detail
+    this.device = device
+    this.user = user
+    this.actions = actions
+    this.metaData = metaData ?? {}
+
+    this.__client = client
+  }
+
+  get __isOhbugEvent() {
+    return true
+  }
+
+  /**
+   * Add an action.
+   * Once the threshold is reached, the oldest breadcrumbs will be deleted.
+   * 新增一个动作。
+   * 一旦达到阈值，最老的 Action 将被删除。
+   *
+   * @param message
+   * @param data
+   * @param type
+   * @param timestamp
+   */
+  addAction(
+    message: string,
+    data: Record<string, any>,
+    type: string,
+    timestamp?: string,
+  ): void {
+    const actions = this.actions!
+
+    const targetMessage = isString(message) ? message : ''
+    const targetData = data || {}
+    const targetType = isString(type) ? type : ''
+
+    const action = new Action(targetMessage, targetData, targetType, timestamp)
+    if (actions.length >= (this.__client?.__config.maxActions ?? 30))
+      actions.shift()
+
+    actions.push(action)
+  }
+
+  /**
+   * Get current user information
+   * 获取当前的用户信息
+   */
+  getUser(): OhbugUser | undefined {
+    return this.user
+  }
+
+  /**
+   * Set current user information
+   * 设置当前的用户信息
+   */
+  setUser(user: OhbugUser): OhbugUser | undefined {
+    if (isObject(user) && Object.keys(user).length <= 6) {
+      this.user = { ...this.user, ...user }
+      return this.getUser()
+    }
+    this.__client?.__logger.error(getErrorMessage(
+      'setUser should be an object and have up to 6 attributes',
+      user,
+    ))
+    return undefined
+  }
+
+  /**
+   * Add metaData
+   * 新增 metaData
+   *
+   * @param section
+   * @param data
+   */
+  addMetaData(section: string, data: any) {
+    return addMetaData(this.metaData, section, data)
+  }
+
+  /**
+   * Get metaData
+   * 获取 metaData
+   *
+   * @param section
+   */
+  getMetaData(section: string) {
+    return getMetaData(this.metaData, section)
+  }
+
+  /**
+   * Delete metaData
+   * 删除 metaData
+   *
+   * @param section
+   */
+  deleteMetaData(section: string) {
+    return deleteMetaData(this.metaData, section)
+  }
+
+  toJSON() {
+    const {
+      apiKey,
+      appVersion,
+      appType,
+      timestamp,
+      category,
+      type,
+      sdk,
+      device,
+      detail,
+      user,
+      actions,
+      metaData,
+      releaseStage,
+    } = this
+    return {
+      apiKey,
+      appVersion,
+      appType,
+      timestamp,
+      category,
+      type,
+      sdk,
+      device,
+      detail,
+      user,
+      actions,
+      metaData,
+      releaseStage,
+    }
+  }
+}
+
+export function createEvent<D>(
+  values: OhbugCreateEvent<D>,
+  client: OhbugClient,
+): OhbugEventWithMethods<D> {
+  const { apiKey, appVersion, appType, releaseStage } = client.__config
+  const timestamp = new Date().toISOString()
+  const device = client.__device(client)
+  let category: OhbugCategory
+  let type: string
+  let detail: D
+  if (
+    isObject(values)
+    && Object.prototype.hasOwnProperty.call(values, 'type')
+    && Object.prototype.hasOwnProperty.call(values, 'detail')
+  ) {
+    category = values.category || 'error'
+    type = values.type
+    detail = values.detail
+  }
+  else {
+    category = 'error'
+    type = 'unknownError'
+    detail = values as unknown as D
+  }
+
+  return new Event(
+    {
+      apiKey,
+      appVersion,
+      appType,
+      timestamp,
+      category,
+      type,
+      sdk: client.__sdk,
+      device,
+      user: client.__user,
+      detail,
+      actions: client.__actions,
+      metaData: client.__metaData,
+      releaseStage,
+    },
+    client,
+  )
+}
+
+export function handleEventCreated<D = any>(
+  event: OhbugEventWithMethods<D>,
+  client: OhbugClient,
+): OhbugEventWithMethods<D> | null {
+  const funcs = [
+    client.__config.created,
+    ...client.__extensions.map(({ created }) => created),
+  ].filter(v => isFunction(v)) as ((
+    event: OhbugEventWithMethods<D>,
+    client: OhbugClient
+  ) => OhbugEventWithMethods<D> | null)[]
+  if (funcs.length === 0)
+    return event
+
+  return funcs.reduce<OhbugEventWithMethods<D> | null>((previous, current) => {
+    if (previous && isFunction(current))
+      return current(previous, client)
+
+    return null
+  }, event)
+}
+
+export function isEvent(eventLike: any): eventLike is OhbugEventWithMethods<any> {
+  return Boolean(eventLike?.__isOhbugEvent)
+}

package/src/extension.ts

@@ -0,0 +1,8 @@
+import type { OhbugExtension, OhbugExtensionUI } from '@ohbug/types'
+
+export function defineExtension(extension: OhbugExtension) {
+  return extension
+}
+export function createExtensionUI(extensionUI: OhbugExtensionUI) {
+  return extensionUI
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './client'
+export { isEvent } from './event'
+export * from './extension'
+export * from './types'
+export * as types from './types'

package/src/lib/getErrorMessage.ts

@@ -0,0 +1,17 @@
+import type { OhbugConfig } from '@ohbug/types'
+
+export function getConfigErrorMessage(
+  errors: Record<keyof OhbugConfig, string>,
+  config: OhbugConfig,
+) {
+  return new Error(`Invalid configuration\n${Object.keys(errors)
+    .map((key) => {
+      return `- ${key} ${errors[key as keyof OhbugConfig]}, got ${JSON.stringify(config[key as keyof OhbugConfig])}`
+    })
+    .join('\n')}
+      `)
+}
+
+export function getErrorMessage(message: string, data: any) {
+  return new Error(`Invalid data\n- ${message}, got ${JSON.stringify(data)}`)
+}

package/src/lib/metaData.ts

@@ -0,0 +1,21 @@
+import type { OhbugMetaData } from '@ohbug/types'
+
+export function addMetaData(map: OhbugMetaData, section: string, data: any) {
+  if (!section) return
+
+  map[section] = data
+}
+
+export function getMetaData(map: OhbugMetaData, section: string) {
+  if (map[section])
+    return map[section]
+
+  return undefined
+}
+
+export function deleteMetaData(map: OhbugMetaData, section: string) {
+  if (map[section])
+    return delete map[section]
+
+  return undefined
+}

package/src/lib/verifyConfig.ts

@@ -0,0 +1,37 @@
+import type { OhbugConfig, OhbugSchema } from '@ohbug/types'
+
+interface ConfigAndErrors {
+  config: Record<keyof OhbugConfig, any>
+  errors: Record<keyof OhbugConfig, string>
+}
+export function verifyConfig(config: OhbugConfig, schema: OhbugSchema) {
+  const keys = Object.keys(schema) as (keyof OhbugConfig)[]
+  return keys.reduce<ConfigAndErrors>(
+    (accumulator, key) => {
+      const configValue = config[key]
+      const { defaultValue, message, validate } = schema[key]
+
+      if (configValue !== undefined) {
+        const valid = validate(configValue)
+        if (valid) {
+          accumulator.config[key] = configValue
+        }
+        else {
+          accumulator.config[key] = defaultValue
+          accumulator.errors[key] = message
+        }
+      }
+      else {
+        // if there is no corresponding configuration, use the default value
+        // 如果没有传入相应配置 使用默认值
+        accumulator.config[key] = defaultValue
+      }
+
+      return accumulator
+    },
+    {
+      config: {} as ConfigAndErrors['config'],
+      errors: {} as ConfigAndErrors['errors'],
+    },
+  )
+}

package/src/notify.ts

@@ -0,0 +1,38 @@
+import type { OhbugClient, OhbugEventWithMethods } from '@ohbug/types'
+import { isFunction } from '@ohbug/utils'
+
+function handleNotified<D>(
+  event: OhbugEventWithMethods<D>,
+  client: OhbugClient,
+) {
+  const funcs = [
+    client.__config.notified,
+    ...client.__extensions
+      .filter(({ notified }) => isFunction(notified))
+      .map(({ notified }) => notified),
+  ]
+  funcs.forEach(func => func?.(event, client))
+}
+
+/**
+ * Used to control the timing of reporting events and the related life cycle.
+ *
+ * @param event
+ * @param client
+ */
+export async function notify<D>(
+  event: OhbugEventWithMethods<D> | null,
+  client: OhbugClient,
+): Promise<any> {
+  try {
+    let result = null
+    if (event) {
+      result = await client.__notifier(event)
+      handleNotified(event, client)
+    }
+    return result
+  }
+  catch (e) {
+    client.__logger.error(e)
+  }
+}