@odg/chemical-x 2.1.3 → 2.2.0

package/README.md

@@ -27,6 +27,8 @@
 
 # Table of Contents
 
+> See [agents.md](agents.md) for consumer API reference. Detailed guides in [docs/](docs/).
+
 - [🎇 Benefits](#-benefits)
 - [📗 Libraries](#-libraries)
 - [📁 Dependencies](#-dependencies)

package/agents.md

@@ -0,0 +1,157 @@
+## @odg/chemical-x - Consumer Guide
+
+## 🎯 Purpose
+
+- Framework TypeScript para automação web (scraping, crawling) com abstração sobre Puppeteer/Playwright, retry com lifecycle hooks e DSL baseada em decorators.
+- Helpers utilitários (`retry`, `sleep`, `timeout`, `throwIf`) para controle de fluxo assíncrono com tratamento de erros tipado.
+- Arquitetura Page/Handler: Pages executam ações por **intenção** (não por URL); Handlers validam transições e declaram soluções ou exceções.
+
+## 🚀 Quick Start
+
+```typescript
+// Helpers — sem browser driver necessário
+import { retry, sleep, timeout, throwIf, RetryAction } from "@odg/chemical-x";
+
+const result = await retry({
+    times: 3,
+    sleep: 1000,
+    callback: async (attempt) => { /* operação retriable */ },
+});
+
+// Crawler — requer Puppeteer ou Playwright instalado
+import { BrowserManager, BasePage, BaseHandler, Container } from "@odg/chemical-x";
+```
+
+## 📜 Quick API Reference
+
+**Helpers** — Controle de fluxo assíncrono:
+
+| Função | Propósito |
+|---|---|
+| `retry(options)` | Retenta callback N vezes com sleep, abort signal e callback `when` para decidir ação por tentativa |
+| `sleep(ms, options?)` | Pausa assíncrona com suporte a `AbortSignal` |
+| `timeout(options)` | Envolve callback com limite de tempo; lança `TimeoutException` se exceder |
+| `throwIf(condition, exception)` | Lança exceção condicionalmente; tipagem `never` quando `condition: true` |
+
+📖 See also: [docs/helpers.md](docs/helpers.md)
+
+**Decorators** — DSL para classes:
+
+| Decorator | Propósito |
+|---|---|
+| `@attemptableFlow()` | Retry a nível de classe com lifecycle hooks (`attempt`, `sleep`, `success`, `failure`, `retrying`, `finish`) |
+| `@getterAccess()` | Proxy que intercepta todo acesso a propriedades via `__get(key, value)` |
+| `@injectablePageOrHandler(name)` | Registra classe no Container (Inversify) com `@injectable` + `@injectFromHierarchy` |
+| `@registerListener(event, container, options)` | Registra listener de eventos em Container EventEmitter |
+
+📖 See also: [docs/decorators.md](docs/decorators.md)
+
+**Crawler** — Automação web:
+
+| Classe | Propósito |
+|---|---|
+| `BrowserManager` | Orquestrador: cria instâncias de Browser e Context via factories injetadas |
+| `Browser` | Wrapper com `@getterAccess` sobre engine do browser; gerencia Contexts |
+| `Context` | Wrapper sobre contexto do browser; gerencia Pages |
+| `Page` | Wrapper sobre page do browser com acesso ao Context pai |
+| `BasePage` (abstract) | Define uma página por intenção; implementa `execute()` + `attempt()` + seletores `$s`/`$$s` |
+| `BaseHandler` (abstract) | Valida transições; implementa `waitForHandler()` + `attempt()`; declara Solution ou Exception |
+
+📖 See also: [docs/crawlers.md](docs/crawlers.md)
+
+**Support** — Utilidades tipadas:
+
+| Classe | Propósito |
+|---|---|
+| `Str` | Manipulação de string: extração monetária (`money()`, `moneys()`), `onlyNumbers()`, `ucFirst()`, `isJson()`, `formatUnicorn()` |
+| `Num` | Wrapper numérico com `toNative()` e `clone()` |
+| `Arr<Type>` | Wrapper de array com `random(length?)` e `clone()` |
+| `File` | Verificação de existência de arquivo via `exists()` |
+
+**Enums:**
+
+| Enum | Valores |
+|---|---|
+| `RetryAction` | `Retry` (forçar retry), `Throw` (lançar), `Resolve` (resolver com undefined), `Default` (seguir `times`) |
+
+**Container:**
+
+- `Container<T>` estende `TypedContainer` (Inversify); adiciona `getOptional(name)` que retorna `undefined` se não registrado.
+
+## 🚦 Key Rules
+
+1. **`@attemptableFlow` vs `retry()`**: Use `@attemptableFlow` para retry a nível de classe com lifecycle hooks completo (attempt, success, failure, retrying, finish, sleep). Use `retry()` para retentativa simples de um callback isolado.
+   📖 See also: [docs/decorators.md](docs/decorators.md)
+
+2. **`@getterAccess` — Proxy total**: Todo acesso a propriedade/método passa por `__get(key, value)`. Implementações de Browser, Context e Page usam isso para delegar ao engine subjacente.
+   📖 See also: [docs/decorators.md](docs/decorators.md)
+
+3. **Page Intent Design**: Pages agrupam por **intenção**, não por URL. Uma mesma URL pode ter múltiplas Pages (ex: `LoginPage` para autenticar, `HomeVerificationPage` para validar conteúdo).
+   📖 See also: [docs/crawlers.md](docs/crawlers.md)
+
+4. **Handler Validation Contract**: Handlers **validam**, não executam. `waitForHandler()` retorna `Exception` ou `() => Promise<HandlerSolutionType>`. O handler declara Solution (próxima Page) ou lança Exception. Nunca falha silenciosamente.
+   📖 See also: [docs/crawlers.md](docs/crawlers.md)
+
+5. **Container.loadModule() obrigatório**: Classes com `@injectablePageOrHandler` precisam de `Container.loadModule()` antes da execução. DI binding é responsabilidade do consumidor.
+   📖 See also: [docs/crawlers.md](docs/crawlers.md)
+
+6. **`retry()` com `when` callback**: O callback `when(exception, times)` retorna `RetryAction` para decidir por tentativa: `Retry` (forçar), `Throw` (parar), `Resolve` (resolver com `undefined`), `Default` (seguir contagem `times`).
+   📖 See also: [docs/helpers.md](docs/helpers.md)
+
+7. **Seletores `$s` e `$$s` em Pages/Handlers**: `$s` define seletor único da página; `$$s` define mapa nomeado de seletores (`Record<string, SelectorType>`). Ambos são `abstract readonly` em `BasePage`/`BaseHandler`.
+   📖 See also: [docs/crawlers.md](docs/crawlers.md)
+
+8. **`AttemptableInterface` — contrato base**: Tanto `BasePage` quanto `BaseHandler` implementam `AttemptableInterface`. Hooks opcionais: `success()`, `failure(exception)`, `retrying(exception, attempt)`, `finish(exception?)`, `sleep()`. Obrigatórios: `execute()`, `attempt()`.
+   📖 See also: [docs/decorators.md](docs/decorators.md)
+
+## 💥 Critical Exceptions
+
+| Exception | Quando é lançada | Handling |
+|---|---|---|
+| `BrowserException` | Falha em operação do browser em runtime (crash, perda de conexão) | Catch e retry ou fallback |
+| `BrowserInstanceException` | Falha ao criar/inicializar instância do browser (extends `BrowserException`) | Verificar setup do driver, retry init |
+| `RetryException` | Todas as tentativas de `retry()` esgotadas sem sucesso | Fallback final ou propagar erro |
+| `TimeoutException` | Operação excede o limite de `timeout()` | Catch e tratar timeout; ajustar limite se válido |
+| `InvalidArgumentException` | Parâmetros inválidos (ex: `times < 1`, timeout negativo) | Validar inputs antes de chamar API |
+| `MoneyNotFoundException` | `Str.money()` não encontra valor monetário na string | Verificar formato da string antes |
+| `MoneyMultipleResultException` | `Str.money()` encontra múltiplos valores; use `Str.moneys()` | Usar `moneys()` para múltiplos valores |
+
+📖 See also: [docs/exceptions.md](docs/exceptions.md) para referência completa com exemplos de try-catch.
+
+## ⚠️ Integration Pitfalls
+
+1. **Node 24+ obrigatório**: `engines.node >= 24.0` no package.json; versões anteriores não são suportadas.
+2. **Puppeteer/Playwright NÃO incluído**: Crawler APIs requerem driver de browser, mas o consumidor **deve instalar separadamente**. Helpers e Decorators funcionam sem driver.
+3. **DI é responsabilidade do consumidor**: Chemical-X usa Inversify mas **não auto-wira**. Consumidor deve registrar bindings e chamar `Container.loadModule()`.
+4. **Driver não é auto-selecionado**: Consumer configura qual driver usar via binding no Container ou construtor do `BrowserManager`. Puppeteer e Playwright são intercambiáveis via configuração.
+5. **`Container.loadModule()` antes de executar**: Sem essa chamada, classes registradas com `@injectablePageOrHandler` não estarão disponíveis no container.
+6. **Pages por intenção, não por URL**: Não assuma 1:1 entre URL e Page. Modele Pages pela responsabilidade/ação desejada.
+7. **Handlers não agem — validam**: Handler nunca deve interagir com a page diretamente nem chamar outras Pages. Declara Solution ou lança Exception.
+8. **Dependências de runtime**: `@odg/exception`, `inversify` e `@inversifyjs/binding-decorators` são dependências obrigatórias em runtime.
+
+## 📖 Detailed Documentation
+
+| Documento | Conteúdo |
+|---|---|
+| [docs/helpers.md](docs/helpers.md) | Guia completo de `retry()`, `sleep()`, `timeout()`, `throwIf()` com padrões de uso |
+| [docs/crawlers.md](docs/crawlers.md) | Arquitetura Crawler: BrowserManager, Pages, Handlers, Container/DI, workflow examples |
+| [docs/decorators.md](docs/decorators.md) | `@attemptableFlow`, `@getterAccess`, `@injectablePageOrHandler` com lifecycle e exemplos |
+| [docs/exceptions.md](docs/exceptions.md) | Referência completa de exceções com trigger, handling e exemplos |
+
+## 🔗 Interfaces Públicas
+
+| Interface | Propósito |
+|---|---|
+| `AttemptableInterface` | Contrato base para Pages e Handlers: `execute()`, `attempt()`, hooks opcionais |
+| `PageInterface` | Extends `AttemptableInterface`; contrato para `BasePage` |
+| `HandlerInterface` | Extends `AttemptableInterface`; adiciona `waitForHandler()` |
+| `GetterAccessInterface` | Define `__get(key, value)` para classes com `@getterAccess` |
+| `CloneableInterface` | Define `clone()` para Support utilities (`Str`, `Num`, `Arr`) |
+| `NativeInterface<Type>` | Define `toNative()` para conversão ao tipo primitivo |
+| `RetryOptionsInterface` | Parâmetros de `retry()`: `times`, `sleep`, `callback`, `signal` |
+| `TimeoutOptionsInterface` | Parâmetros de `timeout()`: `name`, `timeout`, `callback` |
+
+## 🔍 Entry Points
+
+- **Main**: `import { retry, sleep, BrowserManager, BasePage, ... } from "@odg/chemical-x"`
+- **Container only**: `import { Container } from "@odg/chemical-x/container"`

package/docs/crawlers.md

@@ -0,0 +1,240 @@
+## Chemical-X Crawler API - Pages, Handlers, BrowserManager
+
+Arquitetura para automação web com abstração sobre Puppeteer/Playwright. Requer driver de browser instalado separadamente.
+
+```typescript
+import { BrowserManager, BasePage, BaseHandler, Browser, Context, Page, Container } from "@odg/chemical-x";
+```
+
+---
+
+### BrowserManager
+
+Orquestrador central que cria instâncias de Browser e Context via factories injetadas pelo consumidor.
+
+**Assinatura:**
+
+```typescript
+class BrowserManager<BrowserClassEngine, ContextClassEngine, PageClassEngine> {
+    constructor(
+        $newBrowser: CreateBrowserFactoryType<BrowserClassEngine, ContextClassEngine, PageClassEngine>,
+        $newContext: CreateContextFactoryType<ContextClassEngine, PageClassEngine>,
+        $newPage: CreatePageFactoryType<PageClassEngine>,
+    )
+
+    async newBrowser(
+        browser: () => Promise<BrowserClassEngine>,
+    ): Promise<BrowserChemicalXInterface<...> & BrowserClassEngine>
+
+    async newPersistentContext(
+        context: () => Promise<ContextClassEngine>,
+    ): Promise<ContextChemicalXInterface<...> & ContextClassEngine>
+}
+```
+
+**Responsabilidades:**
+
+- Cria instâncias de `Browser` via `newBrowser()` — recebe factory que retorna engine do browser
+- Cria contextos persistentes via `newPersistentContext()` — recebe factory que retorna engine do contexto
+- **Não auto-seleciona driver**: consumer configura Puppeteer ou Playwright via factory injetada
+- Retorna objetos que combinam interface Chemical-X com o engine nativo (via `@getterAccess` proxy)
+
+**Lifecycle:**
+
+1. Consumer instancia `BrowserManager` com factories (normalmente via Container/DI)
+2. `newBrowser(() => puppeteer.launch())` → retorna `Browser` com proxy sobre Puppeteer
+3. `browser.newContext(options?)` → retorna `Context` com proxy
+4. `context.newPage()` → retorna `Page` com proxy
+
+---
+
+### Browser, Context, Page (Wrappers)
+
+Wrappers com `@getterAccess` que delegam acesso ao engine nativo de forma transparente.
+
+**Browser:**
+
+```typescript
+@ODGDecorators.getterAccess()
+class Browser<BrowserClassEngine, ContextClassEngine, PageClassEngine>
+    implements GetterAccessInterface, BrowserChemicalXInterface<...> {
+
+    $browserInstance: BrowserClassEngine;
+    async defaultContextOptions(): Promise<ContextOptionsLibraryInterface>;
+    async newContext(options?): Promise<ContextChemicalXInterface<...> & ContextClassEngine>;
+    contexts(): Array<ContextChemicalXInterface<...> & ContextClassEngine>;
+    __get(key: PropertyKey): unknown;
+}
+```
+
+**Context:**
+
+```typescript
+@ODGDecorators.getterAccess()
+class Context<ContextClassEngine, PageClassEngine>
+    implements GetterAccessInterface, ContextChemicalXInterface<...> {
+
+    $contextInstance: ContextClassEngine;
+    async defaultPageOptions(): Promise<PageOptionsLibraryInterface>;
+    async newPage(options?): Promise<PageChemicalXInterface<...> & PageClassEngine>;
+    pages(): Array<PageChemicalXInterface<...> & PageClassEngine>;
+    __get(key: PropertyKey): unknown;
+}
+```
+
+**Page:**
+
+```typescript
+@ODGDecorators.getterAccess()
+class Page<ContextClassEngine, PageClassEngine>
+    implements GetterAccessInterface, PageChemicalXInterface<...> {
+
+    $pageInstance: PageClassEngine;
+    context(): ContextChemicalXInterface<...> & ContextClassEngine;
+    __get(key: PropertyKey): unknown;
+}
+```
+
+Todos usam `@getterAccess` para delegar acessos de propriedade/método ao engine subjacente. Isso permite chamar métodos nativos do Puppeteer/Playwright diretamente no wrapper.
+
+---
+
+### BasePage (Abstract)
+
+Define uma página por **intenção**, não por URL. Implementa `AttemptableInterface` com lifecycle hooks para retry via `@attemptableFlow`.
+
+**Assinatura:**
+
+```typescript
+abstract class BasePage<PageClassEngine> implements PageInterface {
+    currentAttempt: number = 0;
+    page?: PageClassEngine;
+
+    abstract readonly $s?: SelectorType;                              // Seletor principal
+    abstract readonly $$s?: Record<string | number | symbol, SelectorType>; // Mapa de seletores
+
+    setPage(page: PageClassEngine): this;
+
+    // Obrigatórios (abstract)
+    abstract execute(): Promise<void>;    // Ação principal da página
+    abstract attempt(): Promise<number>;  // Retorna número de tentativas
+
+    // Hooks opcionais (lifecycle do @attemptableFlow)
+    success?(): Promise<void>;
+    failure?(exception: Exception): Promise<void>;
+    retrying?(exception: Exception, attempt: number): Promise<RetryAction>;
+    finish?(exception?: Exception): Promise<void>;
+    sleep?(): Promise<number>;
+}
+```
+
+**Page Intent Design:**
+
+> Pages agrupam por **INTENÇÃO**, não por URL. Uma mesma URL pode ter múltiplas Pages.
+
+Exemplos:
+- `LoginPage` (intenção: autenticar) — URL: `/login`
+- `LoginVerificationPage` (intenção: verificar se login OK) — URL: `/login` ou `/dashboard`
+- `HomeContentPage` (intenção: extrair conteúdo) — URL: `/`
+- `HomeAdPage` (intenção: extrair anúncios) — URL: `/`
+
+**Lifecycle:**
+
+1. `setPage(page)` — injeta instância da page do browser
+2. `execute()` — executa ação (navegar, preencher, clicar)
+3. Se falha → `retrying(exception, attempt)` decide retry ou não
+4. Se sucesso → `success()`
+5. Se falha final → `failure(exception)`
+6. Sempre → `finish(exception?)`
+
+---
+
+### BaseHandler (Abstract)
+
+Valida transições e resultados de páginas. **Handlers validam, não executam ações.**
+
+**Assinatura:**
+
+```typescript
+abstract class BaseHandler<PageClassEngine> implements HandlerInterface {
+    currentAttempt: number = 0;
+    page?: PageClassEngine;
+
+    abstract readonly $$s: Record<string | number | symbol, SelectorType>;
+
+    setPage(page: PageClassEngine): this;
+
+    // Concrete
+    async execute(): Promise<void>;
+    async successSolution(): Promise<HandlerSolutionType>; // Retorna RetryAction.Resolve
+
+    // Obrigatórios (abstract)
+    abstract waitForHandler(): Promise<HandlerFunction>;   // Retorna Exception ou solution function
+    abstract attempt(): Promise<number>;
+
+    // Hooks opcionais
+    success?(): Promise<void>;
+    failure?(exception: Exception): Promise<void>;
+    retrying?(exception: Exception, attempt: number): Promise<RetryAction>;
+    finish?(exception?: Exception): Promise<void>;
+    sleep?(): Promise<number>;
+}
+```
+
+**Tipos de retorno de Handler:**
+
+```typescript
+type HandlerSolutionType = Exception | Exclude<RetryAction, RetryAction.Default | RetryAction.Throw>;
+type HandlerFunction = Exception | (() => Promise<HandlerSolutionType>);
+```
+
+**Handler Pattern:**
+
+> "Pages executam. Handlers validam. Handlers declaram Solution ou lançam Exception."
+
+- `waitForHandler()` retorna `Exception` → falha detectada
+- `waitForHandler()` retorna `() => Promise<HandlerSolutionType>` → solução disponível
+- Solution pode ser: `RetryAction.Resolve` (sucesso), `RetryAction.Retry` (tentar novamente)
+- Handler **NUNCA** interage com a page diretamente
+- Handler **NUNCA** chama outras Pages para resolver problemas
+- Handler **NUNCA** falha silenciosamente
+
+---
+
+### Container / DI
+
+Chemical-X usa Inversify para DI. `@injectablePageOrHandler(name)` registra metadata; consumer deve chamar `Container.loadModule()`.
+
+**Regras:**
+
+1. `Container.loadModule()` **obrigatório** antes de executar qualquer Page/Handler registrado
+2. DI binding é **responsabilidade do consumidor** — Chemical-X não auto-wira
+3. `Container.getOptional(name)` retorna `undefined` se serviço não registrado (vs `get()` que lança)
+4. Puppeteer/Playwright deve ser injetado via Container ou passado ao `BrowserManager` constructor
+
+---
+
+### Workflow Example
+
+Fluxo completo: login em site com tratamento de 2FA.
+
+```
+1. Create LoginPage (intent: autenticar)
+   → setPage(page) → execute() (navegar, preencher credenciais, clicar login)
+
+2. Create LoginHandler (intent: validar resultado do login)
+   → setPage(page) → waitForHandler()
+   → Detecta 2FA required → return () => new TwoFaPage() as Solution
+   → Detecta login error → return new InvalidCredentialsException()
+   → Detecta sucesso → return successSolution() (RetryAction.Resolve)
+
+3. Se Solution = TwoFaPage:
+   → Create TwoFaPage (intent: resolver 2FA)
+   → setPage(page) → execute() (preencher código 2FA)
+
+4. Create DashboardHandler (intent: verificar que chegou no dashboard)
+   → setPage(page) → waitForHandler()
+   → Verifica URL/conteúdo → return successSolution()
+```
+
+See also: `tests/vitest/Handlers/` e `tests/vitest/Pages/` para exemplos reais de implementação.

package/docs/decorators.md

@@ -0,0 +1,257 @@
+## Chemical-X Decorators - @attemptableFlow, @getterAccess, @injectablePageOrHandler
+
+DSL baseada em decorators para retry com lifecycle, interceptação de acesso e DI registration.
+
+```typescript
+import { ODGDecorators } from "@odg/chemical-x";
+```
+
+---
+
+### `@attemptableFlow()`
+
+Decorator de classe que adiciona retry com lifecycle hooks completo. Envolve `execute()` com lógica de retentativa baseada em `AttemptableInterface`.
+
+**Aplicação:**
+
+```typescript
+@ODGDecorators.attemptableFlow()
+class MyPage extends BasePage<PageEngine> {
+    // ...
+}
+```
+
+**Lifecycle Hooks:**
+
+| Hook | Obrigatório | Quando chamado |
+|---|---|---|
+| `execute()` | Sim | Ação principal; retentada até `attempt()` vezes |
+| `attempt()` | Sim | Retorna número máximo de tentativas |
+| `sleep()` | Não | Retorna ms entre tentativas (se definido) |
+| `success()` | Não | Chamado quando `execute()` sucede |
+| `failure(exception)` | Não | Chamado quando todas tentativas falham; recebe a última exceção |
+| `retrying(exception, attempt)` | Não | Chamado antes de cada retry; retorna `RetryAction` para decidir ação |
+| `finish(exception?)` | Não | Chamado sempre ao final (sucesso ou falha); recebe exceção se houve |
+
+**Propriedade:**
+
+- `currentAttempt: number` — número da tentativa atual (atualizado automaticamente pelo decorator)
+
+**Fluxo de Execução:**
+
+```
+execute() chamado
+  ├─ Sucesso → success() → finish()
+  └─ Falha → retrying(exception, attempt)?
+               ├─ RetryAction.Retry → execute() novamente
+               ├─ RetryAction.Throw → failure(exception) → finish(exception)
+               ├─ RetryAction.Resolve → finish() (sem exceção, resolve undefined)
+               └─ RetryAction.Default → se attempts restam → sleep() → execute()
+                                         └─ se esgotou → failure(exception) → finish(exception)
+```
+
+**Exemplo:**
+
+```typescript
+@ODGDecorators.attemptableFlow()
+class LoginPage extends BasePage<PuppeteerPage> {
+    readonly $s = "form#login";
+    readonly $$s = {
+        username: "input[name=username]",
+        password: "input[name=password]",
+        submit: "button[type=submit]",
+    };
+
+    async attempt(): Promise<number> {
+        return 3;
+    }
+
+    async execute(): Promise<void> {
+        await this.page!.type(this.$$s.username, "user@example.com");
+        await this.page!.type(this.$$s.password, "password123");
+        await this.page!.click(this.$$s.submit);
+    }
+
+    async sleep(): Promise<number> {
+        return 2000; // 2s entre tentativas
+    }
+
+    async success(): Promise<void> {
+        console.log("Login successful");
+    }
+
+    async failure(exception: Exception): Promise<void> {
+        console.error("Login failed after all attempts:", exception.message);
+    }
+
+    async retrying(exception: Exception, attempt: number): Promise<RetryAction> {
+        if (exception instanceof BrowserException) return RetryAction.Throw;
+        return RetryAction.Default;
+    }
+}
+```
+
+See also: `tests/vitest/Pages/` para exemplos de Pages com `@attemptableFlow`.
+
+---
+
+### `@getterAccess()`
+
+Decorator de classe que cria um Proxy interceptando **todo** acesso a propriedade/método via `__get(key, value)`.
+
+**Aplicação:**
+
+```typescript
+@ODGDecorators.getterAccess()
+class MyWrapper implements GetterAccessInterface {
+    __get(key: PropertyKey, value: unknown): unknown {
+        // Intercepta todo acesso
+        return value;
+    }
+}
+```
+
+**Comportamento do Proxy:**
+
+- **Todo** acesso a propriedade (leitura) passa por `__get(key, value)` onde:
+  - `key` = nome da propriedade acessada
+  - `value` = valor original da propriedade (se existir)
+- Permite: delegação transparente ao engine, validação, lazy-load, tracking, logging
+
+**Uso interno no Chemical-X:**
+
+`Browser`, `Context` e `Page` usam `@getterAccess` para delegar ao engine nativo:
+
+```typescript
+@ODGDecorators.getterAccess()
+class Browser<BrowserClassEngine, ...> implements GetterAccessInterface {
+    $browserInstance: BrowserClassEngine;
+
+    __get(key: PropertyKey): unknown {
+        // Delega ao engine nativo (Puppeteer/Playwright)
+        return (this.$browserInstance as Record<PropertyKey, unknown>)[key];
+    }
+}
+```
+
+Isso permite:
+```typescript
+const browser = await manager.newBrowser(() => puppeteer.launch());
+// Acessa métodos nativos do Puppeteer diretamente no wrapper:
+await browser.close(); // Delegado via __get → puppeteerBrowser.close()
+```
+
+See also: `tests/vitest/puppeteer/` e `tests/vitest/playwright/` para exemplos de uso com drivers reais.
+
+---
+
+### `@injectablePageOrHandler(name)`
+
+Registra classe no Container (Inversify) com `@injectable()` e `@injectFromHierarchy()`.
+
+**Aplicação:**
+
+```typescript
+@ODGDecorators.injectablePageOrHandler("LoginPage")
+@ODGDecorators.attemptableFlow()
+class LoginPage extends BasePage<PageEngine> {
+    // ...
+}
+```
+
+**Regras:**
+
+1. Define metadata para DI — **não registra automaticamente no Container**
+2. Consumer **deve** chamar `Container.loadModule()` para efetivar os bindings
+3. Combinado com `@attemptableFlow` em Pages e Handlers
+4. O `name` é usado como identificador do binding no Container
+
+---
+
+### `@registerListener(eventName, containerName, options)`
+
+Registra listener de eventos em Container EventEmitter via metadata.
+
+**Aplicação:**
+
+```typescript
+@ODGDecorators.registerListener("page:loaded", "PageEventEmitter", { once: true })
+class PageLoadedListener {
+    // ...
+}
+```
+
+---
+
+### Comparison - When to Use
+
+| Cenário | Ferramenta | Motivo |
+|---|---|---|
+| Retry simples de callback | `retry()` | Função isolada, sem lifecycle, sem estado |
+| Retry de classe inteira com hooks | `@attemptableFlow` | Lifecycle completo: attempt, success, failure, retrying, finish, sleep |
+| Interceptar propriedades | `@getterAccess` | Proxy transparente para delegação/validação |
+| Registrar no Container | `@injectablePageOrHandler` | DI via Inversify com hierarchy |
+| Callback com timeout | `timeout()` | Sem retry, apenas limite de tempo |
+| Classe retriable com timeout | `@attemptableFlow` + `timeout()` no `execute()` | Combine ambos para retry + timeout |
+
+**Regra geral:**
+- Use `retry()` quando quer retentar **uma função**
+- Use `@attemptableFlow` quando quer retentar **um comportamento de classe** com estado e lifecycle
+
+---
+
+### Common Patterns
+
+**@attemptableFlow com handler e solução:**
+
+```typescript
+@ODGDecorators.injectablePageOrHandler("LoginHandler")
+@ODGDecorators.attemptableFlow()
+class LoginHandler extends BaseHandler<PuppeteerPage> {
+    readonly $$s = {
+        errorMsg: ".error-message",
+        dashboard: "#dashboard",
+        twoFa: "#two-fa-form",
+    };
+
+    async attempt(): Promise<number> {
+        return 5;
+    }
+
+    async waitForHandler(): Promise<HandlerFunction> {
+        // Espera por um dos seletores aparecer na página
+        const found = await this.page!.waitForSelector(
+            [this.$$s.errorMsg, this.$$s.dashboard, this.$$s.twoFa].join(", "),
+        );
+
+        if (found?.matches(this.$$s.errorMsg)) {
+            return new BrowserException("Login failed");
+        }
+
+        if (found?.matches(this.$$s.twoFa)) {
+            return async () => RetryAction.Retry; // Indica que precisa retry (2FA page)
+        }
+
+        return async () => this.successSolution(); // RetryAction.Resolve
+    }
+}
+```
+
+**@getterAccess para wrapper customizado:**
+
+```typescript
+@ODGDecorators.getterAccess()
+class CachedPage implements GetterAccessInterface {
+    private cache = new Map<PropertyKey, unknown>();
+    private wrapped: SomeEngine;
+
+    __get(key: PropertyKey, value: unknown): unknown {
+        if (this.cache.has(key)) return this.cache.get(key);
+        const result = (this.wrapped as Record<PropertyKey, unknown>)[key];
+        this.cache.set(key, result);
+        return result;
+    }
+}
+```
+
+See also: `tests/vitest/Handlers/` e `tests/vitest/Listeners/` para exemplos reais.

package/docs/exceptions.md

@@ -0,0 +1,212 @@
+## Chemical-X Exceptions - Reference Guide
+
+Referência completa de todas as exceções públicas. Todas estendem `Exception` de `@odg/exception`.
+
+```typescript
+import {
+    BrowserException,
+    BrowserInstanceException,
+    RetryException,
+    TimeoutException,
+    InvalidArgumentException,
+    MoneyNotFoundException,
+    MoneyMultipleResultException,
+} from "@odg/chemical-x";
+```
+
+---
+
+### Exception Reference
+
+#### `BrowserException`
+
+| | |
+|---|---|
+| **Trigger** | Falha em operação do browser em runtime (crash, perda de conexão, operação inválida) |
+| **Quando** | Interações com Page/Browser via Crawler API (click, type, goto, etc.) |
+| **Extends** | `Exception` (`@odg/exception`) |
+| **Handling** | Catch e retry (via `@attemptableFlow`) ou fallback |
+
+```typescript
+try {
+    await page.execute();
+} catch (exception) {
+    if (exception instanceof BrowserException) {
+        // Browser crashed ou conexão perdida — retry ou fallback
+    }
+}
+```
+
+---
+
+#### `BrowserInstanceException`
+
+| | |
+|---|---|
+| **Trigger** | Falha ao criar/inicializar instância do browser |
+| **Quando** | `BrowserManager.newBrowser()` ou `BrowserManager.newPersistentContext()` |
+| **Extends** | `BrowserException` |
+| **Handling** | Verificar setup do driver (Puppeteer/Playwright instalado?), retry init |
+
+```typescript
+try {
+    const browser = await manager.newBrowser(() => puppeteer.launch());
+} catch (exception) {
+    if (exception instanceof BrowserInstanceException) {
+        // Driver não encontrado ou falha ao iniciar — verificar instalação
+    }
+}
+```
+
+---
+
+#### `RetryException`
+
+| | |
+|---|---|
+| **Trigger** | Todas as tentativas de `retry()` esgotadas sem sucesso |
+| **Quando** | `retry()` completa todos os `times` sem callback suceder |
+| **Extends** | `Exception` (`@odg/exception`) |
+| **Handling** | Fallback final ou propagar erro ao chamador |
+
+```typescript
+try {
+    await retry({ times: 3, callback: async () => { /* ... */ } });
+} catch (exception) {
+    if (exception instanceof RetryException) {
+        // Todas tentativas falharam — aplicar fallback ou logar erro final
+    }
+}
+```
+
+---
+
+#### `TimeoutException`
+
+| | |
+|---|---|
+| **Trigger** | Operação excede o limite de tempo definido em `timeout()` |
+| **Quando** | `timeout({ timeout: ms, callback })` quando callback não completa a tempo |
+| **Extends** | `Exception` (`@odg/exception`) |
+| **Handling** | Catch e tratar timeout; ajustar limite se operação legitimamente lenta |
+
+```typescript
+try {
+    await timeout({
+        name: "loadPage",
+        timeout: 5000,
+        callback: async () => await page.goto(url),
+    });
+} catch (exception) {
+    if (exception instanceof TimeoutException) {
+        // Operação "loadPage" excedeu 5000ms — retry ou aumentar limite
+    }
+}
+```
+
+---
+
+#### `InvalidArgumentException`
+
+| | |
+|---|---|
+| **Trigger** | Parâmetros inválidos passados para API |
+| **Quando** | `retry({ times: -1 })`, timeout negativo, argumento obrigatório ausente |
+| **Extends** | `Exception` (`@odg/exception`) |
+| **Handling** | Validar inputs antes de chamar API; este é um erro de programação |
+
+```typescript
+// Este erro indica bug no código do consumidor:
+try {
+    await retry({ times: 0, callback: async () => {} });
+} catch (exception) {
+    if (exception instanceof InvalidArgumentException) {
+        // Corrigir: times deve ser >= 1
+    }
+}
+```
+
+---
+
+#### `MoneyNotFoundException`
+
+| | |
+|---|---|
+| **Trigger** | `Str.money()` não encontra valor monetário na string |
+| **Quando** | `new Str("texto sem valor").money()` |
+| **Extends** | `Exception` (`@odg/exception`) |
+| **Handling** | Verificar formato da string antes; usar try-catch ou validar conteúdo |
+
+```typescript
+try {
+    const value = new Str(rawText).money();
+} catch (exception) {
+    if (exception instanceof MoneyNotFoundException) {
+        // String não contém valor monetário reconhecível
+    }
+}
+```
+
+---
+
+#### `MoneyMultipleResultException`
+
+| | |
+|---|---|
+| **Trigger** | `Str.money()` encontra múltiplos valores monetários na string |
+| **Quando** | `new Str("R$ 10,00 e R$ 20,00").money()` — use `moneys()` |
+| **Extends** | `Exception` (`@odg/exception`) |
+| **Handling** | Usar `Str.moneys()` para extrair todos os valores; `money()` espera exatamente um |
+
+```typescript
+try {
+    const value = new Str("R$ 10,00 e R$ 20,00").money();
+} catch (exception) {
+    if (exception instanceof MoneyMultipleResultException) {
+        // Múltiplos valores encontrados — usar moneys() em vez de money()
+        const values = new Str("R$ 10,00 e R$ 20,00").moneys();
+    }
+}
+```
+
+---
+
+### Handler Exception/Solution Contract
+
+`BaseHandler.waitForHandler()` retorna `HandlerFunction`:
+
+```typescript
+type HandlerSolutionType = Exception | Exclude<RetryAction, RetryAction.Default | RetryAction.Throw>;
+type HandlerFunction = Exception | (() => Promise<HandlerSolutionType>);
+```
+
+**Contrato:**
+
+1. Handler **deve** retornar `Exception` (falha) ou `() => Promise<HandlerSolutionType>` (solução)
+2. Handler **nunca** falha silenciosamente (retornar `void`/`undefined` não permitido)
+3. Solution function retorna:
+   - `RetryAction.Resolve` — sucesso (via `successSolution()`)
+   - `RetryAction.Retry` — retentar
+   - `Exception` — falha específica detectada na validação
+
+**Exemplo — Handler com contrato completo:**
+
+```typescript
+async waitForHandler(): Promise<HandlerFunction> {
+    // Espera seletores e decide
+    const errorVisible = await this.page!.$(this.$$s.error);
+    if (errorVisible) {
+        return new BrowserException("Login failed: error message visible");
+    }
+
+    const dashboardVisible = await this.page!.$(this.$$s.dashboard);
+    if (dashboardVisible) {
+        return async () => this.successSolution(); // RetryAction.Resolve
+    }
+
+    // Estado intermediário — retentar
+    return async () => RetryAction.Retry;
+}
+```
+
+See also: `tests/vitest/Exceptions/` e `tests/vitest/Handlers/` para exemplos de teste.

package/docs/helpers.md

@@ -0,0 +1,223 @@
+## Chemical-X Helpers - Detailed Guide
+
+Funções utilitárias para controle de fluxo assíncrono com tratamento de erros tipado. Não requerem browser driver.
+
+```typescript
+import { retry, sleep, timeout, throwIf, RetryAction } from "@odg/chemical-x";
+```
+
+---
+
+### `retry(options)`
+
+Retenta um callback N vezes com controle fino sobre sleep, abort e decisão por tentativa.
+
+**Assinatura:**
+
+```typescript
+// Quando `when` retorna Default | Retry | Throw (ou não fornecido): retorna ReturnType
+async function retry<ReturnType>(options: {
+    times: number;
+    sleep?: number;
+    signal?: AbortSignal;
+    callback(attempt: number, signal?: AbortSignal): Promise<ReturnType> | ReturnType;
+    when?(exception: Exception, times: number): Promise<RetryAction> | RetryAction;
+}): Promise<ReturnType>;
+
+// Quando `when` pode retornar Resolve: retorno inclui undefined
+async function retry<ReturnType>(options: {
+    times: number;
+    sleep?: number;
+    signal?: AbortSignal;
+    callback(attempt: number, signal?: AbortSignal): Promise<ReturnType> | ReturnType;
+    when?(exception: Exception, times: number): Promise<RetryAction> | RetryAction;
+}): Promise<ReturnType | undefined>;
+```
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|---|---|---|---|
+| `times` | `number` | Sim | Número máximo de tentativas. `InvalidArgumentException` se < 1 |
+| `sleep` | `number` | Não | Milissegundos entre tentativas |
+| `signal` | `AbortSignal` | Não | Sinal de abort para cancelar retries |
+| `callback` | `(attempt, signal?) => T` | Sim | Função a ser retentada. Recebe número da tentativa atual |
+| `when` | `(exception, times) => RetryAction` | Não | Decide ação por tentativa: `Retry`, `Throw`, `Resolve`, `Default` |
+
+**Comportamento:**
+
+1. Executa `callback(attempt, signal)` até `times` tentativas
+2. Se callback sucede → retorna resultado
+3. Se callback falha e `when` está definido → chama `when(exception, remainingTimes)`:
+   - `RetryAction.Retry` → retenta imediatamente (ignora `times`)
+   - `RetryAction.Throw` → lança exceção imediatamente
+   - `RetryAction.Resolve` → resolve com `undefined`
+   - `RetryAction.Default` → segue contagem normal de `times`
+4. Se todas tentativas esgotam → lança `RetryException`
+5. Entre tentativas, aguarda `sleep` ms (se definido)
+
+**Exemplo:**
+
+```typescript
+const data = await retry({
+    times: 3,
+    sleep: 1000,
+    callback: async (attempt) => {
+        return await fetchData(attempt);
+    },
+    when: (exception, times) => {
+        if (exception instanceof FatalError) return RetryAction.Throw;
+        return RetryAction.Default;
+    },
+});
+```
+
+See also: `tests/vitest/helpers/retry.test.ts` para exemplos completos de padrões com retry.
+
+---
+
+### `sleep(milliseconds, options?)`
+
+Pausa assíncrona com suporte a cancelamento via `AbortSignal`.
+
+**Assinatura:**
+
+```typescript
+async function sleep(milliseconds: number, options?: { signal?: AbortSignal }): Promise<void>
+```
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|---|---|---|---|
+| `milliseconds` | `number` | Sim | Duração da pausa em milissegundos |
+| `options.signal` | `AbortSignal` | Não | Sinal para cancelar o sleep antecipadamente |
+
+**Exemplo:**
+
+```typescript
+await sleep(2000); // Pausa 2 segundos
+
+// Com abort
+const controller = new AbortController();
+await sleep(5000, { signal: controller.signal });
+```
+
+---
+
+### `timeout(options)`
+
+Envolve uma operação assíncrona com limite de tempo. Lança `TimeoutException` se exceder.
+
+**Assinatura:**
+
+```typescript
+async function timeout<ReturnType>(options: {
+    name?: string;
+    timeout?: number;
+    callback(): Promise<ReturnType> | ReturnType;
+}): Promise<ReturnType>
+```
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|---|---|---|---|
+| `name` | `string` | Não | Nome da operação (incluído na mensagem de `TimeoutException`) |
+| `timeout` | `number` | Não | Limite em milissegundos |
+| `callback` | `() => T` | Sim | Operação a ser executada com limite de tempo |
+
+**Comportamento:**
+
+- Se callback completa antes do limite → retorna resultado
+- Se excede limite → lança `TimeoutException` com nome da operação (se fornecido)
+
+**Exemplo:**
+
+```typescript
+const result = await timeout({
+    name: "fetchData",
+    timeout: 5000,
+    callback: async () => {
+        return await longRunningOperation();
+    },
+});
+```
+
+See also: `tests/vitest/helpers/timeout.test.ts` para exemplos com timeout.
+
+---
+
+### `throwIf(condition, exception)`
+
+Lança exceção condicionalmente com tipagem estrita — `never` quando condition é `true`.
+
+**Assinatura:**
+
+```typescript
+function throwIf(condition: true, exception: () => Exception): never;
+function throwIf(condition: false, exception: () => Exception): void;
+function throwIf(condition: boolean, exception: () => Exception): never | void;
+```
+
+**Parâmetros:**
+
+| Parâmetro | Tipo | Obrigatório | Descrição |
+|---|---|---|---|
+| `condition` | `boolean` | Sim | Se `true`, lança a exceção |
+| `exception` | `() => Exception` | Sim | Factory que cria a exceção (lazy — só chamada se `condition: true`) |
+
+**Exemplo:**
+
+```typescript
+throwIf(!user, () => new InvalidArgumentException("User is required"));
+// Após esta linha, TypeScript sabe que `user` existe (type narrowing via `never`)
+
+throwIf(amount < 0, () => new InvalidArgumentException("Amount must be positive"));
+```
+
+See also: `tests/vitest/helpers/throw-if.test.ts` para padrões de validação.
+
+---
+
+### Common Patterns
+
+**Retry com exponential backoff:**
+
+```typescript
+let delay = 500;
+const result = await retry({
+    times: 5,
+    sleep: delay,
+    callback: async (attempt) => {
+        delay = 500 * Math.pow(2, attempt - 1); // 500, 1000, 2000, 4000, 8000
+        return await unstableApi();
+    },
+});
+```
+
+**Retry com timeout por tentativa:**
+
+```typescript
+const result = await retry({
+    times: 3,
+    sleep: 1000,
+    callback: async (attempt) => {
+        return await timeout({
+            name: `attempt-${attempt}`,
+            timeout: 5000,
+            callback: () => fetchData(),
+        });
+    },
+});
+```
+
+**Validação com throwIf encadeado:**
+
+```typescript
+throwIf(!config.url, () => new InvalidArgumentException("URL is required"));
+throwIf(config.timeout < 0, () => new InvalidArgumentException("Timeout must be positive"));
+// config agora está validado com tipagem correta
+```
+
+See also: `tests/vitest/helpers/` para todos os testes de helpers.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@odg/chemical-x",
-    "version": "2.1.3",
+    "version": "2.2.0",
     "description": "Chemical-X Project It's the basis of everything",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -30,7 +30,9 @@
     },
     "files": [
         "./dist/",
-        "./README.md"
+        "./README.md",
+        "agents.md",
+        "docs/**"
     ],
     "author": "Dragons Gamers <https://www.linkedin.com/in/victor-alves-odgodinho>",
     "license": "MIT",