@offscript/sdk 0.1.2 → 0.1.5

package/dist/utils/errors.d.ts

@@ -1,4 +1,4 @@
-export type OffscriptErrorCode = "CONFIG_INVALID" | "AUTH_FAILED" | "SESSION_EXPIRED" | "SESSION_DISABLED" | "INVALID_STATE" | "TRANSPORT_FAILED" | "PAYLOAD_TOO_LARGE" | "NOT_SUPPORTED" | "INTERNAL";
+export type OffscriptErrorCode = "CONFIG_INVALID" | "INVALID_STATE" | "TRANSPORT_FAILED" | "PAYLOAD_TOO_LARGE" | "NOT_SUPPORTED" | "INTERNAL";
 export declare class OffscriptError extends Error {
     readonly code: OffscriptErrorCode;
     readonly status?: number;
@@ -11,26 +11,9 @@ export declare class OffscriptError extends Error {
 export declare class ConfigError extends OffscriptError {
     constructor(message: string);
 }
-export declare class AuthError extends OffscriptError {
-    constructor(message: string, status?: number);
-}
-export declare class SessionExpiredError extends OffscriptError {
-    constructor(message?: string);
-}
-export declare class SessionDisabledError extends OffscriptError {
-    constructor(message?: string);
-}
 export declare class InvalidStateError extends OffscriptError {
     constructor(message: string);
 }
-export declare class TransportError extends OffscriptError {
-    readonly retryable: boolean;
-    constructor(message: string, opts: {
-        status?: number;
-        retryable: boolean;
-        cause?: unknown;
-    });
-}
 /** Emissor tipado mínimo. */
 export declare class Emitter<M extends Record<string, unknown>> {
     private handlers;

package/docs/api-contract.md

@@ -1,56 +1,7 @@
-# Contrato da API Offscript (SDK ↔ backend)
+# Envio final
 
-Todos os endpoints exigem `Authorization: Bearer <sessionToken>` (token de curta duração, escopo: plataforma + execução + sessão). A aplicação pode entregar esse token ao SDK em `?offscript_token=` na URL inicial; o SDK o captura, remove o parâmetro da barra de endereço e o reutiliza em todas as chamadas, inclusive `/complete`. Respostas em JSON. CORS: o backend deve permitir os headers `Authorization, Content-Type, Content-Encoding, Idempotency-Key, X-Offscript-Sdk` (um `*` **não** cobre `Authorization`).
+O SDK grava localmente. `complete({ endpoint, token })` encerra a captura e faz um POST ao endpoint informado pelo host, com JSON e `Authorization: Bearer <token>`.
 
-| Método | Caminho | Finalidade |
-|---|---|---|
-| POST | `/sdk/sessions` | Cria (ou obtém, idempotente por `executionId`) a sessão |
-| POST | `/sdk/sessions/{id}/events` | Recebe um lote de eventos |
-| POST | `/sdk/sessions/{id}/heartbeat` | Mantém a sessão viva; informa desativação remota |
-| POST | `/sdk/sessions/{id}/complete` | Encerra a sessão |
-| GET | `/sdk/sessions/{id}/status` | Estado da sessão (usado ao retomar após reload) |
+Campos: `recording` é a lista de envelopes não HTTP, incluindo rrweb; `request` contém envelopes HTTP; `regression` descreve condições iniciais e passos Playwright. IDs do domínio não são enviados. A autorização e a associação do token pertencem ao destinatário.
 
-## POST /sdk/sessions
-Request: `{ platformId, testCaseId, executionId, tabId, sdkVersion, appVersion?, context }`
-
-Response `200`:
-```json
-{ "sessionId": "ses_1", "recording": { "enabled": true, "reason": null },
-  "expiresAt": 1790000000000, "heartbeatIntervalMs": 30000,
-  "sessionToken": "(opcional) token renovado",
-  "limits": { "maxBatchBytes": 524288, "maxBatchEvents": 200 } }
-```
-Se `recording.enabled = false` o SDK **não grava** e lança `SessionDisabledError`.
-O backend deve validar que a plataforma, o caso de teste e a execução pertencem ao escopo do token.
-
-## POST /sdk/sessions/{id}/events
-Headers: `Idempotency-Key: <batchId>`; opcionalmente `Content-Encoding: gzip` (se `transport.compress`).
-
-Body (`EventBatch`):
-```json
-{ "schemaVersion": "1.0", "batchId": "ses_1.tab_x.1-200.200", "sessionId": "ses_1",
-  "executionId": "exec", "tabId": "tab_x", "sequenceStart": 1, "sequenceEnd": 200,
-  "createdAt": 1790000000000, "sdkVersion": "0.1.0", "events": [ /* OffscriptEvent */ ] }
-```
-Response `200`: `{ "batchId": "...", "accepted": 200, "duplicate": false, "persistedThrough": 200 }`
-
-Requisitos do backend:
-- **Idempotência**: deduplicar por `event.id` (e/ou `batchId`). Reenvios devem responder `200` com `duplicate: true`. O SDK reenvia lotes que não recebeu ACK, inclusive após reload e após o envio `keepalive` do encerramento da página.
-- **Ordenação lógica**: chunk por `(sessionId, tabId, sequenceStart)`; a ordem canônica é `(tabId, sequence)`; eventos podem chegar fora de ordem.
-- Armazenar em múltiplos chunks (um registro por lote), nunca um JSON único por sessão.
-- Códigos: `401/403` → `AuthError` (SDK para e vai para `error`); `410` → `SessionExpiredError`; `413` → o SDK divide o lote e reenvia; `408/429/5xx` e falhas de rede → retry com backoff exponencial + jitter (respeita `Retry-After`); outros `4xx` não são reenviados.
-- Rate limiting e validação de payload (`schemaVersion`, tamanhos, sequências) são responsabilidade do backend.
-
-## POST /sdk/sessions/{id}/heartbeat
-Request: `{ tabId, pageId, status, pending, lastSequence }` → Response: `{ "status": "active" | "disabled" | "expired", "sessionToken"?, "expiresAt"? }`.
-`disabled` = desativação remota: o SDK faz flush de melhor esforço, para e emite `disabled`. `expired` → `SessionExpiredError`.
-
-## POST /sdk/sessions/{id}/complete
-Request: `{ tabId, lastSequence, eventCount, pages }` → Response: `{ "completed": true }`.
-
-## GET /sdk/sessions/{id}/status
-Response: `{ "status": "active" | "disabled" | "expired", "sessionToken"?, "expiresAt"? }`.
-
-## Retenção / LGPD
-- Local: eventos não confirmados ficam no IndexedDB até o ACK ou até `privacy.localRetentionMs` (24 h por padrão); ao encerrar com sucesso o buffer da sessão é apagado.
-- Servidor: a política de retenção, base legal e direito de exclusão são do backend; o SDK só envia dados já sanitizados e permite desativação remota via `recording.enabled`/`heartbeat`.
+Não existem requisições antes da finalização. Falhas HTTP rejeitam a promise e preservam o payload. Uma nova tentativa depende de outra chamada explícita. Após sucesso, a mesma instância retorna a resposta sem repetir o POST. Respostas de sucesso podem conter JSON, texto ou corpo vazio. A confirmação do HTTP de sucesso impede reenvio, independentemente do formato da resposta. Para destinos de outra origem, o servidor deve aceitar o preflight CORS para POST, Authorization e Content-Type.

package/docs/architecture.md

@@ -1,38 +1,9 @@
-# Decisões de arquitetura
+# Arquitetura
 
-## Contexto do repositório
-O repositório `soffact/offscript-sdk` estava **vazio** (nenhum painel, backend, tabela, endpoint ou player). Portanto:
-- o SDK foi criado como pacote independente (`packages/offscript-sdk`), sem acoplamento a framework;
-- não existe backend a reutilizar: os contratos HTTP estão em [api-contract.md](./api-contract.md) e há um **servidor de referência** (`tests/helpers/referenceServer.ts`) que implementa esse contrato para testar o cliente de ponta a ponta. Ele **não** substitui o backend real da Offscript, que precisa implementar o mesmo contrato.
+`Offscript` coordena o ciclo de captura e mantém envelopes em memória. Os recorders capturam rrweb, ações, HTTP, console/erros, contexto e iframes por meio de `EventSink`. `DataSanitizer` aplica as opções de privacidade. `LifecycleManager` observa navegação SPA e mudanças de visibilidade sem enviar dados.
 
-## Dois fluxos independentes
-```
-Session Manager + autorização
- ├─ Visual Recorder   (rrweb: DOM, snapshots, mutações) → replay histórico
- ├─ Semantic Recorder (ações + seletores + contexto)    → Playwright futuro
- ├─ Observability     (HTTP, console, erros, iframes)
- └─ Event Transport → API Offscript (lotes idempotentes, IndexedDB, retry)
-```
-- `RRWebRecorder` nunca produz ações; `ActionRecorder` nunca lê eventos rrweb. Ambos só falam com o núcleo via `EventSink.emit(kind, data)`.
-- Eventos brutos (`action`) ≠ passos normalizados (`ActionNormalizer`) ≠ contrato Playwright (`PlaywrightDataContract`). A normalização é função pura e roda fora do caminho de captura (no navegador via `exportPlaywrightData()` ou no backend com `buildPlaywrightContract`).
+Ao finalizar, todos os recorders são parados. O núcleo monta o payload e o contrato Playwright. O host fornece destino e token a `complete`. O overlay usa `startRecording`, pausa/retomada, descarte e o callback `onComplete` do host. `stopRecording` permite obter o payload sem rede.
 
-## Envelope e ordenação
-Todo evento tem `(sessionId, tabId, sequence, timestamp, pageId)`. A sequência é monotônica **por aba**, persistida em `sessionStorage` a cada evento, e continua entre páginas (MPA). O `id` do evento é `${tabId}:${sequence}` — determinístico, o que torna reenvios idempotentes. Entre abas a ordenação é por `timestamp`.
+A persistência local é opcional, habilitada por `persistenceKey` fornecida pelo host. `RecordingStore` guarda status e eventos incrementalmente no IndexedDB. Ao sair do documento, um checkpoint síncrono no sessionStorage preserva a cauda ainda não confirmada. Na próxima página, o SDK recupera esse checkpoint, restaura os dados e retoma o estado anterior com um novo identificador de página e snapshot rrweb. Não há comunicação com backend durante essa continuidade.
 
-## Política multi-aba
-Cada aba grava de forma independente na **mesma sessão/execução**, com `tabId` e sequência próprios. O estado da sessão fica em `sessionStorage` (escopo de aba). Abas abertas por `window.open` herdam uma cópia do `sessionStorage`; quando `navigator.locks` existe, um Web Lock por `tabId` detecta o clone e atribui um novo `tabId`.
-
-## Segurança por padrão
-- Token de sessão de **curta duração**, emitido pelo backend; o SDK nunca recebe chaves administrativas. O token vai em `Authorization: Bearer` com `credentials: "omit"`.
-- Sanitização **antes** de qualquer persistência (IndexedDB) ou envio — inclusive atributos de URL e textos dentro dos eventos rrweb.
-- Valores digitados viram `valueRef` (referência opaca com sal por aba), exceto campos na allowlist (`data-offscript-allow`). Senhas nunca.
-- Bodies HTTP desligados por padrão.
-
-## Transporte
-- Fila em memória (staging) → IndexedDB (`PersistentBuffer`, com fallback para memória) → lotes por aba.
-- Um evento só sai do buffer depois do ACK do backend (`200` com o `batchId`).
-- Backpressure por prioridade: `low` (mousemove, scroll, console) é descartado antes de `normal` e `critical` (snapshots rrweb, lifecycle). Se incrementais do rrweb forem descartados, o SDK força novo snapshot completo assim que houver folga.
-- Encerramento da página: `pagehide` → evento `page-end` + `fetch(..., {keepalive:true})` do que ainda está em staging (≤ 60 KB). **Não há ACK nesse caminho**; os eventos continuam no IndexedDB e são reenviados na próxima página (idempotente). `sendBeacon` não é usado porque não permite o header `Authorization`.
-
-## Carregamento sob demanda
-`rrweb` é carregado com `import("rrweb")` apenas quando `recording.rrweb` está ligado; o pacote tem `sideEffects: false` e entradas separadas para adaptadores e para o contrato Playwright.
+O host mantém o token separadamente na aba; o armazenamento do SDK não recebe credenciais. Sucesso no envio e descarte limpam o rascunho. `destroy` apenas fecha os recursos. Sem `persistenceKey`, o comportamento permanece em memória.

package/docs/event-contract.md

@@ -1,26 +1,5 @@
-# Contrato de eventos (schemaVersion 1.0)
+# Eventos locais
 
-Envelope (`OffscriptEvent`): `id`, `kind`, `sessionId`, `executionId`, `tabId`, `pageId`, `sequence`, `timestamp`, `relatedActionId?`, `relatedActionDeltaMs?`, `data`.
+Cada envelope possui `id`, `kind`, `tabId`, `pageId`, `sequence`, `timestamp` e `data`. A sequência é monotônica dentro da gravação. HTTP, console, erros e iframes podem conter `relatedActionId` e `relatedActionDeltaMs` para correlação temporal.
 
-`relatedActionId` liga `http`, `console`, `error` e `iframe` à ação mais recente do usuário dentro de `correlationWindowMs` (3 s por padrão). Para `http`, o `timestamp` é o **início** da requisição.
-
-| kind | `data` | Observações |
-|---|---|---|
-| `rrweb` | evento rrweb nativo (`type`: 2 snapshot, 3 incremental, 4 meta…) | URLs em atributos e textos sensíveis redigidos. Um `type 2` abre cada página. |
-| `action` | `RecordedAction` | `schemaVersion` próprio (`ACTION_SCHEMA_VERSION`), `sequence` = sequência do envelope |
-| `http` | `HttpEventData` | um evento por requisição, na conclusão |
-| `console` | `ConsoleEventData` | níveis configuráveis; argumentos serializados e sanitizados |
-| `error` | `ErrorEventData` | `window.onerror`, `unhandledrejection`, falha de recurso |
-| `context` | `ContextEventData` | `reason`: `page-load`, `viewport`, `navigation`… |
-| `iframe` | `IframeEventData` | presença/geometria/foco; **sem** conteúdo interno |
-| `lifecycle` | `LifecycleEventData` | `session-start/resume`, `page-start/end`, `pause/resume`, `stop`, `navigation`, `recorder-error` |
-
-Tipos completos: `src/types/events.ts`. Alterações compatíveis (campos opcionais novos) mantêm `1.x`; remoção/renomeação exige `2.0`.
-
-## Ações (`RecordedAction.type`)
-`click`, `dblclick`, `hover` (`payload.phase`: enter/leave), `mousemove` (trajetória amostrada; desligado por padrão), `drag`, `input`, `keydown` (somente teclas relevantes: Enter, Esc, Tab, setas, F-keys, atalhos com Ctrl/Meta/Alt), `select`, `check`, `scroll` (from/to), `navigate`, `reload`, `focus`, `blur`.
-
-Valores de `input` **não** são gravados por padrão: `payload = { valueCaptured: false, valueRef, length, fieldType }`. Em campos com `data-offscript-allow` (ou seletor em `privacy.allowedInputSelectors`): `{ valueCaptured: true, value }`. Senhas nunca.
-
-## Seletores
-`selector` é o primeiro candidato único na ordem: `testid` → `attribute` (name/data-id) → `role` (`role=button[name="Salvar"]`) → `label` → `placeholder` → `id` estável → `css` estrutural. Todos os candidatos são enviados em `selectorCandidates` com `unique`/`matches` no momento da ação. Classes geradas (CSS-in-JS, hashes) e ids dinâmicos são ignorados.
+Tipos: `rrweb`, `action`, `http`, `console`, `error`, `context`, `iframe` e `lifecycle`. A tipagem canônica está em `src/types/events.ts`. Não há IDs do domínio. Os envelopes HTTP compõem `request`; os demais compõem `recording`. O player obtém o evento rrweb de `envelope.data`.

package/docs/playwright-contract.md

@@ -1,39 +1,5 @@
-# Playwright Data Contract (v1.0)
+# Contrato Playwright
 
-O SDK **não executa Playwright**. Ele produz, a partir das ações gravadas, um documento versionado para um serviço externo converter em testes. Uma reprodução bem-sucedida **não** significa aprovação: as assertions pertencem aos casos de teste no painel.
+`buildPlaywrightContract({ actions, contexts, extensions })` produz um contrato versionado `offscript.playwright-recording`, com versão do SDK, data de geração, condições iniciais, passos, estatísticas e limitações. Não exige identidade de backend.
 
-```ts
-import { buildPlaywrightContract, validatePlaywrightContract } from "@offscript/sdk/playwright"; // sem puxar o runtime de gravação
-const contract = buildPlaywrightContract({ session, actions, contexts });   // backend ou navegador
-validatePlaywrightContract(contract); // [] = válido
-// ou, no navegador, com as ações da página atual:
-offscript.exportPlaywrightData();
-```
-
-```jsonc
-{
-  "contractVersion": "1.0", "kind": "offscript.playwright-recording",
-  "session": { "sessionId", "executionId", "testCaseId", "platformId" },
-  "initialConditions": { "url", "viewport", "userAgent", "language", "timezone", "deviceScaleFactor", "browser" },
-  "steps": [{
-    "index": 0, "type": "click|dblclick|fill|press|select|check|uncheck|hover|drag|scroll|navigate|reload",
-    "timestamp": 1790000000000, "waitBeforeMs": 420, "url": "…",
-    "selector": "role=button[name=\"Salvar\"]", "selectorUnique": true,
-    "selectorCandidates": [{ "strategy": "testid", "selector": "[data-testid=\"save\"]", "unique": true, "matches": 1 }],
-    "element": { "tag": "button", "role": "button", "name": "Salvar", "testId": "save" },
-    "args": { "value": "…" } /* ou { "valueRef", "valueCaptured": false } */,
-    "expectsNavigation": { "to": "https://app/x" },
-    "sourceActionIds": ["tab_x:12"], "causedByActionId": "…"
-  }],
-  "stats": { "rawActions": 40, "steps": 14, "merged": 26 },
-  "limitations": ["…"], "extensions": {}
-}
-```
-
-## Normalização (`ActionNormalizer`)
-`click,click,dblclick` → `dblclick` · `click` + `check` → `check/uncheck` · vários `input` no mesmo campo → um `fill` · `keydown` → `press` (`Control+s`) · scrolls consecutivos → um `scroll` · `navigate` logo após um clique/Enter → `expectsNavigation` do passo causador · `focus`, `blur`, `mousemove` e `hover` isolado são descartados (permanecem nos eventos brutos). Cada passo mantém `sourceActionIds` para rastreabilidade.
-
-## O que o motor externo deve fazer
-Resolver seletores (tentando `selectorCandidates` em ordem), pedir valores para `valueRef` (campos não autorizados não são reproduzíveis), aplicar esperas inteligentes (`waitBeforeMs` é só dica), validar assertions do caso de teste e produzir o resultado de regressão.
-
-Versionamento: `contractVersion` `MAJOR.MINOR`; `validatePlaywrightContract` recusa `MAJOR` diferente.
+`normalizeActions` consolida ações em passos. Cada passo preserva os IDs das ações de origem para correlação. `validatePlaywrightContract` valida estrutura e ordem. O SDK descreve passos; não executa Playwright nem determina aprovação do teste. A tipagem canônica está em `src/playwright/PlaywrightDataContract.ts`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@offscript/sdk",
-  "version": "0.1.2",
-  "description": "Offscript SDK - gravação de sessões de teste QA (rrweb, ações, rede, erros)",
+  "version": "0.1.5",
+  "description": "Offscript SDK - grava\u00e7\u00e3o de sess\u00f5es de teste QA (rrweb, a\u00e7\u00f5es, rede, erros)",
   "license": "MIT",
   "type": "module",
   "sideEffects": false,

package/dist/chunk-HECPMGDC.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/adapters/vanilla.ts"],"names":[],"mappings":";;;AAKA,eAAsB,gBAAgB,MAAA,EAA6C;AACjF,EAAA,MAAM,GAAA,GAAM,IAAI,SAAA,CAAU,MAAM,CAAA;AAChC,EAAA,MAAM,IAAI,IAAA,EAAK;AACf,EAAA,OAAO,GAAA;AACT;AAEA,eAAsB,cAAA,CAAe,QAAyB,KAAA,EAAkD;AAC9G,EAAA,MAAM,GAAA,GAAM,MAAM,eAAA,CAAgB,MAAM,CAAA;AACxC,EAAA,MAAM,GAAA,CAAI,eAAe,KAAK,CAAA;AAC9B,EAAA,OAAO,GAAA;AACT","file":"chunk-HECPMGDC.js","sourcesContent":["import { Offscript } from \"../core/OffscriptSDK\";\nimport type { OffscriptConfig } from \"../types/config\";\nimport type { StartRecordingOptions } from \"../types/session\";\n\n/** Atalho para aplicações JS tradicionais, Blade e MPA: inicializa e retoma sessões persistidas. */\nexport async function createOffscript(config: OffscriptConfig): Promise<Offscript> {\n  const sdk = new Offscript(config);\n  await sdk.init();\n  return sdk;\n}\n\nexport async function startOffscript(config: OffscriptConfig, start: StartRecordingOptions): Promise<Offscript> {\n  const sdk = await createOffscript(config);\n  await sdk.startRecording(start);\n  return sdk;\n}\n"]}