@bravophone/webphone 0.2.1 → 0.4.0

package/README.md

@@ -1,21 +1,48 @@
 # @bravophone/webphone
 
-Webphone BRAVOPHONE embutível em qualquer página web. Uma linha de `<script>` e o
-softphone aparece como uma janela flutuante arrastável, com as mesmas
-funcionalidades da extensão de navegador.
+Webphone BRAVOPHONE embutível em qualquer página web: o softphone aparece como
+uma janela flutuante arrastável, com as mesmas funcionalidades da extensão de
+navegador.
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@bravophone/webphone@0.1"></script>
 <script>
-  Bravophone.init({ token: 'TOKEN_DO_USUARIO' })
+// Resolve a versão publicada e carrega o bundle dela.
+// Duas etapas de propósito: a consulta tem 5 min de cache, o bundle é
+// immutable. Assim as correções chegam em minutos, sem revalidar 30 kB a cada
+// visita — e sem os 7 dias de cache que a URL sem versão carrega.
+// cache:'no-store' na CONSULTA (~1 kB): sem ele, a resposta fica até 5 min
+// no navegador e uma publicação recém-saída não aparece — foi o que exigiu
+// Ctrl+Shift+R nos testes. O bundle continua vindo de cache immutable, então
+// o custo é uma requisição pequena por carregamento, não 30 kB.
+fetch('https://data.jsdelivr.com/v1/packages/npm/@bravophone/webphone/resolved',
+      { cache: 'no-store' })
+  .then((r) => r.json())
+  .then(({ version }) => {
+    const s = document.createElement('script')
+    s.src = `https://cdn.jsdelivr.net/npm/@bravophone/webphone@${version}/dist/bravophone.umd.js`
+    s.onload = () => Bravophone.init({ session: SESSAO_DO_LOGIN })
+    s.onerror = () => console.error('Bravophone: falha ao carregar do CDN')
+    document.head.appendChild(s)
+  })
 </script>
 ```
 
+Cole **inline**, não como arquivo externo — um arquivo externo teria o mesmo
+problema de cache que este trecho existe para evitar.
+Detalhes em [Manter o cliente sempre atualizado](#manter-o-cliente-sempre-atualizado).
+
+Para travar numa versão (integração de terceiros, ou build com SRI):
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@bravophone/webphone@0.3.0/dist/bravophone.umd.js"></script>
+<script>Bravophone.init({ token: TOKEN_DO_USUARIO })</script>
+```
+
 ```js
 // ou via npm
 import Bravophone from '@bravophone/webphone'
 
-Bravophone.init({ token, position: 'bottom-right' })
+Bravophone.init({ token })
 Bravophone.on('call:incoming', ({ number }) => console.log('ligação de', number))
 await Bravophone.call('11987654321')
 ```
@@ -55,9 +82,9 @@ todas — é o [`host/shim/chrome-shim.js`](host/shim/chrome-shim.js).
 │   │  Shadow DOM · janela arrastável    │                    │
 │   │  API pública · ponte postMessage   │                    │
 │   │                                    │                    │
-│   │   ┌─ <iframe> ──────────────────┐  │                    │
-│   │   │  origem FIXA:               │  │                    │
-│   │   │  webphone.bravophone.com    │  │                    │
+│   │   ┌─ <iframe srcdoc> ───────────┐  │                    │
+│   │   │  origem: a do próprio site  │  │                    │
+│   │   │  arquivos: CDN (jsDelivr)   │  │                    │
 │   │   │                             │  │                    │
 │   │   │  chrome-shim.js             │  │                    │
 │   │   │  libwebphone.js   (604 KB)  │  │                    │
@@ -78,7 +105,7 @@ Testei mentalmente as duas rotas; o iframe ganha em quatro frentes de uma vez:
 1. **CSS.** O bundle traz Tailwind + `dark-theme.css` globais. Injetado na página do
    cliente, ele quebraria o site do cliente — e o CSS do cliente quebraria o webphone.
 2. **CORS, e este é o argumento decisivo.** Dentro do iframe, todo request para
-   `api.bravophone.com`, `reports.teambravotech.com` e `devices.wavoip.com` sai com
+   `pabx.teambravotech.com` e `devices.wavoip.com` sai com
    `Origin: https://webphone.bravophone.com` — **uma origem só, fixa**. Sem iframe,
    cada cliente novo exigiria liberar mais uma origem no CORS de três backends. Com
    iframe, a lista de origens do backend nunca cresce.
@@ -255,6 +282,7 @@ carrega (o mock em `?host=mock` continua funcionando).
 | `npm start` | Sobe as duas origens locais (5173 site, 5174 host) |
 | `npm test` | 100 asserções: shim, geometria da janela e aba de abertura |
 | `npm run audit:theme` | Procura texto invisível no tema escuro |
+| `npm run purge` | Limpa o cache do CDN nas URLs sem versão fixa (roda sozinho após o publish) |
 
 Abra **http://localhost:5173/**.
 
@@ -308,7 +336,7 @@ sync, ou versione por query string); `index.html` sempre com `no-cache`.
 
 ### 2. Backends — CORS
 
