@offscript/sdk 0.0.0-stage → 0.1.0

package/dist/recorders/IframeRecorder.d.ts

@@ -0,0 +1,19 @@
+import { type EventSink, type Recorder } from "./types";
+/**
+ * Detecta iframes (ex.: seats.io) e registra metadados observáveis.
+ * Nunca tenta acessar o DOM interno do iframe.
+ */
+export declare class IframeRecorder implements Recorder {
+    private readonly sink;
+    readonly name = "iframes";
+    private d;
+    private known;
+    private counter;
+    private mo?;
+    constructor(sink: EventSink);
+    start(): void;
+    private scan;
+    private add;
+    private event;
+    stop(): void;
+}

package/dist/recorders/RRWebRecorder.d.ts

@@ -0,0 +1,29 @@
+import { type EventSink, type Recorder } from "./types";
+/**
+ * Captura visual (DOM + mutações + interações) usando rrweb. Carregado sob demanda.
+ * Não produz ações semânticas: isso é responsabilidade do ActionRecorder.
+ */
+export declare class RRWebRecorder implements Recorder {
+    private readonly sink;
+    readonly name = "rrweb";
+    private stopFn?;
+    private mod?;
+    private paused;
+    private stopped;
+    needsSnapshot: boolean;
+    private snapshotsTaken;
+    constructor(sink: EventSink);
+    start(): Promise<void>;
+    private onEvent;
+    /** Sanitiza URLs em atributos e padrões sensíveis em textos ANTES de persistir/enviar. */
+    private sanitizeEvent;
+    /** Chamado pelo núcleo quando há folga novamente após descartes. */
+    recoverIfNeeded(): void;
+    takeFullSnapshot(): void;
+    addCustomEvent(tag: string, payload: unknown): void;
+    get snapshots(): number;
+    pause(): void;
+    /** Ao retomar, as mutações perdidas durante a pausa exigem um snapshot completo. */
+    resume(): void;
+    stop(): void;
+}

package/dist/recorders/types.d.ts

@@ -0,0 +1,25 @@
+import type { Priority, ResolvedConfig } from "../types/config";
+import type { EventKind, OffscriptEvent } from "../types/events";
+import type { DataSanitizer } from "../privacy/DataSanitizer";
+export interface EmitOptions {
+    priority?: Priority;
+    /** Momento em que o fato ocorreu, se diferente de agora. */
+    at?: number;
+}
+/** Contrato entre os recorders e o núcleo. Recorders nunca falam com o transporte diretamente. */
+export interface EventSink {
+    readonly config: ResolvedConfig;
+    readonly sanitizer: DataSanitizer;
+    emit<T>(kind: EventKind, data: T, opts?: EmitOptions): OffscriptEvent<T> | null;
+}
+export interface Recorder {
+    readonly name: string;
+    start(): void | Promise<void>;
+    stop(): void;
+    pause?(): void;
+    resume?(): void | Promise<void>;
+}
+/** Executa um trecho sem nunca propagar erro para a aplicação hospedeira. */
+export declare function guard(sink: {
+    emit: EventSink["emit"];
+} | null, name: string, fn: () => void): void;

package/dist/transport/EventQueue.d.ts

@@ -0,0 +1,28 @@
+import type { OffscriptEvent } from "../types/events";
+import type { Priority } from "../types/config";
+/**
+ * Fila de staging em memória + controle de backpressure.
+ * Eventos "critical" (snapshots rrweb, lifecycle, ações) nunca são descartados
+ * antes dos "low" (mousemove, scroll, console) e têm um teto 2x maior.
+ */
+export declare class EventQueue {
+    private readonly maxEvents;
+    private readonly maxBytes;
+    private staged;
+    private pendingCount;
+    private pendingBytes;
+    dropped: number;
+    constructor(maxEvents: number, maxBytes: number);
+    canAccept(priority: Priority): boolean;
+    noteDropped(): void;
+    push(e: OffscriptEvent, size: number): void;
+    /** Devolve eventos ao staging sem recontar. */
+    restore(events: OffscriptEvent[]): void;
+    takeStaged(): OffscriptEvent[];
+    peekStaged(): readonly OffscriptEvent[];
+    get stagedCount(): number;
+    acked(count: number, bytes: number): void;
+    reset(count: number, bytes: number): void;
+    get pending(): number;
+    get bytes(): number;
+}

