Merge branch 'master' into restrictions-remove-ff

README.md

@@ -2,11 +2,11 @@
 
 Welcome to the __Mews Connector API__. This is a general-purpose API that enables partners of Mews to access data and services in __Mews Operations__.
 
-To make a quick start and get a feel for the API, see [Getting started](getting-started/README.md). For a full guide on how to connect, what authentication tokens you need, the meaning of error codes and much more, see our [Guidelines](guidelines/README.md).
+To make a quick start and get a feel for the API, see [Getting started](getting-started/README.md). For a full guide on how to connect, what authentication tokens you need, the meaning of error codes and much more, see our [Guidelines](guidelines/README.md). For a deeper understanding of **Mews** concepts, see [Concepts](concepts/README.md). 
 All of the API operations are detailed in [API Operations](operations/README.md). In addition, we support [Webhooks](webhooks/README.md) and [WebSockets](websockets/README.md).
 Not sure which to use? See [Ways to communicate](guidelines/communicate.md). For specific guidance on using the API for different scenarios, have a look at [Use cases](use-cases/README.md) which will help you through your implementation.
 
-If you encounter any issues using the API, or you have a question or special request, please get in touch via [partnersuccess@mews.com](mailto:partnersuccess@mews.com).
+If you encounter any issues using the API, or you have any questions, please get in touch via [partnersuccess@mews.com](mailto:partnersuccess@mews.com).
 
 > ### Changes to this API
 > * For the history of changes to the API, see the [Changelog](changelog/README.md)
