@offscript/sdk 0.1.2 → 0.1.6

package/README.md

@@ -1,134 +1,37 @@
 # @offscript/sdk
 
-SDK de instrumentação para aplicações web testadas manualmente por QA. Captura, de forma modular e agnóstica de framework, tudo o que é necessário para **reproduzir** a sessão (rrweb), **investigar** (ações, rede, erros, contexto) e, no futuro, **automatizar** (contrato Playwright), enviando os eventos para a API da Offscript.
-
-Funciona em JS puro, Vue 2/3, Nuxt, React, Laravel Blade e Inertia, em SPA e MPA. O núcleo não depende de nenhum framework.
-
-> Estado: `0.1.0`. Veja [Limitações conhecidas](#limitações-conhecidas) e o [relatório de testes](#testes).
-
-## Instalação
-
-```bash
-npm install @offscript/sdk
-```
-
-## Uso
+Biblioteca de captura no navegador: DOM com rrweb, ações, navegação SPA, HTTP, console, erros, contexto e iframes. O SDK lê `offscript_token` da query string, mantém o token e a gravação entre documentos da mesma origem e preserva a URL. O overlay só aparece quando há um token de execução.
 
 ```ts
 import { Offscript } from "@offscript/sdk";
 
-const offscript = new Offscript({
-  apiUrl: "https://api.offscript.example",
-  platformId: "platform-id",
-  appVersion: "1.4.2",
-  recording: { rrweb: true, actions: true, http: true, console: true, errors: true },
-  privacy: { maskSensitiveInputs: true, captureRequestBodies: false, captureResponseBodies: false },
-});
-
-await offscript.init();                       // retoma sessão persistida (reload / MPA), se houver
-await offscript.startRecording({
-  testCaseId: "test-case-id",
-  executionId: "execution-id",
-  // sessionToken: "short-lived-session-token", // opcional: pode vir de ?offscript_token=
+const sdk = new Offscript({
+  endpoint: "https://painel.example/api/recordings",
+  recording: { rrweb: true, actions: true, http: true, errors: true, iframes: true },
 });
-await offscript.pauseRecording();             // retomar gera um novo snapshot completo
-await offscript.resumeRecording();
-const summary = await offscript.stopRecording(); // { flushed, pendingEvents, completed }
-await offscript.destroy();
+await sdk.init();
+await sdk.startRecording();
+const result = await sdk.complete();
 ```
 
-Todos os métodos são **idempotentes** (`init`, `startRecording` com a mesma execução, `stopRecording`, `pause/resume`, `destroy`). Chamadas concorrentes de `startRecording` compartilham a mesma promise; iniciar outra execução com uma ativa lança `InvalidStateError`.
+`complete()` para os recorders e faz um único POST JSON com `Authorization: Bearer <token>`. O host configura o endpoint; o SDK obtém o token da URL ou da sessão da aba. Também e possível passar `endpoint` e `token` explícitamente a `complete` para integrações personalizadas.
 
-### Estados e eventos
-`idle → initializing → recording ⇄ paused → stopping → stopped` (e `error`). `offscript.getState()` devolve `{ status, session, pending, lastError }`.
+O payload contém `recording` (envelopes rrweb, ações, console, erros, contexto, iframes e ciclo de vida), `request` (envelopes HTTP) e `regression` (contrato Playwright com condições iniciais e passos). Não ha transporte durante a captura nem reenvio automático. Chamadas concorrentes de `complete` compartilham o envio; após sucesso, chamadas repetidas retornam o resultado. Após falha, os dados continuam disponíveis para uma nova chamada explícita.
 
-```ts
-offscript.on("statusChange", ({ from, to }) => …);
-offscript.on("error", (e) => …);       // OffscriptError tipado (e.code)
-offscript.on("sessionStart" | "sessionEnd" | "flush" | "overflow" | "disabled", …);
-```
-Erros tipados: `ConfigError`, `AuthError`, `SessionExpiredError`, `SessionDisabledError`, `InvalidStateError`, `TransportError` (todos estendem `OffscriptError` com `code`).
-
-### Autorização
-A gravação só começa depois que `POST /sdk/sessions` autoriza o token e responde `recording.enabled: true`. O token pode ser informado em `startRecording` ou lido automaticamente de `offscript_token` na query string. Depois de capturado, esse parâmetro é removido da barra de endereço; o token é guardado só em `sessionStorage` (escopo da aba) e usado em `Authorization: Bearer` em todas as chamadas, inclusive na finalização. Renovações chegam em `sessionToken` nas respostas. O backend pode desativar remotamente via heartbeat.
-
-## Configuração
+`stopRecording()` encerra localmente e devolve o payload sem publicar. `pauseRecording()` e `resumeRecording()` controlam a captura; retomar gera um snapshot completo. `discardRecording()` limpa os dados e volta ao estado inicial. `destroy()` libera a instrumentação sem enviar dados.
 
-| Opção | Padrão | Descrição |
-|---|---|---|
-| `apiUrl` | — | HTTPS obrigatório (HTTP só em localhost) |
-| `platformId` | — | Plataforma do SDK |
-| `appVersion` | — | Versão/build da app, enviada no contexto |
-| `autoResume` | `true` | Retoma sessão persistida em `init()` |
-| `correlationWindowMs` | `3000` | Janela para ligar http/erros à ação anterior |
-| `heartbeatIntervalMs` | `30000` | Usado se o backend não informar |
-| `recording.rrweb/actions/http/console/errors/context/iframes` | `true` | Liga cada módulo |
-| `recording.mouseMove` | `false` | Trajetória do mouse nas *ações* (rrweb já grava o movimento) |
-| `recording.consoleLevels` | todos | `log`, `info`, `warn`, `error` |
-| `recording.throttleMs` | `100` | Amostragem de mousemove |
-| `recording.rrwebCheckoutEveryMs` | `300000` | Snapshot completo periódico (0 desliga) |
-| `recording.rrwebRecordCanvas` | `false` | Canvas (custoso) |
-| `recording.testIdAttributes` | `data-testid, data-test, data-cy, data-qa` | Atributos de teste para seletores |
-| `recording.stableAttributes` | `name, data-id, aria-label` | Atributos estáveis extras |
-| `privacy.maskSensitiveInputs` | `false` | Máscara de inputs no replay |
-| `privacy.maskAllText` | `false` | Máscara de todo texto no replay |
-| `privacy.captureRequestBodies / captureResponseBodies` | `false` | Bodies HTTP |
-| `privacy.allowedInputSelectors` | `[data-offscript-allow]` | Campos cujo valor pode ser gravado |
-| `privacy.blockSelectors / maskTextSelectors / ignoreSelectors` | `[data-offscript-block]`… | Bloquear, mascarar texto, ignorar ações |
-| `privacy.ignoreUrls` | `[]` | Requisições não capturadas (string ou RegExp) |
-| `privacy.redactHeaders / redactKeys` | `[]` | Extras além do padrão |
-| `privacy.maxBodyBytes` | `16384` | Limite de body capturado |
-| `privacy.localRetentionMs` | `86400000` | Retenção local de eventos não enviados |
-| `transport.*` | ver `DEFAULT_TRANSPORT` | lote, flush, memória, retries, `compress` (gzip; requer suporte no backend), `persist` (IndexedDB) |
+Com `controls` habilitado (padrão), o overlay aparece em `init()` somente quando existe um token de execução na URL ou na sessão da aba. Iniciar grava localmente; Finalizar envia a gravação ao endpoint configurado usando o token do SDK. `onComplete` continua disponível para integrações que precisem substituir esse comportamento.
 
-### Privacidade (padrão seguro)
-Senhas, tokens, `Authorization`, cookies, chaves de API, JWT, CPF/CNPJ e cartões (Luhn) são redigidos **antes** de persistir ou enviar — em headers, query, bodies, console, erros, URLs/atributos/textos do rrweb. Valores digitados não vão para as ações (viram `valueRef`) a não ser em campos com `data-offscript-allow`. Use `data-offscript-block` / `.offscript-block` para remover um elemento do replay e `data-offscript-ignore` para ignorar suas ações. Isso ajuda a atender a LGPD, mas **não a substitui**: a base legal, o aviso aos testadores, a retenção e a exclusão no servidor são responsabilidade da Offscript/cliente.
+As opções `recording` e `privacy` estão tipadas em `src/types/config.ts`. `captureSensitiveValues` vem desabilitada; habilitá-la inclui valores sensíveis na captura. Configure máscaras, seletores bloqueados e URLs ignoradas conforme a aplicação.
 
-## Adaptadores
-`@offscript/sdk/vue` (Vue 2/3, sem importar Vue), `@offscript/sdk/nuxt` (client-only), `@offscript/sdk/vanilla` (`createOffscript`, `startOffscript`). Exemplos em [examples/](./examples).
+Adaptadores disponíveis: `@offscript/sdk/vanilla`, `/vue` e `/nuxt`. O módulo `/playwright` exporta geração e validação do contrato; não executa o navegador. Iframes de outra origem fornecem apenas metadados de presença, foco e dimensões.
 
-## Playwright
-`offscript.exportPlaywrightData()` ou `buildPlaywrightContract()` (de `@offscript/sdk/playwright`) — ver [docs/playwright-contract.md](./docs/playwright-contract.md). O SDK não executa Playwright.
+Validação: `npm run typecheck`, `npm test`, `npm run build`, `npm run test:e2e` no pacote. Os testes de navegador exigem Chromium e suas bibliotecas de sistema.
 
-## Documentação
-- [Arquitetura e decisões](./docs/architecture.md)
-- [Contrato da API](./docs/api-contract.md) — **o backend da Offscript precisa implementá-lo; este repositório só traz um servidor de referência de testes**
-- [Contrato de eventos](./docs/event-contract.md)
-- [Contrato Playwright](./docs/playwright-contract.md)
+## Continuidade entre páginas
 
-## Limitações conhecidas
-- **Iframes cross-origin (ex.: seats.io)**: nem o SDK nem o rrweb acessam o conteúdo interno. São registrados presença (`origin` + `path`, sem query), dimensões, posição, foco (quando observável) e interações visíveis na página principal. Caminhos futuros: instrumentação/eventos públicos do seats.io, ou captura complementar via Playwright em ambiente de teste autorizado — **não implementados**.
-- **HTTP**: só `fetch` e `XMLHttpRequest` da página principal. Não captura WebSocket, requisições de iframes cross-origin, Service Workers, cookies HttpOnly, headers protegidos, nem `fetch` chamado antes do SDK iniciar. `duration` do fetch é até os headers. Bodies de streaming/binário são omitidos. Bodies de request do tipo `Request`/stream não são lidos.
-- **Console**: o stack aponta para o wrapper; arquivo/linha de `console.*` não é o da chamada original no DevTools.
-- **Entrega ao fechar a aba**: usa `fetch keepalive` (≤ 60 KB) sem ACK; o que não chegar é reenviado na próxima página da mesma aba. Se o navegador for encerrado abruptamente (crash, fechamento da última aba), **não há garantia de entrega** — eventos pendentes ficam no IndexedDB até a próxima sessão da aba/origem ou expirarem.
-- **Multi-aba**: gravação por aba (cada uma com `tabId` e sequência próprios). A detecção de aba clonada exige `navigator.locks`.
-- **Replay**: só reproduz o DOM gravado (iframe sandbox sem scripts). Canvas é opcional e custoso; vídeo/áudio e Shadow DOM fechado seguem as limitações do rrweb. `mousemove` sofre amostragem.
-- **Backpressure**: com a fila cheia, eventos de baixa prioridade são descartados (`overflow`) e o SDK força novo snapshot rrweb.
-- O `exportPlaywrightData()` do navegador cobre as ações da página atual (memória, até 5000); para a sessão inteira use `buildPlaywrightContract` com os eventos armazenados no backend.
-- **Não verificado**: execução em aplicações Vue/Nuxt/Laravel/Inertia reais, navegadores além do Chromium, Safari/iOS (limites de `keepalive`/IndexedDB), carga em páginas muito grandes (só há métricas internas `getMetrics()`, sem benchmark).
-
-## Desenvolvimento
-
-```bash
-npm install
-npm run typecheck
-npm test            # 69 testes (vitest + jsdom + servidor HTTP de referência real)
-npm run test:e2e    # Playwright em Chromium real (npx playwright install chromium)
-npm run build       # tsup (ESM+CJS) + tsc (declarações)
-```
+Em sessões iniciadas com token, o SDK cria e mantém automaticamente uma chave opaca de rascunho em `sessionStorage`. Com ela, `init()` restaura o rascunho e retoma a captura quando ela estava ativa, preserva a pausa ou disponibiliza a gravação encerrada para envio. `persistenceKey` continua opcional para integrações que queiram controlar essa chave.
 
-### Testes
-| Suite | Cobertura |
-|---|---|
-| `tests/session` | init, token inválido, desativação remota, idempotência, pausa/retomada, reload, sessão expirada, heartbeat, 401 no envio |
-| `tests/transport` | lotes ordenados, ACK, falha 5xx + backoff, persistência/recuperação, idempotência, 413, backpressure, flush final, offline/online, gzip |
-| `tests/rrweb` | snapshot, mutações, máscara de inputs, redação de URLs, pausa+snapshot, **replay** com `Replayer` |
-| `tests/actions` | click, input, select, checkbox, teclado, scroll, hover, drag, SPA, seletores |
-| `tests/http` | fetch ok/erro/abort/concorrente/grande/binário, XHR, sanitização, exclusão da própria API, correlação, remoção segura |
-| `tests/observability` | console, recursão, erros globais, correlação, contexto, iframe seats.io |
-| `tests/playwright` | normalização, contrato, validação, SelectorGenerator |
-| `tests/compat` | MPA com reload, SPA/Inertia, multi-aba, adaptadores Vue/Nuxt/vanilla, falha de recorder, destroy |
-| `e2e/mpa.spec.ts` | **Chromium real**: gravação com navegação MPA + reload + SPA, privacidade, correlação, contrato, replay completo no player rrweb |
+Os eventos ficam no IndexedDB da origem. No descarregamento do documento, os últimos eventos ainda não confirmados são guardados em `sessionStorage` para a próxima pagina. `complete()` limpa o rascunho após HTTP de sucesso; `discardRecording()` também o remove. `destroy()` fecha o armazenamento e libera a instrumentação, preservando o rascunho local.
 
-### Publicação
-Versionamento semântico (`MAJOR.MINOR.PATCH`); mudanças incompatíveis nos contratos de evento/Playwright incrementam o `schemaVersion`/`contractVersion` major. Fluxo: `npm version <patch|minor|major>` → `npm run verify` → `npm publish --access public` (o `prepublishOnly` já roda typecheck, testes e build).
+O SDK lê o token de `offscript_token`, mantém a query na URL e guarda a credencial na sessão da aba para continuar após navegações. Após envio bem-sucedido, o SDK limpa o rascunho e não reabre o overlay nessa sessão; falhas mantém os dados para nova tentativa. A continuidade exige a mesma origem e o SDK inicializado em cada documento; armazenamento de navegador não é compartilhado entre domínios ou portas diferentes.

package/dist/adapters/nuxt.cjs

@@ -1,12 +1,12 @@
 'use strict';
 
-var chunkI6JPZAQA_cjs = require('../chunk-I6JPZAQA.cjs');
-require('../chunk-KQVK5EJR.cjs');
+var chunkPCJRHW66_cjs = require('../chunk-PCJRHW66.cjs');
+require('../chunk-MZXF2LF2.cjs');
 
 // src/adapters/nuxt.ts
 function createNuxtOffscript(config) {
   if (typeof window === "undefined") return null;
-  const sdk = new chunkI6JPZAQA_cjs.Offscript(config);
+  const sdk = new chunkPCJRHW66_cjs.Offscript(config);
   void sdk.init().catch(() => void 0);
   return sdk;
 }

package/dist/adapters/nuxt.js

@@ -1,5 +1,5 @@
-import { Offscript } from '../chunk-IBEPWI7S.js';
-import '../chunk-WUFW7TEL.js';
+import { Offscript } from '../chunk-5ZBR6FI5.js';
+import '../chunk-KHKIWCLM.js';
 
 // src/adapters/nuxt.ts
 function createNuxtOffscript(config) {

package/dist/adapters/vanilla.cjs

@@ -1,18 +1,18 @@
 'use strict';
 
-var chunkTBPD2LMI_cjs = require('../chunk-TBPD2LMI.cjs');
-require('../chunk-I6JPZAQA.cjs');
-require('../chunk-KQVK5EJR.cjs');
+var chunkRAUSXUGS_cjs = require('../chunk-RAUSXUGS.cjs');
+require('../chunk-PCJRHW66.cjs');
+require('../chunk-MZXF2LF2.cjs');
 
 
 
 Object.defineProperty(exports, "createOffscript", {
   enumerable: true,
-  get: function () { return chunkTBPD2LMI_cjs.createOffscript; }
+  get: function () { return chunkRAUSXUGS_cjs.createOffscript; }
 });
 Object.defineProperty(exports, "startOffscript", {
   enumerable: true,
-  get: function () { return chunkTBPD2LMI_cjs.startOffscript; }
+  get: function () { return chunkRAUSXUGS_cjs.startOffscript; }
 });
 //# sourceMappingURL=vanilla.cjs.map
 //# sourceMappingURL=vanilla.cjs.map

package/dist/adapters/vanilla.d.ts

@@ -1,6 +1,5 @@
 import { Offscript } from "../core/OffscriptSDK";
 import type { OffscriptConfig } from "../types/config";
-import type { StartRecordingOptions } from "../types/session";
-/** Atalho para aplicações JS tradicionais, Blade e MPA: inicializa e retoma sessões persistidas. */
+/** Atalho para aplicações JS tradicionais, Blade e MPA: inicializa a captura local. */
 export declare function createOffscript(config: OffscriptConfig): Promise<Offscript>;
-export declare function startOffscript(config: OffscriptConfig, start: StartRecordingOptions): Promise<Offscript>;
+export declare function startOffscript(config: OffscriptConfig): Promise<Offscript>;

package/dist/adapters/vanilla.js

@@ -1,5 +1,5 @@
-export { createOffscript, startOffscript } from '../chunk-HECPMGDC.js';
-import '../chunk-IBEPWI7S.js';
-import '../chunk-WUFW7TEL.js';
+export { createOffscript, startOffscript } from '../chunk-R2PPPR4K.js';
+import '../chunk-5ZBR6FI5.js';
+import '../chunk-KHKIWCLM.js';
 //# sourceMappingURL=vanilla.js.map
 //# sourceMappingURL=vanilla.js.map

package/dist/adapters/vue.cjs

@@ -1,13 +1,13 @@
 'use strict';
 
-var chunkI6JPZAQA_cjs = require('../chunk-I6JPZAQA.cjs');
-require('../chunk-KQVK5EJR.cjs');
+var chunkPCJRHW66_cjs = require('../chunk-PCJRHW66.cjs');
+require('../chunk-MZXF2LF2.cjs');
 
 // src/adapters/vue.ts
 var OFFSCRIPT_KEY = "$offscript";
 var OffscriptPlugin = {
   install(app, config) {
-    const sdk = new chunkI6JPZAQA_cjs.Offscript(config);
+    const sdk = new chunkPCJRHW66_cjs.Offscript(config);
     void sdk.init().catch(() => void 0);
     if (app.config?.globalProperties) {
       app.config.globalProperties[OFFSCRIPT_KEY] = sdk;

package/dist/adapters/vue.js

@@ -1,5 +1,5 @@
-import { Offscript } from '../chunk-IBEPWI7S.js';
-import '../chunk-WUFW7TEL.js';
+import { Offscript } from '../chunk-5ZBR6FI5.js';
+import '../chunk-KHKIWCLM.js';
 
 // src/adapters/vue.ts
 var OFFSCRIPT_KEY = "$offscript";