package/dist/transport/EventTransport.d.ts

@@ -0,0 +1,84 @@
+import { type OffscriptEvent } from "../types/events";
+import type { Priority, TransportConfig } from "../types/config";
+import { ApiClient, nativeFetch } from "../core/ApiClient";
+import { AuthError, Emitter, SessionExpiredError } from "../utils/errors";
+import type { EventBuffer } from "./PersistentBuffer";
+export interface TransportIdentity {
+    sessionId: string;
+    executionId: string;
+    tabId: string;
+}
+export type TransportEvents = {
+    flushed: {
+        events: number;
+        batchId: string;
+        duplicate: boolean;
+    };
+    failed: {
+        error: unknown;
+        willRetryInMs?: number;
+    };
+    fatal: {
+        error: AuthError | SessionExpiredError;
+    };
+    overflow: {
+        dropped: number;
+    };
+};
+export interface DrainOptions {
+    inlineRetries: number;
+    deadline?: number;
+}
+export declare class EventTransport extends Emitter<TransportEvents> {
+    private readonly cfg;
+    private readonly api;
+    private readonly buffer;
+    private queue;
+    private retry;
+    private identity;
+    private commitTimer?;
+    private flushTimer?;
+    private retryTimer?;
+    private running;
+    private again;
+    private failures;
+    private stopped;
+    private fatal;
+    private online;
+    private lastDroppedReported;
+    constructor(cfg: TransportConfig, api: ApiClient, buffer: EventBuffer);
+    get bufferKind(): string;
+    /** Inicia o transporte para uma sessão/aba e recupera o que ficou pendente no buffer. */
+    start(identity: TransportIdentity): Promise<void>;
+    setOnline(online: boolean): void;
+    canAccept(priority: Priority): boolean;
+    noteDropped(): void;
+    get pending(): number;
+    enqueue(event: OffscriptEvent): void;
+    private commit;
+    private scheduleFlush;
+    /** Flush de melhor esforço. Retorna true se tudo foi confirmado pelo backend. */
+    flush(opts?: DrainOptions): Promise<boolean>;
+    /** Flush final com retries inline e prazo máximo. */
+    flushFinal(maxWaitMs?: number): Promise<{
+        ok: boolean;
+        pending: number;
+    }>;
+    private drain;
+    private onFailure;
+    private sendWithRetry;
+    private buildBatch;
+    /**
+     * Chamado em pagehide/beforeunload. Persiste o que está em staging (best effort, assíncrono) e
+     * tenta enviar o final da fila com fetch keepalive (limite ~64KB). Sem ACK: os eventos continuam
+     * no IndexedDB e serão reenviados (de forma idempotente) na próxima página.
+     * Não há garantia de entrega se o navegador for encerrado abruptamente.
+     */
+    flushOnUnload(): void;
+    /** Para timers; eventos não confirmados permanecem no buffer. */
+    stop(): void;
+    clearSession(sessionId: string): Promise<void>;
+    purgeExpired(retentionMs: number): Promise<void>;
+    close(): void;
+}
+export { nativeFetch };

package/dist/transport/PersistentBuffer.d.ts

