@tasenor/common-node 1.9.16

package/src/plugins/ReportPlugin.ts

@@ -0,0 +1,443 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import fs from 'fs'
+import { data2csv } from '..'
+import dayjs from 'dayjs'
+import quarterOfYear from 'dayjs/plugin/quarterOfYear'
+import { ReportOptions, ReportID, ReportFlagName, ReportItem, ReportQueryParams, ReportLine, AccountNumber, ReportColumnDefinition, PeriodModel, ReportFormat, Language } from '@dataplug/tasenor-common'
+import { BackendPlugin } from './BackendPlugin'
+
+dayjs.extend(quarterOfYear)
+
+/**
+ * A plugin providing one or more reports.
+ */
+export class ReportPlugin extends BackendPlugin {
+
+  private formats: ReportID[]
+  // Is set, allow this report only on DBs having those accounting schemes.
+  protected schemes: Set<string> | undefined
+
+  constructor(...formats: ReportID[]) {
+    super()
+    this.formats = formats
+    this.schemes = undefined
+  }
+
+  /**
+   * Read in report struture file.
+   */
+  getReportStructure(id: ReportID, lang: Language) : ReportFormat | undefined {
+    const path = this.filePath(`${id}-${lang}.tsv`)
+    if (fs.existsSync(path)) {
+      return fs.readFileSync(path).toString('utf-8') as ReportFormat
+    }
+  }
+
+  /**
+   * Get the list of supported languages.
+   */
+  getLanguages(): Language[] {
+    return []
+  }
+
+  /**
+   * Check if the given report is provided by this plugin.
+   * @param id
+   */
+  hasReport(id) {
+    return this.formats.includes(id)
+  }
+
+  /**
+   * Get the list of report IDs.
+   */
+  getFormats(scheme: string|undefined = undefined): ReportID[] {
+    if (this.schemes === undefined || scheme === undefined || this.schemes.has(scheme)) {
+      return this.formats
+    }
+    return []
+  }
+
+  /**
+   * Return UI option definitions for the given report.
+   * @param id
+   */
+  getReportOptions(id): ReportOptions {
+    return {}
+  }
+
+  /**
+   * Convert time stamp or Date to date string YYYY-MM-DD.
+   * @param {Number} timestamp
+   */
+  time2str(timestamp) {
+    if (timestamp === null) {
+      return null
+    }
+    if (timestamp instanceof Date) {
+      timestamp = timestamp.toISOString()
+    }
+    return timestamp.substr(0, 10)
+  }
+
+  /**
+   * Construct rendering information from report flags
+   * @param flags
+   * @returns
+   */
+  flags2item(flags: ReportFlagName[]) {
+    const item: ReportItem = {}
+    flags.forEach(flag => {
+      if (flag) {
+        switch (flag) {
+          case 'NEW_PAGE':
+            break
+          case 'BREAK':
+            item.break = true
+            break
+          case 'BOLD':
+            item.bold = true
+            break
+          case 'ITALIC':
+            item.italic = true
+            break
+          case 'DETAILS':
+            item.accountDetails = true
+            break
+          case 'HIDE_TOTAL':
+            item.hideTotal = true
+            break
+          case 'REQUIRED':
+            item.required = true
+            break
+          default:
+            throw new Error(`Cannot recognize report format flag '${flag}'.`)
+        }
+      }
+    })
+    return item
+  }
+
+  /**
+   * Construct column definitions for the report.
+   * @param id
+   * @param entries
+   * @param options
+   */
+  async getColumns(id, entries, options: ReportOptions, settings): Promise<ReportColumnDefinition[]> {
+    if (!options.periods) {
+      throw new Error(`Need periods to define columns ${JSON.stringify(options)}`)
+    }
+    const columns: ReportColumnDefinition[] = options.periods.map((period) => {
+      return {
+        type: 'numeric',
+        name: 'period' + period.id,
+        title: this.columnTitle(id, period, options)
+      }
+    })
+    columns.unshift({
+      name: 'title',
+      title: '',
+      type: 'name'
+    })
+    return columns
+  }
+
+  /**
+   * Construct a title for a column.
+   * @param id
+   * @param period
+   * @param options
+   */
+  columnTitle(id: ReportID, period: PeriodModel, options: ReportOptions): string {
+    throw new Error(`Report plugin ${this.constructor.name} does not implement columnTitle().`)
+  }
+
+  /**
+   * Force some options, if needed.
+   * @returns
+   */
+  forceOptions(options) {
+    return {
+      negateAssetAndProfit: false, // A flag to multiply by -1 entries from asset and profit types of accounts.
+      addPreviousPeriod: false // A flag to define if the previous period should be displayed for comparison.
+    }
+  }
+
+  /**
+   * Construct a SQL for the report query.
+   * @param db
+   * @param options
+   * @returns A knex query prepared.
+   */
+  async constructSqlQuery(db, options, settings) {
+    // Construct value negator.
+    let negateSql = '(CASE debit WHEN true THEN 1 ELSE -1 END)'
+    if (options.negateAssetAndProfit) {
+      negateSql += " * (CASE WHEN account.type IN ('ASSET', 'PROFIT') THEN 1 ELSE -1 END)"
+    }
+
+    // Find periods.
+    const periodIds = [options.periodId]
+    if (options.addPreviousPeriod) {
+      const recentPeriods = await db.select('*').from('period').where('id', '<=', options.periodId).orderBy('end_date', 'desc').limit(2)
+      if (recentPeriods.length > 1) {
+        periodIds.push(recentPeriods[1].id)
+      }
+      options.periods = recentPeriods // Save periods for further reference.
+    }
+
+    // Build a query basics.
+    let sqlQuery = db.select(
+      'document.period_id AS periodId',
+      'document.number AS documentId',
+      'document.date',
+      'account.name',
+      'account.type',
+      'account.number',
+      db.raw(`CAST(ROUND(${negateSql} * entry.amount * 100) AS BIGINT) AS amount`),
+      'entry.description'
+    )
+      .from('entry')
+      .leftJoin('account', 'account.id', 'entry.account_id')
+      .leftJoin('document', 'document.id', 'entry.document_id')
+      .whereIn('document.period_id', periodIds)
+
+    // Limit by account, if given.
+    if (options.accountId) {
+      sqlQuery = sqlQuery.andWhere('account.id', '=', options.accountId)
+    }
+
+    // Tune ordering.
+    sqlQuery = (sqlQuery
+      .orderBy('document.date')
+      .orderBy('document.number')
+      .orderBy('document.id')
+      .orderBy('entry.row_number'))
+
+    return sqlQuery
+  }
+
+  /**
+   * Construct a report data for the report.
+   * @param db
+   * @param id
+   * @param options
+   *
+   * Resulting entries on data is an array of objects containing:
+   * * `tab` Zero originating indentation number.
+   * * `error` If true, this row has an error.
+   * * `required` If true, this is always shown.
+   * * `hideTotal` if true, do not show total.
+   * * `bold` if true, show in bold.
+   * * `italic` if true, show in italic.
+   * * `bigger` if true, show in bigger font.
+   * * `fullWidth` if set, the content in column index defined here is expanded to cover all columns.
+   * * `useRemainingColumns` if set, extend this column index to use all the rest columns in the row.
+   * * `accountDetails` if true, after this are summarized accounts under this entry.
+   * * `isAccount` if true, this is an account entry.
+   * * `needLocalization` if set, value should be localized, i.e. translated via Localization component in ui.
+   * * `name` Title of the entry.
+   * * `number` Account number if the entry is an account.
+   * * `amounts` An object with entry for each column mapping name of the columnt to the value to display.
+   */
+  async renderReport(db, id, options: ReportQueryParams = {}) {
+
+    // Add report forced options.
+    Object.assign(options, this.forceOptions(options))
+
+    // Collect settings.
+    const settings = (await db('settings').where('name', 'like', `${this.code}.%`).orWhere({ name: 'companyName' }).orWhere({ name: 'companyCode' })).reduce((prev, cur) => ({ ...prev, [cur.name]: cur.value }), {})
+
+    // Find tags.
+    const settingName = `${this.code}.tagTypes`
+    if (options.byTags && settings[settingName]) {
+      const tags = await db('tags').select('id', 'tag', 'name', 'type', 'order').from('tags').whereIn('type', settings[settingName]).orderBy('order')
+      settings.tags = tags
+    } else {
+      settings.tags = []
+    }
+
+    // Find the formatting text description, if it exist.
+    options.format = this.getReportStructure(id, options.lang || 'en')
+
+    // Prepare query.
+    const q = await this.constructSqlQuery(db, options, settings)
+    let entries = await q
+
+    // Process big ints.
+    for (const entry of entries) {
+      entry.amount = parseInt(entry.amount)
+    }
+
+    // Apply query filtering.
+    entries = this.doFiltering(id, entries, options, settings)
+
+    // We have now relevant entries collected. Use plugin features next.
+    const columns: ReportColumnDefinition[] = await this.getColumns(id, entries, options as ReportOptions, settings)
+    let data = this.preProcess(id, entries, options, settings, columns)
+    data = this.postProcess(id, data, options, settings, columns)
+    const report = {
+      format: id,
+      columns,
+      meta: {
+        businessName: settings.companyName,
+        businessId: settings.companyCode
+      },
+      data
+    }
+
+    // Do the final conversion, if necessary.
+    if (options.csv) {
+      return data2csv(report, options)
+    }
+
+    return report
+  }
+
+  /**
+   * Filter out entries not matching to the report selected parameters.
+   * @param id
+   * @param entries
+   * @param options
+   * @param settings
+   */
+  doFiltering(id, entries, options, settings) {
+    let filter = (entry) => true
+
+    if (options.quarter1) {
+      filter = (entry) => dayjs(entry.date).quarter() <= 1
+    } if (options.quarter2) {
+      filter = (entry) => dayjs(entry.date).quarter() <= 2
+    } if (options.quarter3) {
+      filter = (entry) => dayjs(entry.date).quarter() <= 3
+    }
+
+    return entries.filter(filter)
+  }
+
+  /**
+   * This function converts the list of relevant entries to the column report data.
+   * @param id
+   * @param entries
+   * @param options
+   * @param columns
+   */
+  preProcess(id, entries, options, settings, columns) {
+    throw new Error(`Report plugin ${this.constructor.name} does not implement preProcess().`)
+  }
+
+  /**
+   * Do post processing for report data before sending it.
+   * @param id Report type.
+   * @param data Calculated report data
+   * @param options Report options.
+   * @param settings System settings.
+   * @param columns Column definitions.
+   * @returns
+   */
+  postProcess(id, data, options, settings, columns) {
+    return data
+  }
+
+  /**
+   * A helper to combine final report from pre-processed material for reports using text description.
+   * @param accountNumbers A set of all account numbers found.
+   * @param accountNames A mapping from account numbers to their names.
+   * @param columnNames A list of column names.
+   * @param format A text description of the report.
+   * @param totals A mapping from account numbers their total balance.
+   * @returns
+   */
+  parseAndCombineReport(accountNumbers: AccountNumber[], accountNames, columns, format, totals) {
+    const columnNames = columns.filter((col) => col.type === 'numeric').map((col) => col.name)
+
+    // Parse report and construct format.
+    const allAccounts: AccountNumber[] = Array.from(accountNumbers).sort()
+    const ret: ReportLine[] = []
+    format.split('\n').forEach((line) => {
+      if (/^#/.test(line)) {
+        return
+      }
+      let [numbers, text, flags] = line.split('\t')
+      numbers = numbers.split(' ')
+      flags = flags ? new Set(flags.trim().split(/\s+/)) : new Set()
+      const tab = text ? text.replace(/^(_*).*/, '$1').length : 0
+      text = text ? text.replace(/^_+/, '') : ''
+
+      if (flags.has('NEW_PAGE')) {
+        ret.push({ pageBreak: true })
+        return
+      }
+
+      if (flags.has('BREAK')) {
+        ret.push({ paragraphBreak: true })
+        return
+      }
+
+      // Split the line and reset variables.
+      const amounts: Record<string, number | null> = {}
+      columnNames.forEach((column) => (amounts[column] = null))
+      let unused = true
+      const item: ReportItem = { tab, ...this.flags2item(flags) }
+
+      // Collect all totals inside any of the account number ranges.
+      for (let i = 0; i < numbers.length; i++) {
+        const parts = numbers[i].split('-')
+        const from = parts[0]
+        const to = parts[1]
+        columnNames.forEach((column) => {
+          allAccounts.forEach((number) => {
+            if (number >= from && number < to) {
+              unused = false
+              if (totals[column][number] !== undefined) {
+                amounts[column] += totals[column][number]
+              }
+            }
+          })
+        })
+      }
+
+      // If we actually show details we can skip this entry and fill details below.
+      if (!item.accountDetails) {
+        if (item.required || !unused) {
+          item.name = text
+          item.amounts = amounts
+          ret.push(item)
+        }
+      }
+
+      // Fill in account details for the entries wanting it.
+      if (item.accountDetails) {
+        for (let i = 0; i < numbers.length; i++) {
+          const parts = numbers[i].split('-')
+          const from = parts[0]
+          const to = parts[1]
+          allAccounts.forEach((number) => {
+            if (number >= from && number < to) {
+              const item = { tab, ...this.flags2item(flags) }
+              item.isAccount = true
+              delete item.accountDetails
+              item.name = accountNames[number]
+              item.number = number
+              item.amounts = {}
+              columnNames.forEach((column) => {
+                if (!item.amounts) {
+                  item.amounts = {}
+                }
+                if (totals[column][number] === undefined) {
+                  item.amounts[column] = null
+                } else {
+                  item.amounts[column] = totals[column][number] + 0
+                }
+              })
+              ret.push(item)
+            }
+          })
+        }
+      }
+    })
+
+    return ret
+  }
+}

