@tillhub/schemas 6.119.0 → 6.122.0

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+# [6.122.0](https://github.com/tillhub/schemas/compare/v6.121.0...v6.122.0) (2022-02-22)
+
+
+### Features
+
+* **carts:** add detailed schema #API-1394 ([#673](https://github.com/tillhub/schemas/issues/673)) ([774c03b](https://github.com/tillhub/schemas/commit/774c03b)), closes [#API-1394](https://github.com/tillhub/schemas/issues/API-1394) [#API-1394](https://github.com/tillhub/schemas/issues/API-1394)
+
+# [6.121.0](https://github.com/tillhub/schemas/compare/v6.120.0...v6.121.0) (2022-02-21)
+
+
+### Bug Fixes
+
+* **tests:** remove require() errors ([f2b6a16](https://github.com/tillhub/schemas/commit/f2b6a16))
+
+
+### Features
+
+* **customers:** add rmissing schemas #API-1393 ([#672](https://github.com/tillhub/schemas/issues/672)) ([a4b8f30](https://github.com/tillhub/schemas/commit/a4b8f30)), closes [#API-1393](https://github.com/tillhub/schemas/issues/API-1393) [#API-1393](https://github.com/tillhub/schemas/issues/API-1393)
+
+# [6.120.0](https://github.com/tillhub/schemas/compare/v6.119.0...v6.120.0) (2022-02-17)
+
+
+### Features
+
+* **branches:** add detailed branches schema #API-1392 ([#671](https://github.com/tillhub/schemas/issues/671)) ([3232d2b](https://github.com/tillhub/schemas/commit/3232d2b)), closes [#API-1392](https://github.com/tillhub/schemas/issues/API-1392) [#API-1392](https://github.com/tillhub/schemas/issues/API-1392)
+
 # [6.119.0](https://github.com/tillhub/schemas/compare/v6.118.1...v6.119.0) (2022-02-15)
 
 

package/lib/common/address.js

@@ -1,7 +1,7 @@
-module.exports = {
-  type: 'object',
-  additionalProperties: false,
-  required: [
+const { oneOf } = require('../helpers/payload-or-null')
+
+function getAddress ({
+  required = [
     'lines',
     'street',
     'locality',
@@ -10,10 +10,21 @@ module.exports = {
     'country',
     'type'
   ],
-  properties: {
-    lines: {
-      oneOf: [
-        {
+  availableTypes = [
+    'local',
+    'delivery',
+    'billing'
+  ]
+} = {}) {
+  return {
+    type: 'object',
+    additionalProperties: false,
+    required,
+    properties: {
+      lines: {
+        description: 'Address details',
+        example: 'Penthouse',
+        ...oneOf({
           type: 'array',
           minItems: 1,
           maxItems: 4,
@@ -21,91 +32,65 @@ module.exports = {
             type: 'string',
             minLength: 1
           }
-        },
-        {
-          type: 'null'
-        }
-      ]
-    },
-    street: {
-      oneOf: [
-        {
+        })
+      },
+      street: {
+        description: 'Street name',
+        example: 'Genthiner Str.',
+        ...oneOf({
           type: 'string'
-        },
-        {
-          type: 'null'
-        }
-      ]
-    },
-    street_number: {
-      oneOf: [
-        {
+        })
+      },
+      street_number: {
+        description: 'Building number',
+        example: '34',
+        ...oneOf({
           type: 'string'
-        },
-        {
-          type: 'null'
-        }
-      ]
-    },
-    locality: {
-      oneOf: [
-        {
+        })
+      },
+      locality: {
+        description: 'Locality name (city, village, etc.)',
+        example: 'Berlin',
+        ...oneOf({
           type: 'string'
-        },
-        {
-          type: 'null'
-        }
-      ]
-    },
-    region: {
-      oneOf: [
-        {
+        })
+      },
+      region: {
+        description: 'Region name',
+        example: 'Branderburg',
+        ...oneOf({
           type: 'string'
-        },
-        {
-          type: 'null'
-        }
-      ]
-    },
-    postal_code: {
-      oneOf: [
-        {
+        })
+      },
+      postal_code: {
+        description: 'Postal code',
+        example: '10785',
+        ...oneOf({
           type: 'string',
           maxLength: 10
-        },
-        {
-          type: 'null'
-        }
-      ]
-    },
-    country: {
-      oneOf: [
-        {
+        })
+      },
+      country: {
+        description: 'Country',
+        example: 'Germany',
+        ...oneOf({
           type: 'string',
           minLength: 2,
           maxLength: 2,
           pattern: '^[A-Z]{2}$'
-        },
-        {
-          type: 'null'
-        }
-      ],
-      'default': null
-    },
-    type: {
-      oneOf: [
-        {
+        }),
+        'default': null
+      },
+      type: {
+        description: 'Address type',
+        example: 'delivery',
+        ...oneOf({
           type: 'string',
-          'enum': [
-            'local',
-            'delivery',
-            'billing'
-          ]
-        },
-        {
-          type: 'null'
-        }
-      ]
+          'enum': availableTypes
+        })
+      }
     }
   }
 }
+
+module.exports = { getAddress }

package/lib/common/base.js

@@ -5,16 +5,19 @@
 function baseObject (options = {}) {
   return {
     id: {
+      description: 'Unique entity ID',
       type: 'string',
       format: 'uuid',
       example: '936835f7-2d75-41d2-9001-38ed6e458328'
     },
     created_at: {
+      description: 'The date and time entity was created',
       type: 'string',
       format: 'date-time',
       example: '2019-03-17T21:12:04.849Z'
     },
     updated_at: {
+      description: 'The date and time entity was updated',
       type: 'string',
       format: 'date-time',
       example: '2019-03-17T21:12:04.849Z'

package/lib/common/images.js

@@ -0,0 +1,63 @@
+const definedSizes = {
+  '1x': {
+    description: 'Image transformed to predefined small size',
+    example: 'https://my-storage.io/images/f5a3cc72-7fb5-4d2c-bda5-9b2983c7e879_1x.png',
+    type: 'string',
+    format: 'uri'
+  },
+  '2x': {
+    description: 'Image transformed to predefined medium size',
+    example: 'https://my-storage.io/images/f5a3cc72-7fb5-4d2c-bda5-9b2983c7e879_2x.png',
+    type: 'string',
+    format: 'uri'
+  },
+  '3x': {
+    description: 'Image transformed to predefined big size',
+    example: 'https://my-storage.io/images/f5a3cc72-7fb5-4d2c-bda5-9b2983c7e879_1x.png',
+    type: 'string',
+    format: 'uri'
+  },
+  gallery: {
+    description: 'Image transformed to predefined size to use in gallery',
+    example: 'https://my-storage.io/images/f5a3cc72-7fb5-4d2c-bda5-9b2983c7e879_gallery.png',
+    type: 'string',
+    format: 'uri'
+  },
+  avatar: {
+    description: 'Image transformed to predefined size to use as "avatar"',
+    example: 'https://my-storage.io/images/f5a3cc72-7fb5-4d2c-bda5-9b2983c7e879_avatar.png',
+    type: 'string',
+    format: 'uri'
+  }
+}
+
+function getImages (sizes = ['1x', '2x', '3x', 'avatar'], strict = false) {
+  const sizesMap = sizes.reduce((memo, size) => {
+    if (!definedSizes[size]) {
+      throw new ReferenceError(`Size '${size}' is not defined`)
+    }
+
+    memo[size] = { ...definedSizes[size] }
+    return memo
+  }, {})
+
+  return {
+    description: 'Images object with URLs of various types of images',
+    anyOf: [{
+      type: 'object',
+      additionalProperties: !strict,
+      properties: {
+        ...sizesMap,
+        original: {
+          description: 'Original image',
+          example: 'https://my-storage.io/images/f5a3cc72-7fb5-4d2c-bda5-9b2983c7e879.png',
+          type: 'string',
+          format: 'uri'
+        }
+      } }, {
+      type: 'null'
+    }]
+  }
+}
+
+module.exports = { getImages }

package/lib/common/query.js

@@ -0,0 +1,64 @@
+const standardParams = {
+  start: {
+    description: 'The start date to filter entities by "updated_at" field value',
+    example: '2022-02-01T00:00:00.000Z',
+    type: 'string',
+    format: 'date-time'
+  },
+  end: {
+    description: 'The end date to filter entities by "updated_at" field value',
+    example: '2022-02-28T23:59:59.999Z',
+    type: 'string',
+    format: 'date-time'
+  },
+  limit: {
+    description: 'The maximum amount of entries on page (for paginated output)',
+    example: 50,
+    type: 'integer',
+    minimum: 1
+  },
+  active: {
+    description: 'Filter entities by "active" field value',
+    example: 'true',
+    type: 'string',
+    enum: ['true', 'false']
+  },
+  deleted: {
+    description: 'Filter entities which are deleted or not',
+    example: 'true',
+    type: 'string',
+    enum: ['true', 'false']
+  }
+}
+
+/**
+ * Generate a common query for entities set
+ * @param {Object} required Required fields to restrict the amount of entries
+ */
+function getQuery ({
+  standard = ['start', 'end'],
+  required = ['start', 'end'],
+  additional = {}
+} = {}) {
+  const properties = standard.reduce((memo, paramName) => {
+    if (!standardParams[paramName]) {
+      throw new ReferenceError(`Parameter '${paramName}' is not standard`)
+    }
+
+    memo[paramName] = { ...standardParams[paramName] }
+
+    return memo
+  }, {})
+
+  Object.assign(properties, additional)
+
+  return {
+    $schema: 'http://json-schema.org/draft-07/schema#',
+    additionalProperties: false,
+    type: 'object',
+    required,
+    properties
+  }
+}
+
+module.exports = getQuery

package/lib/common/response.js

@@ -1,25 +1,26 @@
 const cursor = {
   type: 'object',
+  description: 'Optional cursor in paginated API calls. The cursor next field must be called as fully quantifiable URI in order to hit the next if available.',
   additionalProperties: false,
-  description: 'Optional cursor in pagable API calls. The cursor next field must be called as fully qualifyable URI in order to hit the next page',
+  required: ['self'],
   properties: {
     next: {
       type: 'string',
       format: 'uri',
       description: 'The URI pointing to the next page.',
-      example: 'https://api.tillhub.com/api/v1/products/061f91a3-eba2-40b8-9a76-115189d6741e?first=2018-07-02T21%3A47%3A44.382Z&page=0&size=10&cursor_field=updated_at'
+      example: 'https://api.tillhub.com/api/v1/products/061f91a3-eba2-40b8-9a76-115189d6741e?cursor=2018-07-02T21%3A47%3A44.382Z&size=10&cursor_field=updated_at'
     },
     first: {
       type: 'string',
       format: 'uri',
       description: 'The URI pointing to the the first page.',
-      example: 'https://api.tillhub.com/api/v1/products/061f91a3-eba2-40b8-9a76-115189d6741e?first=2018-07-02T21%3A47%3A44.382Z&page=1&size=10&cursor_field=updated_at'
+      example: 'https://api.tillhub.com/api/v1/products/061f91a3-eba2-40b8-9a76-115189d6741e?cursor=2018-07-02T21%3A47%3A44.382Z&size=10&cursor_field=updated_at'
     },
     self: {
       type: 'string',
       format: 'uri',
       description: 'The URI pointing to this page.',
-      example: 'https://api.tillhub.com/api/v1/products/061f91a3-eba2-40b8-9a76-115189d6741e?first=2018-07-02T21%3A47%3A44.382Z&page=0&size=10&cursor_field=updated_at'
+      example: 'https://api.tillhub.com/api/v1/products/061f91a3-eba2-40b8-9a76-115189d6741e?cursor=2018-07-02T21%3A47%3A44.382Z&size=10&cursor_field=updated_at'
     }
   }
 }
@@ -47,14 +48,14 @@ function commonResponse ({ resultItems, results, additionals } = {}, { hasCursor
       msg: {
         type: 'string',
         minLength: 1,
-        example: 'Queried transactions sucessefully.',
-        description: 'Any English sentence, meant as information for developers and implementers. Avoid displaying this to the users and especially do not expect thos messages to stay stable.'
+        example: 'Queried transactions successfully.',
+        description: 'Any English sentence, meant as information for developers and implementers. Avoid displaying this to the users and especially do not expect those messages to stay stable.'
       },
       msg_localised: {
+        description: 'Optional localized message that can be displayed to the user if existing. The language can be set by in the request or will fallback to English.',
+        example: 'Abgefragte Transaktionen erfolgreich.',
         type: 'string',
-        minLength: 1,
-        example: 'Queried transactions sucessefully.',
-        description: 'Optional localised message that can be displayed to the user if existing. The language can be set by in the request or will fallback to English.'
+        minLength: 1
       },
       request: {
         type: 'object',

package/lib/v0/branches/base.js

@@ -1,9 +1,11 @@
-const customProperties = require('../../common/custom_properties')
 const { stripIndents } = require('common-tags')
+const customProperties = require('../../common/custom_properties')
+const { getImages } = require('../../common/images')
 
 module.exports = {
   name: {
-    description: 'any arbitrary name for a branch that can be displayed in applications.',
+    description: 'Any arbitrary name for a branch that can be displayed in applications.',
+    example: 'Head office',
     anyOf: [
       {
         type: 'string',
@@ -16,17 +18,19 @@ module.exports = {
     ]
   },
   phonenumbers: {
-    description: 'A number of valid types of phonenumbers for a branch.',
+    description: 'A number of valid types of phone numbers for a branch.',
     anyOf: [
       {
         type: 'object',
         additionalProperties: false,
         properties: {
           line_main: {
-            type: 'string'
+            type: 'string',
+            example: '+49-555-1976'
           },
           line_1: {
-            type: 'string'
+            type: 'string',
+            example: '+49-555-1977'
           },
           line_2: {
             type: 'string'
@@ -57,6 +61,7 @@ module.exports = {
   },
   email: {
     description: 'The main contact email for a branch.',
+    example: 'office@my-incredible-company.to',
     anyOf: [
       {
         type: 'string',
@@ -70,6 +75,7 @@ module.exports = {
   },
   receipt_header: {
     description: 'An arbitrary string that will be printed on every receipt as the header.',
+    example: 'Perfect socks LTD',
     anyOf: [
       {
         type: 'string',
@@ -82,6 +88,7 @@ module.exports = {
   },
   receipt_footer: {
     description: 'An arbitrary string that will be printed on every receipt as the footer',
+    example: 'Thank you!',
     anyOf: [
       {
         type: 'string',
@@ -117,40 +124,7 @@ module.exports = {
       }
     ]
   },
-  images: {
-    description: 'A Tillhub image object with URLs to display images this for this branch.',
-    anyOf: [
-      {
-        type: 'object',
-        additionalProperties: true,
-        properties: {
-          '1x': {
-            type: 'string',
-            format: 'uri'
-          },
-          '2x': {
-            type: 'string',
-            format: 'uri'
-          },
-          '3x': {
-            type: 'string',
-            format: 'uri'
-          },
-          avatar: {
-            type: 'string',
-            format: 'uri'
-          },
-          original: {
-            type: 'string',
-            format: 'uri'
-          }
-        }
-      },
-      {
-        type: 'null'
-      }
-    ]
-  },
+  images: getImages(),
   image: {
     description: 'DEPRECATED. Omit or set null.',
     anyOf: [
@@ -170,11 +144,13 @@ module.exports = {
   },
   active: {
     description: 'Soft disable or enabled this branch.',
+    example: 'true',
     type: 'boolean',
     default: true
   },
   deleted: {
     description: 'Soft delete this branch.',
+    example: 'false',
     type: 'boolean',
     default: false
   },
@@ -186,10 +162,22 @@ module.exports = {
   branch_number: {
     type: 'number',
     description: 'The maximum stems from the fact that is it stored as an postgres int4 type, with 4 bytes of space',
+    example: 107,
     minimum: 0,
     maximum: 2147483647
   },
+  custom_id: {
+    description: 'Branch custom unique ID.',
+    example: 'dd3234of',
+    anyOf: [{
+      type: 'string'
+    }, {
+      type: 'null'
+    }]
+  },
   external_custom_id: {
+    description: 'Unique ID of this branch in external system. Uses for synchronization.',
+    example: '7882448928329',
     anyOf: [
       {
         type: 'string',
@@ -202,6 +190,8 @@ module.exports = {
     ]
   },
   cost_center: {
+    description: 'Cost center unique ID',
+    example: '7882448928329',
     anyOf: [
       {
         type: 'string',
@@ -242,6 +232,7 @@ module.exports = {
             },
             street: {
               description: 'A street name',
+              example: 'Downing Street',
               oneOf: [
                 {
                   type: 'string',
@@ -254,6 +245,7 @@ module.exports = {
             },
             street_number: {
               description: 'A street number',
+              example: '10',
               oneOf: [
                 {
                   type: 'string',
@@ -266,6 +258,7 @@ module.exports = {
             },
             locality: {
               description: 'The international format for a city, village and any other localizable city like place.',
+              example: 'London',
               oneOf: [
                 {
                   type: 'string'
@@ -277,6 +270,7 @@ module.exports = {
             },
             region: {
               description: 'The international format for regional sub category of a country e.g. a state or province.',
+              example: 'Greater London',
               oneOf: [
                 {
                   type: 'string'
@@ -288,6 +282,7 @@ module.exports = {
             },
             postal_code: {
               description: 'A non-validated postal code.',
+              example: 'SW1A',
               oneOf: [
                 {
                   type: 'string',
@@ -300,6 +295,7 @@ module.exports = {
             },
             country: {
               description: 'A country as ISO Alpha-2 code.',
+              example: 'UK',
               oneOf: [
                 {
                   type: 'string',
@@ -366,42 +362,37 @@ module.exports = {
   },
   configuration: {
     description: 'Deprecated: Overwriting a fa_account_number on cash payments for DATEV export.',
-    anyOf: [
-      {
-        type: 'string'
-      },
-      {
-        type: 'null'
-      }
-    ]
+    anyOf: [{
+      type: 'string'
+    }, {
+      type: 'null'
+    }]
   },
   timezone_default: {
     description: 'An IANA timezone that will be used to display local timezones in documents and UI. Validation for the timezone will happen in memory of the server, but not on that schema.',
-    anyOf: [
-      {
-        type: 'string'
-      },
-      {
-        type: 'null'
-      }
-    ]
+    example: 'Europe/London',
+    anyOf: [{
+      type: 'string'
+    }, {
+      type: 'null'
+    }]
   },
   currency_default: {
     description: 'The three letter [ISO currency](https://en.wikipedia.org/wiki/ISO_4217) of this branch.',
-    anyOf: [
-      {
-        type: 'string'
-      },
-      {
-        type: 'null'
-      }
-    ]
+    example: 'GBP',
+    anyOf: [{
+      type: 'string'
+    }, {
+      type: 'null'
+    }]
   },
   custom_properties: {
+    description: 'User-defined branch properties',
     ...customProperties.implementation
   },
   default_favourite: {
     description: 'Define which favourite set to show as default in the POS if none is defined on the register.',
+    example: '20e89159-28d9-46f2-bda3-d74bb70834e7',
     anyOf: [
       {
         type: 'string',
@@ -414,6 +405,7 @@ module.exports = {
   },
   default_category_tree: {
     description: 'Define which category tree to use as default in the POS if none is defined on the register.',
+    example: 'c45764ed-fc6d-4b32-b406-59a5e84d2999',
     anyOf: [
       {
         type: 'string',