@@ -0,0 +1,60 @@
+import type { OffscriptEvent } from "../types/events";
+export interface StoredEvent {
+    key: string;
+    sessionId: string;
+    tabId: string;
+    sequence: number;
+    storedAt: number;
+    size: number;
+    event: OffscriptEvent;
+}
+export interface PeekResult {
+    items: StoredEvent[];
+    bytes: number;
+}
+export interface EventBuffer {
+    readonly kind: "indexeddb" | "memory";
+    put(events: OffscriptEvent[]): Promise<void>;
+    peek(sessionId: string, tabId: string, maxEvents: number, maxBytes: number): Promise<PeekResult>;
+    remove(keys: string[]): Promise<void>;
+    stats(sessionId?: string): Promise<{
+        count: number;
+        bytes: number;
+    }>;
+    purgeOlderThan(ts: number): Promise<number>;
+    clearSession(sessionId: string): Promise<void>;
+    close(): void;
+}
+export declare const eventKey: (sessionId: string, tabId: string, seq: number) => string;
+export declare class MemoryBuffer implements EventBuffer {
+    readonly kind: "memory";
+    private map;
+    put(events: OffscriptEvent[]): Promise<void>;
+    peek(sessionId: string, tabId: string, maxEvents: number, maxBytes: number): Promise<PeekResult>;
+    remove(keys: string[]): Promise<void>;
+    stats(sessionId?: string): Promise<{
+        count: number;
+        bytes: number;
+    }>;
+    purgeOlderThan(ts: number): Promise<number>;
+    clearSession(sessionId: string): Promise<void>;
+    close(): void;
+}
+/** Persistência temporária em IndexedDB. Eventos só saem daqui após o ACK do backend. */
+export declare class IndexedDBBuffer implements EventBuffer {
+    private db;
+    readonly kind: "indexeddb";
+    private constructor();
+    static open(name: string): Promise<IndexedDBBuffer>;
+    put(events: OffscriptEvent[]): Promise<void>;
+    peek(sessionId: string, tabId: string, maxEvents: number, maxBytes: number): Promise<PeekResult>;
+    remove(keys: string[]): Promise<void>;
+    stats(sessionId?: string): Promise<{
+        count: number;
+        bytes: number;
+    }>;
+    purgeOlderThan(ts: number): Promise<number>;
+    clearSession(sessionId: string): Promise<void>;
+    close(): void;
+}
+export declare function openBuffer(name: string, persist: boolean): Promise<EventBuffer>;

package/dist/transport/RetryManager.d.ts

@@ -0,0 +1,9 @@
+/** Exponential backoff com full jitter. */
+export declare class RetryManager {
+    private readonly baseMs;
+    private readonly maxMs;
+    private readonly random;
+    constructor(baseMs: number, maxMs: number, random?: () => number);
+    delay(attempt: number): number;
+    sleep(ms: number): Promise<void>;
+}

package/dist/types/config.d.ts