package/src/plugins/SchemePlugin.ts

@@ -0,0 +1,56 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import { Currency, Language, SchemeName, TsvFilePath } from '@dataplug/tasenor-common'
+import { BackendPlugin } from './BackendPlugin'
+
+/**
+ * A plugin providing one or more accounting schemes.
+ */
+export class SchemePlugin extends BackendPlugin {
+
+  private schemes: Set<SchemeName>
+
+  constructor(...schemes: SchemeName[]) {
+    super()
+    this.schemes = new Set(schemes)
+  }
+
+  /**
+   * Check if this plugin has the given scheme.
+   * @param code
+   * @returns
+   */
+  hasScheme(code): boolean {
+    return this.schemes.has(code)
+  }
+
+  /**
+   * Get the paths to the accounting scheme .tsv files by its code name.
+   * @param code
+   */
+  getSchemePaths(code, languae): TsvFilePath[] {
+    throw new Error(`A class ${this.constructor.name} does not implement getScheme().`)
+  }
+
+  /**
+   * Get the default settings for the new database.
+   * @param  code
+   * @returns
+   */
+  getSchemeDefaults(code): Record<string, unknown> {
+    return {}
+  }
+
+  /**
+   * Supported currencies.
+   */
+  supportedCurrencies(): Currency[] {
+    return []
+  }
+
+  /**
+   * Supported languages.
+   */
+  supportedLanguages(): Language[] {
+    return []
+  }
+}

