@bravophone/webphone 0.2.0 → 0.3.0

package/README.md

@@ -1,21 +1,43 @@
 # @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.
+fetch('https://data.jsdelivr.com/v1/packages/npm/@bravophone/webphone/resolved')
+  .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({ token: TOKEN_DO_USUARIO })
+    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 +77,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)  │  │                    │
@@ -255,6 +277,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/**.
 
@@ -330,6 +353,55 @@ 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.
+
+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.
+
+## Documentação
+
+| Documento | Para quem |
+|---|---|
+| [`docs/api.html`](docs/api.html) | Referência completa da API — abra no navegador |
+| [`docs/PARA-IA.md`](docs/PARA-IA.md) | Contexto para um agente de IA implementar a integração |
+| [`examples/integracao.html`](examples/integracao.html) | Exemplo pronto para colar numa página |
+| [`examples/loader.js`](examples/loader.js) | Carregar o SDK por JavaScript (SPA, Tag Manager) |
+
 ## API
 
 ### `Bravophone.init(options)`
@@ -337,7 +409,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 |
@@ -376,7 +448,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 |
@@ -502,8 +574,12 @@ const off = Bravophone.on('call:incoming', (call) => { /* … */ })
 off()  // remove o listener
 ```
 
-`ready` · `state` · `call:incoming` · `call:answered` · `call:ended` · `call:failed` ·
-`open` · `close` · `error`. Use `'*'` para receber todos como `{ event, payload }`.
+`ready` · `state` · `call:dialing` · `call:incoming` · `call:answered` ·
+`call:ended` · `resize` · `reveal` · `open` · `close` · `error`.
+Use `'*'` para receber todos como `{ event, payload }`.
+
+Uma chamada que não completa chega como `call:ended`: o estado do bundle não
+distingue desligar de falhar.
 
 ---