@@ -0,0 +1,115 @@
+export type Priority = "critical" | "normal" | "low";
+export interface RecordingConfig {
+    /** Gravação visual (rrweb). */
+    rrweb: boolean;
+    /** Ações semânticas (clique, input, teclado...). */
+    actions: boolean;
+    /** Instrumentação de fetch/XMLHttpRequest. */
+    http: boolean;
+    /** console.* */
+    console: boolean;
+    /** window.onerror / unhandledrejection */
+    errors: boolean;
+    /** Metadados de contexto (navegador, viewport...). */
+    context: boolean;
+    /** Detecção de iframes de terceiros (ex.: seats.io). */
+    iframes: boolean;
+    /** Eventos de mousemove no Action Recorder (rrweb já captura o movimento visual). */
+    mouseMove: boolean;
+    /** Níveis de console capturados. */
+    consoleLevels: Array<"log" | "info" | "warn" | "error">;
+    /** Intervalo mínimo entre amostras de mousemove/scroll (ms). */
+    throttleMs: number;
+    /** Snapshot completo periódico do rrweb (ms). 0 = desligado. */
+    rrwebCheckoutEveryMs: number;
+    /** Captura de canvas pelo rrweb (custoso). */
+    rrwebRecordCanvas: boolean;
+    /** Atributos considerados identificadores de teste, em ordem de prioridade. */
+    testIdAttributes: string[];
+    /** Atributos estáveis adicionais usados na geração de seletores. */
+    stableAttributes: string[];
+}
+export interface PrivacyConfig {
+    /** Mascara valores de <input>/<textarea>/<select> no replay. Padrão: true. */
+    maskSensitiveInputs: boolean;
+    /** Mascara todo texto da página no replay. Padrão: false. */
+    maskAllText: boolean;
+    captureRequestBodies: boolean;
+    captureResponseBodies: boolean;
+    /**
+     * Valores digitados só são gravados nas ações para elementos que casem com estes seletores.
+     * Os demais viram uma referência opaca. Senhas nunca são gravadas.
+     */
+    allowedInputSelectors: string[];
+    /** Grava o valor selecionado/estado de select, checkbox e radio. Padrão: true. */
+    captureChoiceValues: boolean;
+    /** Elementos que não aparecem no replay nem nas ações. */
+    blockSelectors: string[];
+    /** Elementos cujo texto é mascarado no replay. */
+    maskTextSelectors: string[];
+    /** Elementos ignorados pelo Action Recorder. */
+    ignoreSelectors: string[];
+    /** URLs cujas requisições não são capturadas (string = prefixo/substring, RegExp). */
+    ignoreUrls: Array<string | RegExp>;
+    /** Cabeçalhos adicionais a remover. */
+    redactHeaders: string[];
+    /** Chaves adicionais (query/body/json) a redigir. */
+    redactKeys: string[];
+    /** Tamanho máximo (bytes) de cada body capturado. */
+    maxBodyBytes: number;
+    /** Content-types capturáveis como texto. */
+    textContentTypes: RegExp[];
+    /** Descrição da retenção local (ms) dos eventos não enviados no IndexedDB. */
+    localRetentionMs: number;
+}
+export interface TransportConfig {
+    batchMaxEvents: number;
+    batchMaxBytes: number;
+    flushIntervalMs: number;
+    maxMemoryEvents: number;
+    maxBufferBytes: number;
+    maxRetries: number;
+    retryBaseMs: number;
+    retryMaxMs: number;
+    /** Compressão gzip (requer suporte do backend: Content-Encoding: gzip). */
+    compress: boolean;
+    /** Limite para envio com keepalive no encerramento da página (browsers limitam a ~64KB). */
+    keepaliveMaxBytes: number;
+    /** Persistência em IndexedDB. Se indisponível, cai para memória. */
+    persist: boolean;
+    requestTimeoutMs: number;
+}
+export interface OffscriptConfig {
+    apiUrl: string;
+    platformId: string;
+    /** Versão/build da aplicação testada. */
+    appVersion?: string;
+    recording?: Partial<RecordingConfig>;
+    privacy?: Partial<PrivacyConfig>;
+    transport?: Partial<TransportConfig>;
+    /** Janela (ms) para relacionar requisições/erros à ação anterior. */
+    correlationWindowMs?: number;
+    /** Retoma automaticamente a sessão persistida em init() (após reload/navegação). Padrão: true. */
+    autoResume?: boolean;
+    /** Intervalo de heartbeat quando o backend não informar. */
+    heartbeatIntervalMs?: number;
+    /** Prefixo de chaves de storage. */
+    storagePrefix?: string;
+    debug?: boolean;
+}
+export interface ResolvedConfig {
+    apiUrl: string;
+    platformId: string;
+    appVersion?: string;
+    recording: RecordingConfig;
+    privacy: PrivacyConfig;
+    transport: TransportConfig;
+    correlationWindowMs: number;
+    autoResume: boolean;
+    heartbeatIntervalMs: number;
+    storagePrefix: string;
+    debug: boolean;
+}
+export declare const DEFAULT_RECORDING: RecordingConfig;
+export declare const DEFAULT_PRIVACY: PrivacyConfig;
+export declare const DEFAULT_TRANSPORT: TransportConfig;

package/dist/types/events.d.ts

