@whook/versions/README.md

A wrapper to provide versions check support to a Whook server

[//]: # ( )
[//]: # (This file is automatically generated by a `metapak`)
[//]: # (module. Do not change it  except between the)
[//]: # (`content:start/end` flags, your changes would)
[//]: # (be overridden.)
[//]: # ( )
# @whook/versions
> A wrapper to provide versions check support to a Whook server

[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/nfroidure/whook/blob/main/packages/whook-versions/LICENSE)


[//]: # (::contents:start)

This [Whook](https://github.com/nfroidure/whook)'s wrapper simply answer to any
HTTP call with a unsupported version header with a 418 HTTP error.

To use this plugin, simply install it:

```sh
npm i @whook/versions;
```

Declare it in the `src/index.ts` file of your project:

```diff

  // ...

  $.register(
    constant('ROUTES_WRAPPERS_NAMES', [
+      'wrapRouteHandlerWithVersionChecker',
      'wrapRouteHandlerWithAuthorization',
    ]),
  );

  // ...

  $.register(
    constant('WHOOK_PLUGINS', [
      '@whook/whook',
+      '@whook/versions',
      '@whook/authorization',
    ]),
  );

  // ...
```

Declare types in your `src/whook.d.ts` definition:

```diff
// ...
+ import { type WhookVersionsConfig } from '@whook/versions';

declare module 'application-services' {

  // ...

  export interface AppConfig
-    extends WhookBaseConfigs {}
+    extends WhookBaseConfigs, WhookVersionsConfig {}

  // ...

}

// ...
```

And add the errors descriptors or provide your own and configure the module
(usually in `src/config/common/config.js`):

```diff
// ...
import { DEFAULT_ERRORS_DESCRIPTORS } from '@whook/whook';
+ import { VERSIONS_ERRORS_DESCRIPTORS } from '@whook/versions';
import { type AppConfig } from 'application-services';

// ...

+ const VERSIONS = [
+   {
+     header: 'X-SDK-Version',
+     rule: '>=2.2.0',
+   },
+   {
+     header: 'X-APP-Version',
+     rule: '>=3.6.0',
+   },
+ ];

const CONFIG: AppConfig = {
  // ...
-   ERRORS_DESCRIPTORS: DEFAULT_ERRORS_DESCRIPTORS,
+   ERRORS_DESCRIPTORS: {
+     ...DEFAULT_ERRORS_DESCRIPTORS,
+     ...VERSIONS_ERRORS_DESCRIPTORS,
+   },
  // ...
+   VERSIONS,
};

export default CONFIG;
```

[//]: # (::contents:end)

# API
## Functions

<dl>
<dt><a href="#augmentAPIWithVersionsHeaders">augmentAPIWithVersionsHeaders(API, VERSIONS)</a> ⇒ <code>Promise.&lt;Object&gt;</code></dt>
<dd><p>Augment an OpenAPI with versions headers added.</p>
</dd>
<dt><a href="#initWrapRouteHandlerWithVersionChecker">initWrapRouteHandlerWithVersionChecker(services)</a> ⇒ <code>Promise.&lt;Object&gt;</code></dt>
<dd><p>Wrap a route handler to append CORS to response.</p>
</dd>
</dl>

<a name="augmentAPIWithVersionsHeaders"></a>

## augmentAPIWithVersionsHeaders(API, VERSIONS) ⇒ <code>Promise.&lt;Object&gt;</code>
Augment an OpenAPI with versions headers added.

**Kind**: global function  
**Returns**: <code>Promise.&lt;Object&gt;</code> - The augmented  OpenAPI object  

| Param | Type | Description |
| --- | --- | --- |
| API | <code>Object</code> | The OpenAPI object |
| VERSIONS | <code>Object</code> | The versions configurations |

<a name="initWrapRouteHandlerWithVersionChecker"></a>

## initWrapRouteHandlerWithVersionChecker(services) ⇒ <code>Promise.&lt;Object&gt;</code>
Wrap a route handler to append CORS to response.

**Kind**: global function  
**Returns**: <code>Promise.&lt;Object&gt;</code> - A promise of an object containing the reshaped env vars.  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| services | <code>Object</code> |  | The services ENV depends on |
| services.VERSIONS | <code>Object</code> |  | A VERSIONS object with the versions configuration |
| [services.log] | <code>Object</code> | <code>noop</code> | An optional logging service |


# Authors
- [Nicolas Froidure](http://insertafter.com/en/index.html)

# License
[MIT](https://github.com/nfroidure/whook/blob/main/packages/whook-versions/LICENSE)