package/src/plugins/ServicePlugin.ts

@@ -0,0 +1,188 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import axios from 'axios'
+import { log, note, error, PluginService, PluginServiceResponse, waitPromise } from '@dataplug/tasenor-common'
+import { BackendPlugin } from './BackendPlugin'
+import { KnexDatabase } from '..'
+
+export type ServicePluginRequestOptions = {
+  rateLimitDelay?: number
+}
+
+/**
+ * An API end point provider.
+ */
+export class ServicePlugin extends BackendPlugin {
+
+  private services: PluginService[]
+
+  constructor(...services) {
+    super()
+    this.services = services
+  }
+
+  getServices(): PluginService[] {
+    return this.services
+  }
+
+  /**
+   * A query executor called by the back end for API request.
+   * @param best The currently best solution found.
+   * @param db Knex database.
+   * @param service Name of the service to called.
+   * @param query Query parameters.
+   * This calls the actual query function, handles errors and finally modifies `best` if found a solution.
+   */
+  async executeQuery(best: unknown, db: KnexDatabase, service: PluginService, query: Record<string, unknown>) {
+    const settings: Record<string, unknown> = {}
+    for (const setting of await db('settings').select('*').where('name', 'like', `${this.code}.%`)) {
+      const [, name] = setting.name.split('.')
+      settings[name] = setting.value
+    }
+
+    // First check if the current answer is adequate.
+    if (this.isAdequate(best)) {
+      return
+    }
+    // Then run the query and catch errors.
+    let result
+    try {
+      result = await this.query(db, settings, service, query)
+    } catch (err) {
+      error(`Exception when handling service ${service} query ${JSON.stringify(query)}: ${err}`)
+      result = {
+        status: 500,
+        message: `Execution of service ${service} query failed on plugin ${this.constructor.name}.`
+      }
+    }
+    // Combine result.
+    this.addResult(best, result)
+  }
+
+  /**
+   * Perform the actual query.
+   *
+   * @param db Knex database.
+   * @param service Name of the service to called.
+   * @param query Query parameters.
+   */
+  async query(db: KnexDatabase, settings: Record<string, unknown>, service: PluginService, query: unknown) {
+    throw new Error(`A service plugin ${this.constructor.name} does not implement query().`)
+  }
+
+  /**
+   * Combine result of the service query.
+   *
+   * @param old Currently found solution.
+   * @param latest The solution given by this plugin.
+   *
+   * By default, any 2xx status result will override the current result.
+   * Any error result will override initial 404 result.
+   * Otherwise the latest is ignored.
+   */
+  addResult(old, latest) {
+    if ((latest.status >= 200 && latest.status < 300) ||
+      (old.status === 404 && old.message === 'No handlers found.')) {
+      delete old.message
+      Object.assign(old, latest)
+    }
+  }
+
+  /**
+   * Check if the current solution is sufficient.
+   * By default, any status 2xx is sufficient.
+   */
+  isAdequate(solution) {
+    return solution.status >= 200 && solution.status < 300
+  }
+
+  /**
+   * Execute query to the third party service,
+   * @param service
+   * @param method
+   * @param url
+   * @param params
+   * @returns Result body.
+   */
+  async request(service, method, url, params, headers = {}): Promise<PluginServiceResponse> {
+    if (method !== 'GET') {
+      throw new Error('Only GET method currently supported in plugin requests.')
+    }
+    note(`Service ${service} request ${method} ${url}`)
+    return new Promise((resolve, reject) => {
+      axios.request({ method, url, params, headers })
+        .then(response => {
+          log(`Request ${method} ${url}: HTTP ${response.status}`)
+          resolve({
+            status: response.status,
+            data: response.data
+          })
+        })
+        .catch(err => {
+          const status = err.response ? err.response.status : 500
+          const message = err.response && err.response.data && err.response.data.message ? err.response.data.message : `${err}`
+          error(`Request ${method} ${url} failed: HTTP ${status} ${message}`)
+          resolve({
+            status,
+            message
+          })
+        })
+    })
+  }
+
+  /**
+   * Pick meaningful keys unique from the headers for using as a key, whe storing result to teh cache.
+   * @param service
+   * @param header
+   * By default, no header is used as cache key.
+   */
+  cacheHeadersKey(service, header) {
+    return {}
+  }
+
+  /**
+   * Pick meaningful keys unique from the query parameters for using as a key, whe storing result to teh cache.
+   * @param service
+   * @param params
+   * By default, all parameters are used as cache key.
+   */
+  cacheParamsKey(service, params) {
+    return params
+  }
+
+  /**
+   * Execute query to the third party service,
+   * @param db
+   * @param service
+   * @param method
+   * @param url
+   * @param params
+   * @returns Result body.
+   */
+  async cachedRequest(db: KnexDatabase | null, service, method, url, params, headers = {}, options: ServicePluginRequestOptions = {}) {
+
+    // Get cache keys.
+    const keyParams = this.cacheParamsKey(service, params)
+    const keyHeaders = this.cacheHeadersKey(service, headers)
+
+    // Check if cached.
+    const cached = db ? await db('cached_requests').select('status', 'result').where({ method, url, query: keyParams, headers: keyHeaders }).first() : null
+    if (cached) {
+      if (cached.status >= 200 && cached.status < 300) {
+        log(`Using cached service ${service} result for ${method} ${url}`)
+        return cached.result
+      }
+    }
+
+    // Add delay if needed.
+    if (options.rateLimitDelay) {
+      await waitPromise(options.rateLimitDelay)
+    }
+
+    // Do the request and cache the result.
+    const result = await this.request(service, method, url, params, headers)
+    if (db) {
+      await db('cached_requests').insert({ method, url, query: keyParams, headers: keyHeaders, status: result.status || null, result })
+    }
+    return result
+  }
+}