@@ -0,0 +1,185 @@
+export declare const SCHEMA_VERSION = "1.0";
+export declare const SDK_VERSION = "0.1.0";
+export type EventKind = "rrweb" | "action" | "http" | "console" | "error" | "context" | "iframe" | "lifecycle";
+/** Envelope comum a todos os eventos. A ordem canônica é (tabId, sequence). */
+export interface OffscriptEvent<T = unknown> {
+    /** Identificador único (idempotência). */
+    id: string;
+    kind: EventKind;
+    sessionId: string;
+    executionId: string;
+    tabId: string;
+    pageId: string;
+    /** Sequência monotônica por aba, persistida entre páginas. */
+    sequence: number;
+    /** Momento em que o fato ocorreu (epoch ms). */
+    timestamp: number;
+    /** Ação do usuário mais recente dentro da janela de correlação. */
+    relatedActionId?: string;
+    relatedActionDeltaMs?: number;
+    data: T;
+}
+export interface EventBatch {
+    schemaVersion: string;
+    batchId: string;
+    sessionId: string;
+    executionId: string;
+    tabId: string;
+    sequenceStart: number;
+    sequenceEnd: number;
+    createdAt: number;
+    sdkVersion: string;
+    events: OffscriptEvent[];
+}
+/** Contrato das ações semânticas (versionado por ACTION_SCHEMA_VERSION). */
+export declare const ACTION_SCHEMA_VERSION = "1.0";
+export type ActionType = "click" | "dblclick" | "hover" | "mousemove" | "drag" | "input" | "keydown" | "select" | "check" | "scroll" | "navigate" | "reload" | "focus" | "blur";
+export interface SelectorCandidate {
+    strategy: "testid" | "attribute" | "role" | "label" | "placeholder" | "id" | "css";
+    /** Seletor em sintaxe Playwright (ex.: `role=button[name="Salvar"]`). */
+    selector: string;
+    /** Único no documento no momento da ação. */
+    unique: boolean;
+    matches: number;
+}
+export interface ElementDescriptor {
+    tag: string;
+    id?: string;
+    role?: string;
+    name?: string;
+    text?: string;
+    type?: string;
+    testId?: string;
+    classes?: string[];
+    href?: string;
+    inputName?: string;
+    rect?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+}
+export interface RecordedAction {
+    schemaVersion: string;
+    id: string;
+    sessionId: string;
+    executionId: string;
+    timestamp: number;
+    /** Mesma sequência do envelope do evento. */
+    sequence: number;
+    type: ActionType;
+    url: string;
+    selector?: string;
+    selectorCandidates?: SelectorCandidate[];
+    selectorUnique?: boolean;
+    element?: ElementDescriptor;
+    coordinates?: {
+        x: number;
+        y: number;
+    };
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    payload?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+export interface HttpEventData {
+    requestId: string;
+    transport: "fetch" | "xhr";
+    url: string;
+    method: string;
+    query?: Record<string, string | string[]>;
+    requestHeaders?: Record<string, string>;
+    requestBody?: CapturedBody;
+    status?: number;
+    statusText?: string;
+    responseHeaders?: Record<string, string>;
+    responseBody?: CapturedBody;
+    startedAt: number;
+    endedAt: number;
+    durationMs: number;
+    /** fetch: tempo até os headers; xhr: até loadend. */
+    error?: {
+        name: string;
+        message: string;
+    };
+    aborted?: boolean;
+    /** Quantas requisições estavam em andamento quando esta começou. */
+    concurrent: number;
+}
+export interface CapturedBody {
+    kind: "text" | "json" | "form" | "binary" | "omitted";
+    value?: unknown;
+    size?: number;
+    truncated?: boolean;
+    reason?: string;
+}
+export interface ConsoleEventData {
+    level: "log" | "info" | "warn" | "error";
+    args: unknown[];
+    message: string;
+    stack?: string;
+    url: string;
+}
+export interface ErrorEventData {
+    source: "window.onerror" | "unhandledrejection" | "resource";
+    message: string;
+    name?: string;
+    stack?: string;
+    file?: string;
+    line?: number;
+    column?: number;
+    url: string;
+}
+export interface ContextEventData {
+    reason: "initial" | "viewport" | "navigation" | "visibility" | "page-load";
+    url: string;
+    referrer?: string;
+    title?: string;
+    navigationType?: string;
+    browser?: {
+        name?: string;
+        version?: string;
+    };
+    os?: string;
+    userAgent: string;
+    screen: {
+        width: number;
+        height: number;
+    };
+    viewport: {
+        width: number;
+        height: number;
+    };
+    devicePixelRatio: number;
+    language: string;
+    timezone?: string;
+    online: boolean;
+    visibility?: string;
+    platformId: string;
+    testCaseId: string;
+    executionId: string;
+    sdkVersion: string;
+    appVersion?: string;
+}
+export interface IframeEventData {
+    phase: "present" | "removed" | "focus" | "blur" | "resized";
+    provider?: "seatsio" | "unknown";
+    origin?: string;
+    path?: string;
+    crossOrigin: boolean;
+    rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    index: number;
+    limitation: string;
+}
+export interface LifecycleEventData {
+    type: "session-start" | "session-resume" | "page-start" | "page-end" | "pause" | "resume" | "stop" | "navigation" | "overflow" | "recorder-error";
+    detail?: Record<string, unknown>;
+}

package/dist/types/session.d.ts

@@ -0,0 +1,77 @@
+export type RecordingStatus = "idle" | "initializing" | "recording" | "paused" | "stopping" | "stopped" | "error";
+export interface StartRecordingOptions {
+    testCaseId: string;
+    executionId: string;
+    /** Token de curta duração emitido pelo backend da Offscript. */
+    sessionToken: string;
+}
+/** Estado persistido em sessionStorage (escopo: aba). */
+export interface PersistedSessionState {
+    version: 1;
+    tabId: string;
+    sessionId: string;
+    executionId: string;
+    testCaseId: string;
+    platformId: string;
+    sessionToken: string;
+    status: "recording" | "paused";
+    /** Último número de sequência emitido por esta aba. */
+    sequence: number;
+    /** Número de páginas já gravadas nesta aba. */
+    pageCount: number;
+    heartbeatIntervalMs?: number;
+    expiresAt?: number;
+    updatedAt: number;
+}
+export interface SessionInfo {
+    sessionId: string;
+    executionId: string;
+    testCaseId: string;
+    platformId: string;
+    tabId: string;
+    pageId: string;
+    startedAt: number;
+}
+export interface OffscriptState {
+    status: RecordingStatus;
+    session: SessionInfo | null;
+    pending: number;
+    lastError?: {
+        code: string;
+        message: string;
+    };
+}
+/** Resposta de POST /sdk/sessions */
+export interface CreateSessionResponse {
+    sessionId: string;
+    recording: {
+        enabled: boolean;
+        reason?: string;
+    };
+    expiresAt?: number;
+    heartbeatIntervalMs?: number;
+    /** Token renovado (opcional). */
+    sessionToken?: string;
+    limits?: {
+        maxBatchBytes?: number;
+        maxBatchEvents?: number;
+    };
+}
+export interface HeartbeatResponse {
+    status: "active" | "disabled" | "expired";
+    sessionToken?: string;
+    expiresAt?: number;
+}
+export interface EventsAck {
+    batchId: string;
+    /** Maior sequência persistida contiguamente para a aba. */
+    persistedThrough?: number;
+    accepted: number;
+    duplicate?: boolean;
+}
+export interface StopSummary {
+    sessionId: string;
+    flushed: boolean;
+    pendingEvents: number;
+    completed: boolean;
+}

package/dist/utils/errors.d.ts

@@ -0,0 +1,41 @@
+export type OffscriptErrorCode = "CONFIG_INVALID" | "AUTH_FAILED" | "SESSION_EXPIRED" | "SESSION_DISABLED" | "INVALID_STATE" | "TRANSPORT_FAILED" | "PAYLOAD_TOO_LARGE" | "NOT_SUPPORTED" | "INTERNAL";
+export declare class OffscriptError extends Error {
+    readonly code: OffscriptErrorCode;
+    readonly status?: number;
+    readonly cause?: unknown;
+    constructor(code: OffscriptErrorCode, message: string, opts?: {
+        status?: number;
+        cause?: unknown;
+    });
+}
+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;
+    on<K extends keyof M>(type: K, fn: (payload: M[K]) => void): () => void;
+    off<K extends keyof M>(type: K, fn: (payload: M[K]) => void): void;
+    emit<K extends keyof M>(type: K, payload: M[K]): void;
+    clear(): void;
+}

package/dist/utils/id.d.ts

@@ -0,0 +1 @@
+export declare function uid(prefix?: string): string;