# read-update-xlsx

Script TypeScript que consulta erros de regra de negócio (`BusinessRuleError`) na API do Planview Adaptive Work (Clarizen) e imprime o resultado no terminal.

A comunicação com a API usa a biblioteca [@arco/clarizen-lib](https://gitea.rivuslab.com/leonardotoniolo/clarizen-lib), instalada automaticamente via Git ao rodar `npm install`.

## Pré-requisitos

- [Node.js](https://nodejs.org/) 18 ou superior
- Acesso ao Gitea da Rivus Lab (para baixar `clarizen-lib` na instalação)
- Chave de API do Adaptive Work (ou credenciais equivalentes já usadas no time)

## Clonar e instalar

```bash
git clone https://gitea.rivuslab.com/leonardotoniolo/read-update-xlsx.git
cd read-update-xlsx
npm install
```

Se o repositório `clarizen-lib` for privado, configure autenticação no Git antes do `npm install`:

- **SSH:** chave cadastrada no Gitea e dependência no formato  
  `git+ssh://git@gitea.rivuslab.com/leonardotoniolo/clarizen-lib.git#main` (se necessário, ajuste no `package.json`)
- **HTTPS:** token de acesso no Gitea (Personal Access Token) configurado no Git ou no `.npmrc`

Na primeira instalação, o npm clona `clarizen-lib` e executa o build (`prepare` → `tsc`), gerando a pasta `dist/` dentro de `node_modules/@arco/clarizen-lib`.

## Configurar variáveis de ambiente

Copie o exemplo e preencha a API key:

```bash
cp .env.example .env
```

Edite `.env` na **raiz do projeto** (não dentro de `src/`):

```env
CLARIZEN_BASE_URL=https://api.clarizen.com
CLARIZEN_API_KEY=sua_chave_aqui
```

Alternativa aceita pelo código: `API_KEY_AW` em vez de `CLARIZEN_API_KEY`.

O carregador de ambiente também tenta usar `../clarizen-lib/.env` se existir (útil em desenvolvimento local com monorepo).

## Rodar o projeto

```bash
npm start
```

Isso executa `tsx src/index.ts`, que:

1. Valida se há API key configurada
2. Consulta até 5000 registros de `BusinessRuleError` com os campos definidos em `src/index.ts`
3. Exibe a quantidade e cada entidade no console

## Outros comandos

| Comando | Descrição |
| -------- | --------- |
| `npm start` | Executa a consulta ao Clarizen |
| `npm run check:clarizen` | Testa se `@arco/clarizen-lib` foi instalada e compilada corretamente (deve imprimir `OK Clarizen`) |

## Estrutura relevante

```text
read_update_xlsx/
├── .env.example      # modelo de variáveis
├── .env              # suas credenciais (não commitar)
├── package.json      # dependência clarizen-lib via Git
├── src/
│   ├── index.ts      # consulta BusinessRuleError
│   └── load-env.ts   # carrega .env da raiz do projeto
└── README.md
```

## Dependência clarizen-lib

No `package.json` a lib está referenciada assim:

```json
"@arco/clarizen-lib": "git+https://gitea.rivuslab.com/leonardotoniolo/clarizen-lib.git#main"
```

O `package-lock.json` fixa o commit exato usado na instalação. Documentação completa da biblioteca: [clarizen-lib](https://gitea.rivuslab.com/leonardotoniolo/clarizen-lib).

### Desenvolvimento local com a lib ao lado

Se você tiver `clarizen-lib` clonada na pasta irmã (`../clarizen-lib`), pode trocar temporariamente no `package.json`:

```json
"@arco/clarizen-lib": "file:../clarizen-lib"
```

Rode `npm install` e `npm run build` dentro de `clarizen-lib`. Não commite essa alteração se o repositório for usado só via Git.

## Problemas comuns

| Sintoma | O que fazer |
| -------- | ------------ |
| Erro ao clonar `clarizen-lib` no `npm install` | Verificar login SSH/HTTPS no Gitea |
| `Cannot find module .../dist/index.js` | Rodar de novo `npm install` (o `prepare` da lib deve compilar o `dist`) ou `npm run check:clarizen` |
| `Defina CLARIZEN_API_KEY...` | Criar `.env` na raiz com `CLARIZEN_API_KEY` ou `API_KEY_AW` |
| Instalação dentro de monorepo npm | Usar `npm install --workspaces=false` nesta pasta para não sobrescrever o lock com `file:../clarizen-lib` |