npm package: @personio/scripts
Description: A set of node scripts to auto-generate files. Currently, the library includes two: **request** and **translations**. See more information bellow.
Latest version: 7.2.7

# @personio/scripts

A set of node scripts to auto-generate files. Currently, the library includes
two: **request** and **translations**. See more information bellow.

## Installation

Run

```bash
yarn add -D @personio/scripts
```

## CLI options

```
-s, --script <script>        // *Required. The script you want to run. Can be either translations or request.

-o, --outputDir <directory>  // *Only valid for the request script. The path of the directory you want to generate the request helper files.
                             //  The default is src/helpers/request,

-i, --inputFile <type>       // *Only valid for the request script. The path of your openapi.yaml file.
                             //  The default is openapi.yaml

-n, --requestName <name>     // *Only valid for the request script. Create the request helper naming based on this options.
                             //  It accepts three variants: operationId, summary or url, Default is operationId.

--noResponseMocks            // *Only valid for the request script.
                             //  Disable the creation of the response mocks.

--pact                       // Only valid for the request script.
                            // Use to generate pact file

--retrieveDataFromResponse   // Only valid for the request script.
                             // Use if your project is using the retrieveDataFromResponse parameter in the @personio/requests config

-d, --domain <domain>        // *Required. Only valid for the translations script.
                             //  Your teams domain, where we can find the translations.json file.

--fromLocalPhraseServer      // *Only valid for the translations script.
                             //  Retrieves the translations from http://localhost:9800 instead of production.
                             //  Don't forget to run the synchronisation pipeline before going to production!

--fromLocalTranslationsFile <filepath> // *Only valid for the translations script.
                                       //  [DANGEROUS] Retrieves the translations from a local JSON file (in i18next format) instead of production.
                                       //  The usage of the `--fromLocalTranslationsFile` is dangerous since PhraseApp might
                                       //  not contain the keys provided in the input file. It's supposed to be used only by the tooling
                                       //  that ensures that all keys are in place (e.g. VSCode Personio Extension).
```

## Description

As mentioned, we have two different scripts included in the library:

- translations
- request

### translations

This script generates four files:

- `__mocks__/translationsMock.ts` file including all the english translations to
  be injected into your test configuration.
- `config/translations.json` file including the english translations in JSON
  format. It can be served locally for your i18n configuration to speed up
  development.
- `translations.ts` file including the types from the translations of your
  team's domain.
- `react18next-resources.d.ts` file that declares your `react18next` resource
  types to enforce type safety on the translation key usage. **Note :** This
  will only works for `react-18next` version `11` and upwards.

#### Example

```bash
 personio-scripts -s translations -d recruiting
```

- After running the script, you can check the generated files in the path
  `src/translations.ts` and the `src/__mocks__/translationsMock.ts`

### request

This script generates three files, all based on the `openApi.yaml`.

- `types.ts` file, which includes:
  - query keys `enum` for using with `react-query`
  - the types from your request responses
- `requestHelper.ts` file with functions wrapped in the @personio/request
  library based on the APIs URL.
- `responseMocks.ts` file with all the response examples provided. **NOTE**:
  Double check the name of all your examples as it's required to have a valid
  javascript syntax otherwise the script will fail.

#### Example

```bash
 personio-scripts -s request -n summary
```

- After running the script and you haven't changed the output directory, you can
  check the generated files in the path `src/helper/request/requestHelper.ts`
  and the `src/helper/request/types.ts`.

  **Note:**

- The `-n, --requestName <name>` option accepts three variants: **operationId**,
  **summary** or **url**.
  - **operationId**: Takes this property as is. If you intend to use it, you
    should make sure this is a valid function name for javascript. For instance,
    the property is already in _camelCase_.
  - **summary**: Takes the summary property, remove the spacing and prepends the
    http method. Eg:
    - ```yaml
      get:
        summary: Preferences settings
      ```
    - the function will be called: `getPreferencesSettings`
  - **url**: Takes the url, split based on the `/` ,takes the last 3 names and
    prepends the http method. Eg:
    - ```yaml
      /api/v1/preferences:
        get: ...
      ```
    - the function will be called: `getApiV1Preferences`