pwi-kdsmobile-hooks/README.md

Biblioteca de React Hooks para acompanhamento em tempo real de pedidos e exibição sequencial de senhas, ideal para sistemas de atendimento, painéis e aplicações que precisam consumir eventos do backend de forma simples e tipada.

# pwi-kdsmobile-hooks

Biblioteca de React Hooks para acompanhamento em tempo real de pedidos e exibição sequencial de senhas, ideal para sistemas de atendimento, painéis e aplicações que precisam consumir eventos do backend de forma simples e tipada.

[![npm version](https://img.shields.io/npm/v/pwi-kdsmobile-hooks.svg)](https://www.npmjs.com/package/pwi-kdsmobile-hooks)

---

## ✨ Principais Recursos
- Consumo de eventos de pedidos via SSE ou WebSocket
- Serialização de exibição de senhas (ex: modais animados)
- Tipos TypeScript completos para integração segura

---

## 🚀 Instalação

```bash
npm install pwi-kdsmobile-hooks
# ou
pnpm add pwi-kdsmobile-hooks
```

### Requisitos
- React >= 19.0.0
- TypeScript recomendado

---

## 📦 Hooks Disponíveis

### `usePedidoEventos`
Hook para consumir eventos de atualização de pedidos via SSE ou WebSocket.

**Assinatura:**
```ts
const pedidoEventos = usePedidoEventos({
  eventSourceUrl: string,
  token: string,
  onSenhasParaExibir: (senhas: Senha[]) => void,
  onError: (err: PlataError) => void,
})
```

**Retorno:**
- `iniciar(tipo: 'sse' | 'ws')`: inicia o consumo dos eventos
- `userHash`: identificador do usuário (string)
- `senhas`: array de senhas atuais

**Exemplo:**
```tsx
const pedidoEventos = usePedidoEventos({
  eventSourceUrl: 'https://api.exemplo.com',
  token: 'TOKEN_DO_PEDIDO',
  onSenhasParaExibir: (senhas) => { /* exibir senhas */ },
  onError: (err) => { /* tratar erro */ },
})

useEffect(() => {
  pedidoEventos.iniciar('sse')
}, [])
```

---

### `useFilaExibicaoSenha`
Hook para serializar a exibição de senhas (ex: modais animados).

**Assinatura:**
```ts
const { senhaExibicao, adicionarSenhas, fimExibicao } = useFilaExibicaoSenha()
```

- `senhaExibicao`: senha atualmente em exibição (ou null)
- `adicionarSenhas(senhas: Senha[])`: adiciona novas senhas à fila
- `fimExibicao()`: sinaliza que a exibição da senha terminou

**Exemplo:**
```tsx
const { senhaExibicao, adicionarSenhas, fimExibicao } = useFilaExibicaoSenha()

useEffect(() => {
  if (senhaExibicao) {
    // Exibir modal/alerta
    // Ao fechar: fimExibicao()
  }
}, [senhaExibicao])
```

---

## 📝 Tipos Exportados

- **`Senha`**: representa uma senha de pedido
  ```ts
  interface Senha {
    loja?: string
    senha: string
    status: 'preparando' | 'pronto'
  }
  ```
- **`PlataError`**: erro padrão da API
  ```ts
  interface PlataError {
    errorID: string
    msg: string
  }
  ```
- **`PlataResult<T>`**: resultado de API (T ou erro)
  ```ts
  type PlataResult<T> = T | PlataError
  ```
- **`ServerEvent`**: evento recebido do servidor
  ```ts
  interface ServerEvent {
    request: string
    senhas?: Senha[]
    userHash?: string
    erro?: PlataError
  }
  ```

---

## 💡 Exemplo de Integração Completa

```tsx
import { usePedidoEventos, useFilaExibicaoSenha } from 'pwi-kdsmobile-hooks'

const { senhaExibicao, adicionarSenhas, fimExibicao } = useFilaExibicaoSenha()
const pedidoEventos = usePedidoEventos({
  eventSourceUrl: 'https://api.exemplo.com',
  token: 'TOKEN_DO_PEDIDO',
  onSenhasParaExibir: adicionarSenhas,
  onError: (err) => alert(err.msg),
})

useEffect(() => {
  pedidoEventos.iniciar('sse')
}, [])

useEffect(() => {
  if (senhaExibicao) {
    // Exibir modal/alerta
    // Ao fechar: fimExibicao()
  }
}, [senhaExibicao])
```