@tillhub/schemas 6.125.0 → 6.128.0

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+# [6.128.0](https://github.com/tillhub/schemas/compare/v6.127.0...v6.128.0) (2022-03-18)
+
+
+### Features
+
+* **branches:** add receipt_footer_image to branches model ([#682](https://github.com/tillhub/schemas/issues/682)) ([132523f](https://github.com/tillhub/schemas/commit/132523f))
+
+# [6.127.0](https://github.com/tillhub/schemas/compare/v6.126.0...v6.127.0) (2022-03-15)
+
+
+### Bug Fixes
+
+* **functions:** vouchers ([caa53d9](https://github.com/tillhub/schemas/commit/caa53d9))
+
+
+### Features
+
+* **functions:** discounted_voucher ([f8ed802](https://github.com/tillhub/schemas/commit/f8ed802))
+* **transactions:** references ([4a70818](https://github.com/tillhub/schemas/commit/4a70818))
+
+# [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/common/images.js

@@ -1,3 +1,5 @@
+const { anyOf } = require('../helpers/payload-or-null')
+
 const definedSizes = {
   '1x': {
     description: 'Image transformed to predefined small size',
@@ -31,7 +33,11 @@ const definedSizes = {
   }
 }
 
-function getImages (sizes = ['1x', '2x', '3x', 'avatar'], strict = false) {
+const getImages = ({
+  sizes = ['1x', '2x', '3x', 'avatar'],
+  strict = false,
+  description = 'Images object with URLs of various types of images'
+}) => {
   const sizesMap = sizes.reduce((memo, size) => {
     if (!definedSizes[size]) {
       throw new ReferenceError(`Size '${size}' is not defined`)
@@ -42,8 +48,8 @@ function getImages (sizes = ['1x', '2x', '3x', 'avatar'], strict = false) {
   }, {})
 
   return {
-    description: 'Images object with URLs of various types of images',
-    anyOf: [{
+    description,
+    ...anyOf({
       type: 'object',
       additionalProperties: !strict,
       properties: {
@@ -54,9 +60,8 @@ function getImages (sizes = ['1x', '2x', '3x', 'avatar'], strict = false) {
           type: 'string',
           format: 'uri'
         }
-      } }, {
-      type: 'null'
-    }]
+      }
+    })
   }
 }
 

package/lib/index.js

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

package/lib/v0/branches/base.js

@@ -124,7 +124,12 @@ module.exports = {
       }
     ]
   },
-  images: getImages(),
+  images: getImages({
+    description: 'A Tillhub image object with URLs to display images this for this branch.'
+  }),
+  receipt_footer_images: getImages({
+    description: 'A Tillhub image object with URLs to display receipt footer image this for this branch.'
+  }),
   image: {
     description: 'DEPRECATED. Omit or set null.',
     anyOf: [

package/lib/v0/customers/base.js

@@ -154,7 +154,7 @@ module.exports = {
       format: 'date-time'
     })
   },
-  images: getImages(['1x', '2x', '3x', 'avatar', 'gallery']),
+  images: getImages({ sizes: ['1x', '2x', '3x', 'avatar', 'gallery'] }),
   image: {
     description: 'DEPRECATED. Omit or set null.',
     ...anyOf({

package/lib/v0/functions/base.js

@@ -59,7 +59,7 @@ const linkedVoucherPayload = {
   additionalProperties: false,
   type: 'object',
   required: [
-    'products'
+    'linked_voucher'
   ],
   properties: {
     linked_voucher: {
@@ -120,6 +120,59 @@ const linkedVoucherPayload = {
   }
 }
 
+const discountedVoucherPayload = {
+  description: 'Specific description of the discounted voucher function (1 specific voucher added together with a negative amount product).',
+  additionalProperties: false,
+  type: 'object',
+  required: [
+    'discounted_voucher'
+  ],
+  properties: {
+    discounted_voucher: {
+      type: 'object',
+      description: 'Describes the necessary fields to sell voucher that is discounted by an additional product.',
+      additionalProperties: false,
+      properties: {
+        action: {
+          type: 'string',
+          format: 'uuid',
+          description: 'The primaray voucher action ressource ID.',
+          example: 'efe039d8-e38d-4333-86d8-48334da189a8'
+        },
+        amount: {
+          example: 50.0,
+          description: 'The primaray voucher amount (.2Decimal e.g. 50.00€).',
+          type: 'number',
+          minimum: 0,
+          maximum: 1000000,
+          multipleOf: 0.01
+        },
+        linked_product: {
+          type: 'string',
+          format: 'uuid',
+          description: 'The additional product ressource ID.',
+          example: 'fc7cc46a-ebe2-4b62-9b1b-0f849680b49'
+        },
+        linked_amount: {
+          example: 10.0,
+          description: 'The unit price of the linked product.',
+          type: 'number',
+          minimum: 0,
+          maximum: 1000000,
+          multipleOf: 0.01
+        },
+        linked_quantity: {
+          example: -1,
+          description: 'The quantity of the linked product (typically -1) to act as a discount.',
+          type: 'integer',
+          minimum: -16,
+          maximum: 0
+        }
+      }
+    }
+  }
+}
+
 const configurationProperties = {
   description: {
     oneOf: [
@@ -327,50 +380,74 @@ module.exports = {
         enum: [
           'instant_checkout',
           'add_to_cart',
-          'linked_voucher'
+          'linked_voucher',
+          'discounted_voucher'
         ]
       }
     },
-    if: {
-      properties: {
-        class: {
-          type: 'string',
-          enum: [
-            'instant_checkout',
-            'add_to_cart'
-          ]
-        }
-      }
-    },
-    then: {
-      properties: {
-        ...configurationProperties,
-        payload: {
-          ...oneOf(instantCheckoutPayload)
-        }
-      }
-    },
-    else: {
-      if: {
-        properties: {
-          class: {
-            type: 'string',
-            enum: [
-              'linked_voucher'
-            ]
+    allOf: [
+      {
+        if: {
+          properties: {
+            class: {
+              type: 'string',
+              enum: [
+                'instant_checkout',
+                'add_to_cart'
+              ]
+            }
+          }
+        },
+        then: {
+          properties: {
+            ...configurationProperties,
+            payload: {
+              ...oneOf(instantCheckoutPayload)
+            }
           }
         }
       },
-      then: {
-        properties: {
-          ...configurationProperties,
-          payload: {
-            ...oneOf(linkedVoucherPayload)
+      {
+        if: {
+          properties: {
+            class: {
+              type: 'string',
+              enum: [
+                'linked_voucher'
+              ]
+            }
+          }
+        },
+        then: {
+          properties: {
+            ...configurationProperties,
+            payload: {
+              ...oneOf(linkedVoucherPayload)
+            }
           }
         }
       },
-      else: false // further if-else statements add in here, as a nested prop
-    }
+      {
+        if: {
+          properties: {
+            class: {
+              type: 'string',
+              enum: [
+                'discounted_voucher'
+              ]
+            }
+          }
+        },
+        then: {
+          properties: {
+            ...configurationProperties,
+            payload: {
+              ...oneOf(discountedVoucherPayload)
+            }
+          }
+        }
+      }
+    ]
   },
   locations: {
     anyOf: [

package/lib/v1/transactions/components/embedded/reference/depends.js

@@ -19,7 +19,8 @@ module.exports = {
         'canceled_expense',
         'canceled_deposit',
         'canceled_bank_expense',
-        'canceled_bank_deposit'
+        'canceled_bank_deposit',
+        'linked_item'
       ]
     },
     id: {

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.128.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()
+})