feat: reestrutura exemplos em pt/en e alinha contratos com a API

README.md

@@ -8,31 +8,27 @@
 
 Este é um repositório auxiliar contendo trechos de código e exemplos de uso.
 
-## Pré-requisitos para executar o projeto
+## Multilingual / Multilíngue
 
-- Node.js version manager, caso não tenha o nvm instale seguindo estes passos
-  - [nvm para windows](https://github.com/coreybutler/nvm-windows)
-  - [nvm pra mac/linux](https://github.com/nvm-sh/nvm#installing-and-updating)
+Os exemplos estão divididos em três versões, com comentários e textos no idioma correspondente. O código compartilhado (cliente HTTP e utilitários) fica na pasta `core` na raiz do repositório.
 
-- Clonar este repositório localmente `git clone https://github.com/LeoFalco/amonamarth-examples.git`
+The examples are split into three versions, with comments and text in the matching language. The shared code (HTTP client and utilities) lives in the `core` folder at the root of the repository.
 
-- Na pasta do projeto executar os seguintes comandos
+- 🇧🇷 **Português** — exemplos em `pt/exemplos/` · veja [pt/README.md](pt/README.md)
+- 🇺🇸 **English** — examples in `en/examples/` · see [en/README.md](en/README.md)
+- 🇪🇸 **Español** — ejemplos en `es/ejemplos/` · vea [es/README.md](es/README.md)
 
-  ```sh
-  nvm install # para instalar o nome
-  nvm use # troca para a versão do node.js instalada
-  npm install # instala as dependências do projeto
-  ```
+## Estrutura / Structure
 
-- O projeto usa autenticação por de API key você pode declarar a sua dentro de um arquivo chamado `.env`
-assim como na imagem:
-
-  ![image](https://user-images.githubusercontent.com/25820906/178081437-c5939851-116e-44e1-8527-91dc6a63900c.png)
-
-## Executando arquivos
+```text
+amonamarth-examples/
+├── core/   # código compartilhado / shared code (client.js, utils.js)
+├── data/   # arquivos de exemplo / example files
+├── pt/     # exemplos em português / Portuguese examples
+├── en/     # exemplos em inglês / English examples
+└── es/     # ejemplos em espanhol / Spanish examples
+```
 
-Os arquivos de exemplos estão na pasta `src/examples` é possível executa-los diretamente pelo node.js
+Consulte o README de cada idioma para os pré-requisitos e as instruções de execução.
 
-```sh
-  node src/examples/create-maintenance-with-attachment.js
-```
+See the README for each language for prerequisites and run instructions.

en/README.md

@@ -0,0 +1,40 @@
+# Amonamarth Examples (English)
+
+![Field Control ♥](https://img.shields.io/badge/Field%20Control-♥-blue.svg)
+[![GitHub Super-Linter](https://github.com/FieldControl/amonamarth-examples/workflows/Lint/badge.svg)](https://github.com/marketplace/actions/super-linter)
+
+
+:volcano: Amon Amarth, the public supplier management API, is a REST web service that exposes resources to make it easier for companies to integrate with their other systems.
+
+This is an auxiliary repository containing code snippets and usage examples. This is the **English** version of the examples. For the Portuguese version, see [pt/README.md](../pt/README.md). For the Spanish version, see [es/README.md](../es/README.md).
+
+## Prerequisites to run the project
+
+- Node.js version manager. If you do not have nvm, install it following these steps
+  - [nvm for windows](https://github.com/coreybutler/nvm-windows)
+  - [nvm for mac/linux](https://github.com/nvm-sh/nvm#installing-and-updating)
+
+- Clone this repository locally `git clone https://github.com/LeoFalco/amonamarth-examples.git`
+
+- In the project folder run the following commands
+
+  ```sh
+  nvm install # to install node
+  nvm use # switch to the installed Node.js version
+  npm install # install the project dependencies
+  ```
+
+- The project uses API key authentication. You can declare yours inside a file called `.env`
+as shown in the image:
+
+  ![image](https://user-images.githubusercontent.com/25820906/178081437-c5939851-116e-44e1-8527-91dc6a63900c.png)
+
+## Running files
+
+The English example files are in the `en/examples` folder. You can run them directly with Node.js
+
+```sh
+  node en/examples/maintenances/create-maintenance-with-attachment.js
+```
+
+> The shared code (HTTP client and utilities) lives in the `core` folder at the root of the repository.

en/examples/companies/get-companies.js

@@ -0,0 +1,78 @@
+// Example based on the documentation available at https://amonamarth.fieldcontrol.com.br/docs
+// The data provided are only test examples and do not represent the truth
+
+import { client } from '../../../core/client.js'
+import { getData } from '../../../core/utils.js'
+
+async function run () {
+  // Get companies with exact name equal to "Field Control"
+  // Only one item per page
+  // Page one or first page
+  await client.get('/companies', {
+    params: {
+      page: 1,
+      perPage: 1,
+      nameEq: 'Field Control'
+    }
+  }).then(getData)
+
+  // Get companies with exact name equal to "Field Control"
+  // Only two items per page
+  // Page one or first page
+  // From oldest to newest
+  await client.get('/companies', {
+    params: {
+      page: 1,
+      perPage: 2,
+      nameEq: 'Field Control',
+      orderBy: 'createdAt',
+      direction: 'asc'
+    }
+  }).then(getData)
+
+  // Get companies that have a name identical to "Resolv"
+  // Only one item per page
+  // Page one or first page
+  await client.get('/companies', {
+    params: {
+      page: 1,
+      perPage: 1,
+      nameEq: 'Resolv'
+    }
+  }).then(getData)
+
+  // Only two items per page
+  // Page one or first page
+  // With the name from Z to A
+  await client.get('/companies', {
+    params: {
+      page: 1,
+      perPage: 2,
+      orderBy: 'name',
+      direction: 'desc'
+    }
+  }).then(getData)
+
+  // Only two items per page
+  // Page one or first page
+  // Farthest to nearest
+  // The "distanceRelativeTo" field must be a string containing the latitude and longitude, respectively ("latitude,longitude")
+  // The "distanceRelativeTo" field can only be provided if the orderColumn field is equal to "distance"
+  // Companies without coordinates will be placed at the end of the list
+  await client.get('/companies', {
+    params: {
+      page: 1,
+      perPage: 2,
+      orderBy: 'distance',
+      direction: 'desc',
+      distanceRelativeTo: '37.7749,-122.4194'
+    }
+  }).then(getData)
+}
+
+run()
+  .catch(err => {
+    const error = err.isAxiosError ? err.toJSON() : err
+    console.log('error: ', error)
+    process.exit(1)
+  })

en/examples/companies/get-nearby-companies-usage.js

@@ -0,0 +1,29 @@
+// Example based on the documentation available at https://amonamarth.fieldcontrol.com.br/docs
+// The data provided are only test examples and do not represent the truth
+
+import { client } from '../../../core/client.js'
+import { getData } from '../../../core/utils.js'
+import assert from 'node:assert'
+
+async function run () {
+  // Get company geolocation usage history
+  const result = await client.get('/companies/actions/nearby/usage').then(getData)
+
+  assert.deepEqual(result, {
+    items: [
+      {
+        id: 'eyJwayI6IlVTQUdFIzEiLCJzayI6IjIwMjMtMDcifQ==',
+        month: '2023-07',
+        quota: 2000,
+        usedQuota: 10
+      }
+    ]
+  })
+}
+
+run()
+  .catch(err => {
+    const error = err.isAxiosError ? err.toJSON() : err
+    console.log('error: ', error)
+    process.exit(1)
+  })

en/examples/companies/nearby-companies-2.js

@@ -0,0 +1,28 @@
+// Example based on the documentation available at https://amonamarth.fieldcontrol.com.br/docs
+// The data provided are only test examples and do not represent the truth
+
+import { client } from '../../../core/client.js'
+
+async function run () {
+  // Get companies near "Avenida Abrão josé de lima 659"
+  const result = await client.post('/companies/actions/nearby', {
+    formattedAddress: 'Avenida Abrão josé de lima 659',
+    postalCode: '15110000', // optional
+    countryCode: null // optional
+  }, {
+    params: {
+      page: 1,
+      perPage: 2
+    }
+  })
+
+  console.log('headers: ', result.headers)
+  console.log('data: ', result.data)
+}
+
+run()
+  .catch(err => {
+    const error = err.isAxiosError ? err.toJSON() : err
+    console.log('error: ', error)
+    process.exit(1)
+  })

en/examples/companies/nearby-companies.js

@@ -0,0 +1,96 @@
+// Example based on the documentation available at https://amonamarth.fieldcontrol.com.br/docs
+// The data provided are only test examples and do not represent the truth
+
+import { client } from '../../../core/client.js'
+import { getData } from '../../../core/utils.js'
+import assert from 'node:assert'
+
+async function run () {
+  // Get companies near "Avenida Abrão josé de lima 659"
+  const result = await client.post('/companies/actions/nearby', {
+    formattedAddress: 'Avenida Abrão josé de lima 659',
+    postalCode: '15110000', // optional
+    countryCode: null // optional
+  }, {
+    params: {
+      page: 1,
+      perPage: 2
+    }
+  }).then(getData)
+
+  assert.deepEqual(result, {
+    items: [
+      {
+        id: '5a135059-a054-46d1-b431-fb0f1036ccd4',
+        name: 'Field Control - Fornecedor 8817',
+        relativeDistance: {
+          distanceInMeters: 1680, // nearest first
+          relativeTo: {
+            latitude: -20.7972941,
+            longitude: -49.221242
+          }
+        },
+        address: {
+          city: 'Guapiaçu',
+          complement: null,
+          coords: {
+            latitude: -20.807428,
+            longitude: -49.2332
+          },
+          countryCode: 'BRA',
+          neighborhood: 'Guapiaçu',
+          number: '686',
+          state: 'São Paulo',
+          street: 'abrao jose de lima',
+          zipCode: '15110000'
+        },
+        archived: false,
+        avatarUrl: 'https://s3.amazonaws.com/attachments.fieldcontrol.com.br/accounts/8817/company-logo.png',
+        createdAt: '2019-08-01T12:24:18Z'
+      },
+      {
+        id: 'e75d361b-ceee-4c83-9962-b5ecb4272224',
+        name: 'Designers',
+        relativeDistance: {
+          distanceInMeters: 16463,
+          relativeTo: {
+            latitude: -20.7972941,
+            longitude: -49.221242
+          }
+        },
+        address: {
+          city: 'São José do Rio Preto',
+          complement: null,
+          coords: {
+            latitude: -20.8072548,
+            longitude: -49.3790862
+          },
+          countryCode: 'AUS',
+          neighborhood: 'Centro',
+          number: '12',
+          state: 'SP',
+          street: 'Rua Coronel Spínola de Castro',
+          zipCode: '15015500'
+        },
+        archived: false,
+        avatarUrl: 'assets/images/avatars/avatar.jpg',
+        createdAt: '2020-08-04T19:26:48Z'
+      }
+    ],
+    pageInfo: {
+      hasNextPage: true,
+      hasPreviousPage: false,
+      page: 1,
+      pageCount: 4,
+      perPage: 2,
+      totalCount: 7
+    }
+  })
+}
+
+run()
+  .catch(err => {
+    const error = err.isAxiosError ? err.toJSON() : err
+    console.log('error: ', error)
+    process.exit(1)
+  })

en/examples/equipment-types/create-equipment-type.js

@@ -0,0 +1,55 @@
+// Example based on the documentation available at https://amonamarth.fieldcontrol.com.br/docs
+// The data provided are only test examples and do not represent the truth
+
+import { client } from '../../../core/client.js'
+import { getData, getFistItem } from '../../../core/utils.js'
+import assert from 'node:assert'
+
+async function run () {
+  const segment = await client.get('/segments', {
+    params: {
+      page: 1,
+      perPage: 10,
+      nameEq: '001 - Ar condicionado'
+    }
+  }).then(getFistItem)
+
+  const equipmentType = await client.post('/equipment-types', {
+    name: 'An equipment type',
+    archived: false,
+    segment: {
+      id: segment.id
+    },
+    customFields: [
+      {
+        name: 'Field 1',
+        type: 'QUESTION',
+        required: true
+      },
+      {
+        name: 'Field 2',
+        type: 'NUMBER',
+        required: false
+      },
+      {
+        name: 'Field 3',
+        type: 'DATE',
+        required: true
+      },
+      {
+        name: 'Field 4',
+        type: 'MULTIPLE_CHOICE',
+        required: false
+      }
+    ]
+  }).then(getData)
+
+  assert.equal(equipmentType.name, 'An equipment type')
+}
+
+run()
+  .catch(err => {
+    const error = err.isAxiosError ? err.toJSON() : err
+    console.log('error: ', error)
+    process.exit(1)
+  })