@holdyapp/sdk 0.2.1 → 1.0.0

package/dist/outcome.d.ts

@@ -1,19 +0,0 @@
-import type { OutcomeValue } from './types';
-import type { Transport } from './transport';
-/**
- * Outcome tracker · explicit only.
- *
- * - executed → ack via UI handler.
- * - dismissed → ack via UI handler.
- * - no_show → SDK detecta anchor não resolvido em 5s.
- * - failed → exception capturada pelo render boundary.
- * - converted → conversion cron server-side faz join workflow.completed.
- */
-export declare class OutcomeTracker {
-    private readonly transport;
-    private readonly pending;
-    constructor(transport: Transport);
-    registerPending(decisionId: string, workflow: string | undefined): void;
-    dispatch(decisionId: string, outcome: OutcomeValue, metadata?: Record<string, unknown>): void;
-    hasPending(decisionId: string): boolean;
-}

package/dist/queue.d.ts

@@ -1,54 +0,0 @@
-/**
- * Event queue · IndexedDB-backed retry com exponential backoff.
- *
- * Por que existe: SDK fire-and-forget perde eventos quando rede falha
- * (offline · 429 · 500 transitório · pagehide mid-flight). Sem fila, drop
- * silencioso · learning loop pega só os 80-90% que chegam.
- *
- * Comportamento:
- *   · enqueue(events) tenta enviar imediatamente. Se falha (ou já tinha fila),
- *     grava em IndexedDB com nextRetryAt = agora + 1s.
- *   · flusher background polla a cada 5s, dequeue ordenado por nextRetryAt,
- *     manda batch. Sucesso → delete da fila. Falha → backoff próximo.
- *   · Backoff: 1s → 2s → 4s → 8s → 16s. Após 5 tentativas, drop com log.
- *   · Cap 1000 itens (rough proxy 50KB cada · 50MB max). Quando cheio, drop
- *     o mais antigo (FIFO).
- *   · pagehide: tenta drain síncrono final via keepalive fetch (browser
- *     entrega depois mesmo se aba fechou).
- *
- * Fallback: ambientes sem IndexedDB (SSR · Privacy mode em Safari rígido) caem
- * pra fila em memória — perde tudo no reload, mas SDK ainda funciona.
- */
-export interface QueuedBatch {
-    /** Auto-increment key. */
-    id?: number;
-    /** Eventos serializados (já com idempotency_key gerado). */
-    events: unknown[];
-    attempts: number;
-    next_retry_at: number;
-    created_at: number;
-}
-export interface SendFn {
-    /** Retorna true em sucesso, false em falha (caller decide retry). */
-    (body: {
-        events: unknown[];
-    }): Promise<boolean>;
-}
-export declare class EventQueue {
-    private readonly driver;
-    private readonly send;
-    private flushTimer;
-    private flushing;
-    private readonly log;
-    constructor(send: SendFn, log?: (...args: unknown[]) => void);
-    /**
-     * Tenta enviar imediato; se falhar OU já houver fila pendente (ordem),
-     * adiciona com next_retry_at = agora + 1s.
-     */
-    enqueue(events: unknown[]): Promise<void>;
-    private startFlusher;
-    private flushOnce;
-    private bindPagehide;
-    /** Pra testes. */
-    destroy(): void;
-}

package/dist/render/kinds/banner.d.ts

@@ -1,3 +0,0 @@
-import type { InterventionPayload } from '../../types';
-import { type RenderControl, type RenderHandlers } from './shared';
-export declare function renderBanner(payload: InterventionPayload, handlers: RenderHandlers): RenderControl;

package/dist/render/kinds/checklist.d.ts

@@ -1,19 +0,0 @@
-import type { InterventionPayload } from '../../types';
-import { type RenderControl, type RenderHandlers } from './shared';
-/**
- * Checklist · sticky bottom-right com lista de tarefas.
- *
- * Persistência: estado por decision_id em localStorage (chave
- * `holdy_checklist_{decision_id}`). Rehidratado em re-render.
- *
- * UX:
- *   · cada item tem checkbox · clique marca/desmarca
- *   · item com href abre em _self quando label clicado (após marcar)
- *   · primeiro completed dispara onExecuted UMA vez (não a cada check)
- *   · todos completed dispara onExecuted com metadata={completed:true}
- *   · close button dispara onDismissed
- *
- * NÃO há outcome 'converted' aqui — fica pro caller (Holdy backend) detectar
- * via workflow.completed downstream.
- */
-export declare function renderChecklist(payload: InterventionPayload, decisionId: string, handlers: RenderHandlers): RenderControl;