@@ -15,4 +15,3 @@ If you encounter any issues using the API, or you have a question or special req
 
 > ### OpenAPI definition
 > We maintain an [OpenAPI definition](https://api.mews.com/Swagger/connector/swagger.yaml) (formerly Swagger) for the __Mews Connector API__. You can use this to build out client applications using third party tools.
-> At this stage we consider this a Beta test version, but please use it and get in touch to let us know how you get on.

SUMMARY.md

@@ -9,10 +9,12 @@
   * [Environments](guidelines/environments.md)
   * [Serialization](guidelines/serialization.md)
   * [Pagination](guidelines/pagination.md)
-  * [Taxation](guidelines/taxation.md)
   * [Multi-property](guidelines/multi-property.md)
   * [Best practices](guidelines/best-practices.md)
   * [Certification](guidelines/certification.md)
+* [Concepts](concepts/README.md)
+  * [Taxation](concepts/taxation.md)
+  * [Time units](concepts/time-units.md)
 * [Use cases](use-cases/README.md)
   * [Accounting](use-cases/accounting.md)
   * [Customer management](use-cases/customer-management.md)

_generator/.editorconfig

@@ -0,0 +1,13 @@
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+
+[*.{js,jsx,ts,tsx,mjs,yaml,yml}]
+indent_size = 2
+indent_style = space
+
+[*.edge]
+insert_final_newline = false

_generator/.gitignore

@@ -0,0 +1,141 @@
+output/
+
+### Node ###
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+lerna-debug.log*
+.pnpm-debug.log*
+
+# Diagnostic reports (https://nodejs.org/api/report.html)
+report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json
+
+# Runtime data
+pids
+*.pid
+*.seed
+*.pid.lock
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+*.lcov
+
+# nyc test coverage
+.nyc_output
+
+# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+
+# Bower dependency directory (https://bower.io/)
+bower_components
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (https://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directories
+node_modules/
+jspm_packages/
+
+# Snowpack dependency directory (https://snowpack.dev/)
+web_modules/
+
+# TypeScript cache
+*.tsbuildinfo
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Optional stylelint cache
+.stylelintcache
+
+# Microbundle cache
+.rpt2_cache/
+.rts2_cache_cjs/
+.rts2_cache_es/
+.rts2_cache_umd/
+
+# Optional REPL history
+.node_repl_history
+
+# Output of 'npm pack'
+*.tgz
+
+# Yarn Integrity file
+.yarn-integrity
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# parcel-bundler cache (https://parceljs.org/)
+.cache
+.parcel-cache
+
+# Next.js build output
+.next
+out
+
+# Nuxt.js build / generate output
+.nuxt
+dist
+
+# Gatsby files
+.cache/
+# Comment in the public line in if your project uses Gatsby and not Next.js
+# https://nextjs.org/blog/next-9-1#public-directory-support
+# public
+
+# vuepress build output
+.vuepress/dist
+
+# vuepress v2.x temp and cache directory
+.temp
+
+# Docusaurus cache and generated files
+.docusaurus
+
+# Serverless directories
+.serverless/
+
+# FuseBox cache
+.fusebox/
+
+# DynamoDB Local files
+.dynamodb/
+
+# TernJS port file
+.tern-port
+
+# Stores VSCode versions used for testing VSCode extensions
+.vscode-test
+
+# yarn v2
+.yarn/cache
+.yarn/unplugged
+.yarn/build-state.yml
+.yarn/install-state.gz
+.pnp.*
+
+### Node Patch ###
+# Serverless Webpack directories
+.webpack/
+
+# Optional stylelint cache
+
+# SvelteKit build / generate output
+.svelte-kit

_generator/.prettierrc

@@ -0,0 +1,6 @@
+{
+  "arrowParens": "always",
+  "semi": true,
+  "singleQuote": true,
+  "trailingComma": "es5"
+}

_generator/README.md

@@ -0,0 +1,23 @@
+# OpenAPI Spec to Markdown Generator
+
+This is a tool for generating Markdown documentation from an OpenAPI spec.
+
+## Setup
+
+1. Make sure you have [Node.js](https://nodejs.org/) v20 (or later) and `npm` installed
+2. In `_generator` run `npm install`
+
+## Usage
+
+Without providing any arguments, the generator will pick up the configuration from [config.yaml](config.yaml) file.
+
+```shell
+# cd _generator
+node index.js
+```
+
+Alternatively, you can override individual or all configuration arguments via CLI:
+
+```shell
+node index.js --source https://api.mews.com/swagger/connector/swagger.yaml --output some/alternative/output/path --tags bills --tags accounts
+```

_generator/collect-schemas.js

@@ -0,0 +1,46 @@
+import { getSchemaId } from './utils.js';
+
+/**
+ * @typedef { import('oas/operation').Operation } Operation
+ * @typedef { import('openapi-types').OpenAPIV3.SchemaObject } SchemaObject
+ * @typedef { import('openapi-types').OpenAPIV3.ResponseObject } ResponseObject
+ * @typedef { import('openapi-types').OpenAPIV3.Document } OASDocument
+ * @typedef { import('oas').default } Oas
+ * @typedef { import('./types.js').TemplateSchema } TemplateSchema
+ * @typedef { import('./types.js').TemplateProperty } TemplateProperty
+ * @typedef { import('./types.js').TemplateEnumEntry } TemplateEnumEntry
+ * @typedef { import('./types-resolver.js').SchemasAccumulator } SchemasAccumulator
+ */
+
+/**
+ * Traverse schema, collect all nested schemas
+ * @param {SchemaObject} schema
+ * @param {string[]} path
+ * @param {SchemasAccumulator} accumulator
+ * @returns {SchemasAccumulator}
+ */
+export function collectSchemas(schema, path, accumulator) {
+  const schemaId = getSchemaId(schema);
+  const nestedPath = [...path];
+  schema['x-schema-paths'] ??= [];
+  schema['x-schema-paths'].push(path);
+
+  if (schemaId) {
+    accumulator.add(schemaId, schema);
+    nestedPath.push(schemaId);
+  }
+
+  if (schema.type === 'object' || schema.properties?.discriminator) {
+    for (const key in schema.properties) {
+      collectSchemas(schema.properties[key], [...nestedPath, key], accumulator);
+    }
+  }
+  if (schema.type === 'array') {
+    collectSchemas(schema.items, nestedPath, accumulator);
+  }
+  const composedSchemas = schema.anyOf || schema.oneOf || schema.allOf || [];
+  for (const item of composedSchemas) {
+    collectSchemas(item, nestedPath, accumulator);
+  }
+  return accumulator;
+}

_generator/config.js

@@ -0,0 +1,53 @@
+import { parseArgs } from 'node:util';
+import { loadYaml } from './utils.js';
+
+const CONFIG_PATH = './config.yaml';
+
+function loadArgs() {
+  const parsedArgs = parseArgs({
+    options: {
+      tags: {
+        type: 'string',
+        alias: 't',
+        multiple: true,
+        default: [],
+      },
+      source: {
+        type: 'string',
+        alias: 's',
+      },
+      output: {
+        type: 'string',
+        alias: 'o',
+      },
+    },
+  });
+  const tags =
+    parsedArgs.values.tags.length > 0 ? parsedArgs.values.tags : undefined;
+  return {
+    source: parsedArgs.values.source || undefined,
+    output: parsedArgs.values.output || undefined,
+    tags,
+  };
+}
+
+export function loadConfig() {
+  const args = loadArgs();
+  const yamlConfig = loadYaml(CONFIG_PATH);
+  const config = {
+    oasPath: args.source || yamlConfig.source,
+    outputPath: args.output || yamlConfig.output,
+    tags: args.tags || yamlConfig.tags || [],
+  };
+  if (!config.oasPath && !config.outputPath) {
+    console.error(
+      'Usage: node index.js --source <url-or-path-to-openapi> --output <output-folder> [--tags tag1 [--tags "some tag2"]]'
+    );
+    throw new Error('Missing required arguments');
+  }
+  // TODO: This check can be removed after initial migration; if no tags are provided, generator will pick up all tags by default
+  if (config.tags.length === 0) {
+    throw new Error('No tags specified');
+  }
+  return config;
+}

_generator/config.yaml

@@ -0,0 +1,70 @@
+source: https://api.mews.com/swagger/connector/swagger.yaml
+output: ../operations
+tags:
+  # - accountingcategories
+  # - accountingitems
+  - accountnotes
+  # - accounts
+  # - addresses
+  # - agecategories
+  # - availabilityadjustments
+  # - availabilityblocks
+  # - bills
+  # - businesssegments
+  # - cancellationpolicies
+  # - cashiers
+  # - cashiertransactions
+  # - commands
+  # - companies
+  # - companionships
+  # - companycontracts
+  # - configuration
+  # - counters
+  - countries
+  # - creditcards
+  - currencies
+  # - customers
+  # - departments
+  - devices
+  # - enterprises
+  - exchangerates
+  # - exports
+  - images
+  # - languages
+  # - loyaltymemberships
+  # - loyaltyprograms
+  # - loyaltytiers
+  # - messages
+  # - messagethreads
+  - orderitems
+  # - orders
+  # - outletbills
+  # - outletitems
+  # - outlets
+  # - paymentrequests
+  # - payments
+  # - preauthorizations
+  # - productcategories
+  # - products
+  # - productserviceorders
+  # - rategroups
+  # - rates
+  # - reservationgroups
+  # - reservations
+  # - resourceaccesstokens
+  # - resourceblocks
+  # - resourcecategories
+  # - resourcefeatures
+  # - resources
+  # - restrictions
+  # - routingrules
+  # - rules
+  # - serviceordernotes
+  - services
+  # - sourceassignments
+  # - sources
+  # - tasks
+  # - taxations
+  # - taxenvironments
+  # - vouchercodes
+  # - vouchers