@tillhub/schemas 6.125.0 → 6.126.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [6.126.0](https://github.com/tillhub/schemas/compare/v6.125.0...v6.126.0) (2022-03-15)
+
+
+### Features
+
+* **analytics:** transactons overview report v3 schema #API-1042 ([#680](https://github.com/tillhub/schemas/issues/680)) ([e5dc7ba](https://github.com/tillhub/schemas/commit/e5dc7ba)), closes [#API-1042](https://github.com/tillhub/schemas/issues/API-1042) [#API-1042](https://github.com/tillhub/schemas/issues/API-1042)
+
 # [6.125.0](https://github.com/tillhub/schemas/compare/v6.124.0...v6.125.0) (2022-03-10)
 
 

package/lib/common/analytics_response.js

@@ -0,0 +1,68 @@
+const dateObject = require('./date_object')
+const commonResponse = require('./response')
+
+/**
+ * Generate a common analytics response
+ * @param {Array<{job: Object, type: Object}>} metrics
+ * @param {Object[]} values
+ */
+function analyticsResponse (metrics, values) {
+  if (!Array.isArray(metrics)) {
+    throw new TypeError('Analytics response requires metrics to be set')
+  }
+  if (!Array.isArray(values)) {
+    throw new TypeError('Analytics response requires values to be set')
+  }
+  if (metrics.length !== values.length) {
+    throw new TypeError('Analytics response requires matrics and values to have the same length')
+  }
+
+  return {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    additionalProperties: false,
+    ...commonResponse({
+      resultItems: {
+        anyOf: metrics.map((metric, index) => ({
+          type: 'object',
+          additionalProperties: false,
+          properties: {
+            created_at: {
+              ...dateObject,
+              description: 'Job date'
+            },
+            metric: {
+              description: 'Metric description',
+              type: 'object',
+              additionalProperties: false,
+              properties: {
+                user: {
+                  description: 'Client ID',
+                  type: 'string',
+                  format: 'uuid',
+                  example: '936835f7-2d75-41d2-9001-38ed6e458328'
+                },
+                ...metric
+              }
+            },
+            count: {
+              description: 'Dataset entries count',
+              example: 67,
+              type: 'integer'
+            },
+            values: {
+              description: 'Dataset for this metric',
+              type: 'array',
+              items: {
+                type: 'object',
+                additionalProperties: false,
+                properties: values[index]
+              }
+            }
+          }
+        }))
+      }
+    })
+  }
+}
+
+module.exports = analyticsResponse

package/lib/index.js

@@ -1,5 +1,6 @@
 module.exports = {
   v0: require('./v0'),
   v1: require('./v1'),
+  v3: require('./v3'),
   common: require('./common')
 }

package/lib/v3/analytics/index.js

@@ -0,0 +1,3 @@
+module.exports = {
+  reports: require('./reports')
+}

package/lib/v3/analytics/reports/index.js

@@ -0,0 +1,3 @@
+module.exports = {
+  transactions: require('./transactions')
+}

package/lib/v3/analytics/reports/transactions/index.js

@@ -0,0 +1,3 @@
+module.exports = {
+  overview: require('./overview')
+}

package/lib/v3/analytics/reports/transactions/overview.js

@@ -0,0 +1,242 @@
+const analyticsResponse = require('../../../../common/analytics_response')
+
+const summary = {
+  absolute_average_transaction_cancellation_items_total: {
+    description: 'Absolute average total of transactions with type "sale_cancel"',
+    example: 2,
+    type: ['integer', 'null']
+  },
+  absolute_average_transaction_items_total: {
+    description: 'Absolute average of transactions total',
+    example: 2.01,
+    type: 'number',
+    multipleOf: 0.01
+  },
+  absolute_average_transaction_revenue_items_total: {
+    description: 'Absolute average total of transactions with types "sale" and "sale_cancel"',
+    example: 2.01,
+    type: 'number',
+    multipleOf: 0.01
+  },
+  absolute_average_transaction_sale_items_total: {
+    description: 'Absolute average total of transactions with type "sale" which never been cancelled',
+    example: 2.01,
+    type: 'number',
+    multipleOf: 0.01
+  },
+  average_transaction_total: {
+    description: 'Average transactions total',
+    example: 2.01,
+    type: 'number',
+    multipleOf: 0.01
+  },
+  change: {
+    description: 'Total change',
+    example: 2.01,
+    type: 'number',
+    multipleOf: 0.01
+  },
+  currency: {
+    description: 'Currency ISO code',
+    example: 'EUR',
+    type: 'string',
+    minLength: 3,
+    maxLength: 3
+  },
+  total: {
+    description: 'Total revenue',
+    example: 2.01,
+    type: 'number',
+    multipleOf: 0.01
+  },
+  total_cancellation_items_count: {
+    description: 'Total cancellations count',
+    example: 3,
+    type: 'integer'
+  },
+  total_count: {
+    description: 'Total transaction count',
+    example: 245,
+    type: 'integer'
+  },
+  total_revenue_items_count: {
+    description: 'Total revenues count',
+    example: 67,
+    type: 'integer'
+  },
+  total_sale_items_count: {
+    description: 'Total sales count',
+    example: 31,
+    type: 'integer'
+  }
+}
+
+const data = {
+  additional_type: {
+    description: 'Expense account type',
+    example: '',
+    type: ['string', 'null']
+  },
+  balance_custom_id: {
+    description: 'Balance custom id',
+    example: '2',
+    type: ['string', 'null']
+  },
+  branch: {
+    description: 'Branch UUID',
+    example: '936835f7-2d75-41d2-9001-38ed6e458328',
+    type: ['string', 'null'],
+    format: 'uuid'
+  },
+  branch_custom_id: {
+    description: 'Branch custom id',
+    example: '4',
+    type: ['string', 'null']
+  },
+  cashier_staff: {
+    description: 'Cashier UUID',
+    example: '936835f7-2d75-41d2-9001-38ed6e458328',
+    type: ['string', 'null'],
+    format: 'uuid'
+  },
+  cashier_staff_custom_id: {
+    description: 'Cashier custom id',
+    example: '234',
+    type: ['string', 'null']
+  },
+  change: {
+    description: 'The amount of change',
+    example: 3.34,
+    type: 'number',
+    multipleOf: 0.01
+  },
+  currency: {
+    description: 'Currency ISO code',
+    example: 'EUR',
+    type: 'string',
+    minLength: 3,
+    maxLength: 3
+  },
+  custom_id: {
+    description: 'Transaction custom id',
+    example: '17',
+    type: 'string'
+  },
+  customer: {
+    description: 'Customer UUID',
+    example: '936835f7-2d75-41d2-9001-38ed6e458328',
+    type: ['string', 'null'],
+    format: 'uuid'
+  },
+  customer_custom_id: {
+    description: 'Customer custom id',
+    example: '8328',
+    type: ['string', 'null']
+  },
+  customer_firstname: {
+    description: 'Customer first name',
+    example: 'Max',
+    type: ['string', 'null']
+  },
+  customer_lastname: {
+    description: 'Customer last name',
+    example: 'Zimmerman',
+    type: ['string', 'null']
+  },
+  customer_receipt: {
+    description: 'The customer receipt multiline text',
+    example: 'Bestellung: 17\n------------------------------------------\nWax in the City Berlin Charlottenburg',
+    type: 'string'
+  },
+  date: {
+    description: 'The transaction date and time in ISO 8601 format',
+    example: 2,
+    type: 'string',
+    format: 'date-time'
+  },
+  id: {
+    description: 'Transaction UUID',
+    example: '936835f7-2d75-41d2-9001-38ed6e458328',
+    type: 'string',
+    format: 'uuid'
+  },
+  merchant_receipt: {
+    description: 'The merchant receipt multiline text',
+    example: 'Zweitschrift,\nelektronisches Aufzeichnungssystem',
+    type: 'string'
+  },
+  register: {
+    description: 'Register UUID',
+    example: '936835f7-2d75-41d2-9001-38ed6e458328',
+    type: 'string',
+    format: 'uuid'
+  },
+  register_custom_id: {
+    description: 'Register custom id',
+    example: '979',
+    type: 'string'
+  },
+  timezone: {
+    description: 'Timezone code',
+    example: 'Europe/Berlin',
+    type: ['string', 'null']
+  },
+  total: {
+    description: 'Transaction total amount',
+    example: 2.01,
+    type: 'number',
+    multipleOf: 0.01
+  },
+  type: {
+    description: 'Transaction type',
+    example: 'sale',
+    type: 'string'
+  },
+  _external_reference_id: {
+    description: 'Transaction external id',
+    type: ['string', 'null']
+  },
+  _id: {
+    description: 'Transaction sequential id',
+    example: '64305',
+    type: ['string', 'null']
+  }
+}
+
+const meta = {
+  count: {
+    description: 'Total transactions count',
+    example: 315532,
+    type: 'integer'
+  }
+}
+
+const filteredMeta = {
+  count: {
+    description: 'Total transactions count under filters applied',
+    example: 7655,
+    type: 'integer'
+  }
+}
+
+module.exports.response = {
+  $id: 'https://schemas.tillhub.com/v3/analytics.reports.transactions.overview.response.schema.json',
+  ...analyticsResponse([{
+    job: { enum: ['reports_transactions_v2_overview_summary'] },
+    type: { enum: ['summary'] }
+  }, {
+    job: { enum: ['reports_transactions_v2_overview_data'] },
+    type: { enum: ['data_list'] }
+  }, {
+    job: { enum: ['reports_transactions_v2_overview_meta'] },
+    type: { enum: ['meta'] }
+  }, {
+    job: { enum: ['reports_transactions_v2_overview_filtered_meta'] },
+    type: { enum: ['filtered_meta'] }
+  }], [
+    summary,
+    data,
+    meta,
+    filteredMeta
+  ])
+}

package/lib/v3/index.js

@@ -0,0 +1,3 @@
+module.exports = {
+  analytics: require('./analytics')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tillhub/schemas",
-  "version": "6.125.0",
+  "version": "6.126.0",
   "private": false,
   "description": "All Tillhub API OpenAPI 3 compatible JSON Schemas.",
   "main": "./lib/index.js",

package/test/analytics/reports/transactions/overview.v3.spec.js

@@ -0,0 +1,11 @@
+const test = require('tape')
+const validate = require('../../../helpers/validate-schema')
+const overviewSchema = require('../../../../lib/v3/analytics/reports/transactions/overview')
+
+test('analytics:reports:transactions:overview:v3: response schema validation', function (t) {
+  const { valid, error } = validate(overviewSchema.response)
+  t.ok(valid, 'create response schema is valid')
+  t.error(error, 'should not get any error')
+
+  t.end()
+})