package/dist/render/kinds/cta.d.ts

@@ -1,8 +0,0 @@
-import type { InterventionPayload } from '../../types';
-import { type RenderControl, type RenderHandlers } from './shared';
-/**
- * CTA sticky bottom-right · usado quando não há anchor específico mas a
- * intervention precisa de presença persistente (ex: convite pra rodar
- * onboarding workflow).
- */
-export declare function renderCta(payload: InterventionPayload, handlers: RenderHandlers): RenderControl;

package/dist/render/kinds/modal.d.ts

@@ -1,16 +0,0 @@
-import type { InterventionPayload } from '../../types';
-import { type RenderControl, type RenderHandlers } from './shared';
-/**
- * Modal · overlay centralizado com backdrop.
- *
- * UX:
- *   · backdrop click dismissa (igual padrão Apple/Stripe)
- *   · ESC dismissa
- *   · focus trap entre primeiro/último focusable
- *   · scroll body bloqueado enquanto aberto
- *   · role=dialog + aria-modal pra acessibilidade
- *
- * Uso: intervention de alto peso (renewal aproximando, churn risk
- * crítico, expansion oferecida com 1 click). Limite global de 1.
- */
-export declare function renderModal(payload: InterventionPayload, handlers: RenderHandlers): RenderControl;

package/dist/render/kinds/shared.d.ts

@@ -1,16 +0,0 @@
-import type { InterventionPayload, OutcomeValue } from '../../types';
-export interface RenderHandlers {
-    onExecuted(metadata?: Record<string, unknown>): void;
-    onDismissed(metadata?: Record<string, unknown>): void;
-    onFailed(metadata?: Record<string, unknown>): void;
-}
-export interface RenderControl {
-    el: HTMLElement;
-    dismiss: (outcome?: OutcomeValue, metadata?: Record<string, unknown>) => void;
-}
-/** Cria botão fechar SDK-owned · dispatch dismissed. */
-export declare function buildCloseButton(onDismiss: () => void): HTMLButtonElement;
-/** Cria CTA button OU anchor SDK-owned · dispatch executed. */
-export declare function buildCtaButton(payload: InterventionPayload, onExecuted: () => void): HTMLElement | null;
-export declare function buildTextNode(text: string): HTMLParagraphElement;
-export declare function buildActionsRow(...children: Array<HTMLElement | null>): HTMLDivElement | null;

package/dist/render/kinds/spotlight.d.ts

@@ -1,17 +0,0 @@
-import type { InterventionPayload } from '../../types';
-import { type RenderControl, type RenderHandlers } from './shared';
-/**
- * Spotlight · backdrop escurecido com "buraco" recortado no anchor +
- * tooltip apontando.
- *
- * UX:
- *   · backdrop tem clip-path criando ring around o elemento
- *   · tooltip aparece abaixo (ou acima se sem espaço)
- *   · clique no anchor original (atravessa o buraco via pointer-events:none
- *     na área do hole) executa
- *   · backdrop click fora do hole dismissa
- *   · ESC dismissa
- *
- * Uso: onboarding step "veja esse botão", first-time UI guidance.
- */
-export declare function renderSpotlight(payload: InterventionPayload, anchor: Element | null, handlers: RenderHandlers): RenderControl;

package/dist/render/kinds/tooltip.d.ts

@@ -1,3 +0,0 @@
-import type { InterventionPayload } from '../../types';
-import { type RenderControl, type RenderHandlers } from './shared';
-export declare function renderTooltip(payload: InterventionPayload, anchor: Element | null, handlers: RenderHandlers): RenderControl;

package/dist/render/root.d.ts

@@ -1,3 +0,0 @@
-import type { ThemeConfig } from '../types';
-export declare function ensureRoot(theme: ThemeConfig | undefined): ShadowRoot | null;
-export declare function appendToRoot(node: HTMLElement): void;

package/dist/render/styles.d.ts

