@offscript/sdk 0.0.0-stage → 0.1.0

package/dist/utils/misc.d.ts

@@ -0,0 +1,20 @@
+export declare const now: () => number;
+export declare function safe<T>(fn: () => T, fallback?: T): T | undefined;
+export declare function throttle<A extends unknown[]>(fn: (...a: A) => void, ms: number): ((...a: A) => void) & {
+    cancel(): void;
+};
+export declare function debounce<A extends unknown[]>(fn: (...a: A) => void, ms: number): ((...a: A) => void) & {
+    cancel(): void;
+    flush(): void;
+};
+/** Estimativa barata do tamanho serializado (bytes ≈ chars). */
+export declare function approxSize(value: unknown): number;
+export declare function deepMerge<T extends object>(base: T, patch?: Partial<T>): T;
+export type Listener = () => void;
+/** Registro de listeners com remoção em lote. */
+export declare class Disposer {
+    private fns;
+    add(fn: Listener): void;
+    listen(target: EventTarget, type: string, handler: (e: any) => void, opts?: boolean | AddEventListenerOptions): void;
+    dispose(): void;
+}

package/docs/api-contract.md

@@ -0,0 +1,56 @@
+# Contrato da API Offscript (SDK ↔ backend)
+
+Todos os endpoints exigem `Authorization: Bearer <sessionToken>` (token de curta duração, escopo: plataforma + execução + sessão). 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`).
+
+| 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) |
+
+## 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`.

package/docs/architecture.md

@@ -0,0 +1,38 @@
+# Decisões de 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.
+
+## 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`).
+
+## 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`.
+
+## 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.

package/docs/event-contract.md

@@ -0,0 +1,26 @@
+# Contrato de eventos (schemaVersion 1.0)
+
+Envelope (`OffscriptEvent`): `id`, `kind`, `sessionId`, `executionId`, `tabId`, `pageId`, `sequence`, `timestamp`, `relatedActionId?`, `relatedActionDeltaMs?`, `data`.
+
+`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.

package/docs/playwright-contract.md

@@ -0,0 +1,39 @@
+# Playwright Data Contract (v1.0)
+
+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.
+
+```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.

package/package.json

@@ -1,6 +1,81 @@
 {
   "name": "@offscript/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Offscript SDK - grava\u00e7\u00e3o de sess\u00f5es de teste QA (rrweb, a\u00e7\u00f5es, rede, erros)",
+  "license": "UNLICENSED",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./vue": {
+      "types": "./dist/adapters/vue.d.ts",
+      "import": "./dist/adapters/vue.js",
+      "require": "./dist/adapters/vue.cjs"
+    },
+    "./nuxt": {
+      "types": "./dist/adapters/nuxt.d.ts",
+      "import": "./dist/adapters/nuxt.js",
+      "require": "./dist/adapters/nuxt.cjs"
+    },
+    "./vanilla": {
+      "types": "./dist/adapters/vanilla.d.ts",
+      "import": "./dist/adapters/vanilla.js",
+      "require": "./dist/adapters/vanilla.cjs"
+    },
+    "./playwright": {
+      "types": "./dist/playwright/index.d.ts",
+      "import": "./dist/playwright.js",
+      "require": "./dist/playwright.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build",
+    "test:e2e": "node e2e/build.mjs && playwright test",
+    "verify": "npm run typecheck && npm test && npm run build && npm run test:e2e"
+  },
+  "dependencies": {
+    "rrweb": "^2.0.0-alpha.18"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.64.1",
+    "@types/node": "^26.6.5",
+    "esbuild": "^0.28.2",
+    "fake-indexeddb": "^6.2.6",
+    "jsdom": "^30.1.3",
+    "tsup": "^9.0.0",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soffact/offscript-sdk.git",
+    "directory": "packages/offscript-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/soffact/offscript-sdk/issues"
+  },
+  "homepage": "https://github.com/soffact/offscript-sdk#readme"
 }