-Liberar **uma única origem** em `api.bravophone.com`, `reports.teambravotech.com` e
+Liberar **uma única origem** em `api.bravophone.com`, `pabx.teambravotech.com` e
 `devices.wavoip.com`:
 
 ```
@@ -330,6 +358,89 @@ um major não quebre a página deles.
 
 ---
 
+## Manter o cliente sempre atualizado
+
+A intuição diz para usar a URL sem versão. **É a pior escolha para isso**, e os
+headers do CDN mostram por quê:
+
+```
+sem versão / @0.2   →  max-age=604800   (7 dias no navegador do usuário)
+@0.2.1 exata        →  immutable        (eterno, mas fixo)
+```
+
+A URL sem versão é entregue com sete dias de cache **na máquina de quem
+acessa**. Publicar uma correção não alcança essa pessoa: `npm run purge` limpa
+as bordas do CDN, não o cache que já está no navegador dela.
+
+O caminho que resolve é [`examples/loader-latest.js`](examples/loader-latest.js),
+que separa as duas coisas:
+
+1. pergunta ao CDN qual é a versão atual — resposta com **5 min** de cache;
+2. carrega o bundle daquela versão **exata** — URL imutável, cache eterno.
+
+Uma publicação chega em até cinco minutos, e o arquivo pesado vem de um cache
+que nunca precisa ser revalidado. O custo é uma requisição de ~1 kB antes do
+bundle, quase sempre servida do cache.
+
+```js
+const { version } = await (await fetch(
+  'https://data.jsdelivr.com/v1/packages/npm/@bravophone/webphone/resolved'
+)).json()
+
+const s = document.createElement('script')
+s.src = `https://cdn.jsdelivr.net/npm/@bravophone/webphone@${version}/dist/bravophone.umd.js`
+document.head.appendChild(s)
+```
+
+Cole isso **inline** na página, não como arquivo externo — um arquivo externo
+teria o mesmo problema de cache que estamos evitando.
+
+### Se uma publicação não aparecer
+
+Três caches diferentes, do mais provável ao menos:
+
+| O que está velho | Como saber | Solução |
+|---|---|---|
+| **A consulta de versão** | `Bravophone.version` mostra a anterior | Já resolvido: o snippet usa `cache: 'no-store'` |
+| **A página do integrador** | o próprio snippet mudou e não teve efeito | Não sirva o HTML com `max-age` longo |
+| **O bundle** | — | Não acontece: a URL é versionada e `immutable` |
+
+Durante o desenvolvimento, `Ctrl+Shift+R` limpa os três de uma vez — foi o que
+funcionou nos primeiros testes. Em produção não há como pedir isso ao usuário,
+e é por isso que o `no-store` está na consulta: sem ele, quem carregou a página
+nos últimos cinco minutos continua na versão anterior.
+
+Se ainda assim algo ficar para trás, `npm run purge` limpa as bordas do CDN —
+mas lembre que ele não alcança o navegador de ninguém.
+
+Os assets do webphone acompanham automaticamente: o `public_path` é gravado com
+a versão do pacote, então carregar o SDK 0.2.1 carrega o host 0.2.1.
+
+## A sessão que o webphone espera
+
+`init()` recebe a resposta do `/api/voxfree/login` inteira:
+
+```js
+Bravophone.init({
+  session: {
+    vxToken:    '…',   // obrigatório
+    expiresIn:  3600,  // segundos
+    sip:        '…',   // sem isto o webphone não registra
+    ramal:      '…',   // idem
+    tenant:     '…',
+    clienteId:  '…',
+    ramaisUrl:  '…',
+  },
+})
+```
+
+O SDK grava essas chaves onde o bundle as procura, **antes** dele avaliar — a
+sessão já sobe autenticada, sem piscar a tela de login.
+
+`token: '…'` continua aceito como atalho para `{ vxToken }`, mas **sozinho não
+basta**: o webphone carrega, não registra, e o RouteSelector avisa "faça login
+pelo webphone" — justamente o que a auto-autenticação existe para evitar.
+
 ## Documentação
 
 | Documento | Para quem |
@@ -346,7 +457,7 @@ um major não quebre a página deles.
 | Opção | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `token` | `string` | — | Token de sessão emitido pelo seu backend |
-| `mode` | `'hosted' \| 'srcdoc'` | `'hosted'` | Como o webphone é carregado — ver abaixo |
+| `mode` | `'srcdoc' \| 'hosted'` | `'srcdoc'` | Como o webphone é carregado — ver abaixo |
 | `hostUrl` | `string` | `https://webphone.bravophone.com/` | Origem do webphone (só no modo `hosted`) |
 | `position` | `string` | `'bottom-right'` | Canto inicial |
 | `open` | `boolean` | `false` | Abrir já visível |
@@ -385,7 +496,7 @@ Bravophone.init({ token })                     // hospedado (padrão)
 Bravophone.init({ token, mode: 'srcdoc' })     // na origem do próprio site
 ```
 
-| | `hosted` (padrão) | `srcdoc` |
+| | `srcdoc` (padrão) | `hosted` |
 |---|---|---|
 | Onde o iframe roda | `webphone.bravophone.com` | origem do próprio site |
 | De onde vêm os arquivos | do host | do CDN, travados nesta versão |
@@ -395,7 +506,7 @@ Bravophone.init({ token, mode: 'srcdoc' })     // na origem do próprio site
 | Você precisa manter | o domínio do host | nada |
 
 **Antes de oferecer o `srcdoc` a um cliente, a origem dele precisa estar na
-allowlist de CORS de `api.bravophone.com`, `reports.teambravotech.com` e
+allowlist de CORS de `api.bravophone.com`, `pabx.teambravotech.com` e
 `devices.wavoip.com`.** Sem isso o webphone carrega, aparece na tela e não
 registra — o navegador descarta as respostas. Isso é trabalho no **nosso**
 backend: o integrador não tem como liberar CORS de um servidor que não é dele.