@@ -1,5 +0,0 @@
-import type { ThemeConfig } from '../types';
-export declare function getStyleSheet(): CSSStyleSheet | null;
-export declare function applyThemeVars(host: HTMLElement, theme: ThemeConfig | undefined): void;
-/** Fallback pra browsers sem adoptedStyleSheets (Safari <16.4). */
-export declare function injectFallbackStyle(root: ShadowRoot): void;

package/dist/store.d.ts

@@ -1,36 +0,0 @@
-import type { InterventionKind } from './types';
-interface ActiveSlot {
-    decisionId: string;
-    confidence: number;
-    kind: InterventionKind;
-    dismiss: () => void;
-}
-/**
- * Active intervention slots · prioridade por confidence.
- *
- * Caps globais:
- *   - 1 banner global
- *   - 1 modal global (Wave 2 · UX bloqueia tudo, único)
- *   - 1 checklist global (Wave 2 · sticky bottom-right)
- *   - N tooltips, 1 por anchor
- *   - N spotlights, 1 por anchor (Wave 2)
- *   - 1 CTA global (sticky bottom-right)
- *
- * Modal e checklist + cta competem pelo mesmo "espaço mental" do usuário ·
- * a próxima implementação pode consolidar (1 floating element no canto).
- * Wave 2 mantém slots separados pra simplicidade.
- *
- * Quando 2 decisions reivindicam o mesmo slot, a de menor confidence perde.
- */
-export declare class InterventionStore {
-    private readonly tooltipsByAnchor;
-    private readonly spotlightsByAnchor;
-    private banner;
-    private modal;
-    private checklist;
-    private cta;
-    /** Tenta reivindicar slot. Retorna previous slot que precisa ser dismissado (caller). */
-    claim(kind: InterventionKind, decisionId: string, confidence: number, anchorSelector: string | undefined, dismiss: () => void): ActiveSlot | null;
-    release(decisionId: string): void;
-}
-export {};

package/dist/transport.d.ts

@@ -1,59 +0,0 @@
-import type { AccountIdentity, CanonicalPrimitive, DecisionResult, HoldyConfig, RuntimeConfig, UserIdentity } from './types';
-export declare class Transport {
-    private readonly apiKey;
-    private readonly apiUrl;
-    private readonly debug;
-    private readonly queue;
-    constructor(config: HoldyConfig);
-    private headers;
-    fetchRuntimeConfig(): Promise<RuntimeConfig | null>;
-    evaluate(input: {
-        account_id: string;
-        current_workflow?: string;
-        recent_primitives?: Array<{
-            primitive: CanonicalPrimitive;
-            payload: Record<string, unknown>;
-            occurred_at: string;
-        }>;
-        recent_sentiment?: 'positivo' | 'neutro' | 'negativo' | 'urgente';
-        consumer?: 'ui' | 'csm' | 'agent';
-    }): Promise<DecisionResult | null>;
-    /**
-     * Event ingest · delegado pra EventQueue (IndexedDB + exponential backoff).
-     * Tenta envio imediato; se falhar, persiste e retry em background.
-     */
-    ingestBatch(events: Array<{
-        primitive: CanonicalPrimitive;
-        occurred_at: string;
-        account_id?: string;
-        user_id?: string;
-        session_id?: string;
-        payload: Record<string, unknown>;
-        idempotency_key?: string;
-    }>): void;
-    /**
-     * Send raw · usado pelo queue. Retorna true em sucesso (2xx), false em
-     * falha (rede ou 4xx/5xx).
-     *
-     * IMPORTANTE: 4xx é tratado como falha permanente — não vale retry. Mas
-     * a fila não distingue (mantém pra retry simples). MAX_ATTEMPTS = 5 limita
-     * o desperdício. Refinamento (4xx → drop imediato) fica pra Wave 3.
-     */
-    private sendBatch;
-    /**
-     * Upsert account + opcional user via /v1/accounts/upsert.
-     *
-     * Best-effort fire-and-forget. Backend COALESCE não sobrescreve campos não-nulos.
-     * Retorna account_id (UUID Holdy) pra hidratar config local; null em falha.
-     */
-    upsertAccount(payload: {
-        account: AccountIdentity;
-        user?: UserIdentity;
-    }): Promise<{
-        account_id: string;
-        account_user_id: string | null;
-    } | null>;
-    reportOutcome(decisionId: string, outcome: 'executed' | 'dismissed' | 'converted' | 'no_show' | 'failed', metadata?: Record<string, unknown>): void;
-    private log;
-    destroy(): void;
-}

package/src/anchor.ts

@@ -1,72 +0,0 @@
-/**
- * Anchor resolver · MutationObserver-based.
- *
- * Cliente do produto pode renderizar o anchor depois do decision chegar
- * (SPA route, lazy mount). Resolver espera até 5s antes de desistir.
- * Single observer global · cap retries por selector.
- */
-
-const RESOLVE_TIMEOUT_MS = 5000
-
-interface PendingAnchor {
-  selector: string
-  resolve: (el: Element | null) => void
-  cleanup: () => void
-}
-
-const pending = new Set<PendingAnchor>()
-let observer: MutationObserver | null = null
-
-function ensureObserver(): void {
-  if (observer || typeof MutationObserver === 'undefined' || typeof document === 'undefined') return
-  observer = new MutationObserver(() => {
-    if (pending.size === 0) return
-    pending.forEach((entry) => {
-      const el = document.querySelector(entry.selector)
-      if (el) {
-        entry.cleanup()
-        entry.resolve(el)
-      }
-    })
-    if (pending.size === 0) stopObserver()
-  })
-  observer.observe(document.body, { childList: true, subtree: true, attributes: true, attributeFilter: ['id', 'class', 'data-holdy-anchor'] })
-}
-
-function stopObserver(): void {
-  if (observer) {
-    observer.disconnect()
-    observer = null
-  }
-}
-
-export function resolveAnchor(selector: string | undefined): Promise<Element | null> {
-  if (!selector) return Promise.resolve(null)
-  if (typeof document === 'undefined') return Promise.resolve(null)
-
-  // Try sync first
-  const existing = document.querySelector(selector)
-  if (existing) return Promise.resolve(existing)
-
-  return new Promise<Element | null>((resolve) => {
-    let resolved = false
-    const entry: PendingAnchor = {
-      selector,
-      resolve,
-      cleanup: () => {
-        if (resolved) return
-        resolved = true
-        pending.delete(entry)
-        clearTimeout(timeoutId)
-        if (pending.size === 0) stopObserver()
-      },
-    }
-    const timeoutId = setTimeout(() => {
-      entry.cleanup()
-      resolve(null)
-    }, RESOLVE_TIMEOUT_MS)
-
-    pending.add(entry)
-    ensureObserver()
-  })
-}

package/src/outcome.ts

@@ -1,51 +0,0 @@
-import type { OutcomeValue } from './types'
-import type { Transport } from './transport'
-
-interface PendingDecision {
-  id: string
-  workflow?: string | undefined
-  startedAt: number
-}
-
-/**
- * Outcome tracker · explicit only.
- *
- * - executed → ack via UI handler.
- * - dismissed → ack via UI handler.
- * - no_show → SDK detecta anchor não resolvido em 5s.
- * - failed → exception capturada pelo render boundary.
- * - converted → conversion cron server-side faz join workflow.completed.
- */
-export class OutcomeTracker {
-  private readonly transport: Transport
-  private readonly pending = new Map<string, PendingDecision>()
-
-  constructor(transport: Transport) {
-    this.transport = transport
-  }
-
-  registerPending(decisionId: string, workflow: string | undefined): void {
-    this.pending.set(decisionId, {
-      id: decisionId,
-      workflow,
-      startedAt: Date.now(),
-    })
-  }
-
-  dispatch(decisionId: string, outcome: OutcomeValue, metadata?: Record<string, unknown>): void {
-    if (!this.pending.has(decisionId) && outcome !== 'failed') {
-      // unknown decision · still report failed/dismissed since they're idempotent
-      this.transport.reportOutcome(decisionId, outcome, metadata)
-      return
-    }
-    this.pending.delete(decisionId)
-    this.transport.reportOutcome(decisionId, outcome, {
-      ...metadata,
-      latency_ms: metadata?.latency_ms ?? Date.now() - (this.pending.get(decisionId)?.startedAt ?? Date.now()),
-    })
-  }
-
-  hasPending(decisionId: string): boolean {
-    return this.pending.has(decisionId)
-  }
-}