@holdyapp/sdk 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,114 @@
+export type CanonicalPrimitive = 'workflow.started' | 'workflow.progressed' | 'workflow.blocked' | 'workflow.completed' | 'workflow.abandoned' | 'outcome.progressed' | 'outcome.completed' | 'outcome.regressed' | 'friction.detected' | 'collaboration.invited' | 'collaboration.joined' | 'collaboration.deepened' | 'collaboration.weakened' | 'collaboration.champion_lost' | 'support.escalated' | 'support.sentiment_negative' | 'support.theme_detected' | 'expansion.intent_detected' | 'expansion.ceiling_hit' | 'memory.append' | 'session.activity';
+export type DecisionType = 'intervention' | 'briefing' | 'cs_task' | 'track_journey' | 'no_action';
+export type InterventionKind = 'tooltip' | 'banner' | 'modal' | 'checklist' | 'spotlight' | 'cta';
+export interface ChecklistItem {
+    /** ID estável · persistência local + dedup. */
+    id: string;
+    label: string;
+    /** Opcional · link aberto ao clicar. Sem href, item só marca completed. */
+    href?: string;
+    /** Workflow ou outcome primitive que marca esse item como completed quando emitido. */
+    completed_event?: string;
+    /** Pré-marcado · server pode indicar que cliente já fez essa etapa. */
+    completed?: boolean;
+}
+export interface InterventionPayload {
+    kind: InterventionKind;
+    text: string;
+    /** Título opcional · usado em modal/checklist headers. */
+    title?: string;
+    cta_text?: string;
+    cta_href?: string;
+    anchor_selector?: string;
+    /** Items pro kind=checklist. */
+    items?: ChecklistItem[];
+}
+export interface DecisionResult {
+    decision_id: string;
+    decision_type: DecisionType;
+    decision_payload: InterventionPayload | Record<string, unknown>;
+    rule_key: string;
+    confidence: number;
+    reason: string;
+    decided_at: string;
+}
+export type OutcomeValue = 'executed' | 'dismissed' | 'converted' | 'no_show' | 'failed';
+export interface RuntimeConfig {
+    api_version: string;
+    taxonomy_version: string;
+    organization_id: string;
+    thresholds: Record<string, number | string>;
+    features: {
+        auto_attribution: boolean;
+        interventions_enabled: boolean;
+        consent_required: boolean;
+    };
+    theme?: ThemeConfig;
+}
+export interface ThemeConfig {
+    primary_color: string;
+    font_family: string;
+    border_radius_px: number;
+    position_offset_px: number;
+}
+export declare const DEFAULT_THEME: ThemeConfig;
+export interface HoldyConfig {
+    apiKey: string;
+    apiUrl?: string;
+    accountId?: string;
+    userId?: string;
+    sessionId?: string;
+    consumer?: 'ui' | 'csm' | 'agent';
+    debug?: boolean;
+    /** Disables render runtime · SDK só captura telemetry. */
+    renderInterventions?: boolean;
+    /**
+     * Stage 28 · auto-capture de page views (initial_load + route_change +
+     * visibility_change). Quando true, SDK monkeypatcha history.pushState/
+     * replaceState + escuta popstate/visibilitychange e emite session.activity
+     * sem código manual. Default false pra back-compat.
+     */
+    autoCapture?: boolean;
+}
+/**
+ * Rich account metadata enviado pra /v1/accounts/upsert.
+ * Backend usa COALESCE — não sobrescreve campos preenchidos no wizard manual.
+ *
+ * `external_id` é o identificador do cliente (string opaca · ex "acct_abc123").
+ * Backend resolve via customer_identities(source='sdk') → accounts.id.
+ */
+export interface AccountIdentity {
+    external_id: string;
+    name?: string;
+    logo_url?: string;
+    domain?: string;
+    plan?: string;
+    mrr?: number;
+    contract_start?: string;
+    contract_end?: string;
+    lifecycle_stage?: 'onboarding' | 'adoption' | 'expansion' | 'renewal' | 'churned';
+    traits?: Record<string, string | number | boolean | null>;
+}
+export interface UserIdentity {
+    external_id: string;
+    email?: string;
+    name?: string;
+    job_title?: string;
+    role?: 'decision_maker' | 'champion' | 'admin' | 'user' | 'unknown';
+}
+export interface IdentifyOptions {
+    /** ID interno Holdy (UUID) · opcional · usado pra retro-compat. */
+    accountId?: string;
+    userId?: string;
+    sessionId?: string;
+    /** Metadata rica · gera best-effort upsert em /v1/accounts/upsert. */
+    account?: AccountIdentity;
+    user?: UserIdentity;
+}
+export interface TrackOptions {
+    /** Pula chamada implícita ao decisions/evaluate. */
+    skipEval?: boolean;
+    /** Workflow corrente · override do estado interno. */
+    workflow?: string;
+}
+export type DecisionListener = (decision: DecisionResult) => void;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@holdyapp/sdk",
+  "version": "0.2.0",
+  "description": "Holdy SDK · behavioral telemetry + in-product interventions",
+  "private": false,
+  "license": "MIT",
+  "homepage": "https://app.holdy.com.br",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/augustoperolligaedke/holdymvp.git",
+    "directory": "sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/augustoperolligaedke/holdymvp/issues"
+  },
+  "keywords": [
+    "customer-success",
+    "behavioral-analytics",
+    "in-product",
+    "interventions",
+    "holdy"
+  ],
+  "type": "module",
+  "main": "./dist/holdy.cjs.js",
+  "module": "./dist/holdy.esm.js",
+  "browser": "./dist/holdy.iife.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/holdy.esm.js",
+      "require": "./dist/holdy.cjs.js",
+      "default": "./dist/holdy.esm.js"
+    }
+  },
+  "scripts": {
+    "build:js": "node build.mjs",
+    "build:types": "tsc --emitDeclarationOnly",
+    "build": "npm run build:js && npm run build:types",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "typescript": "^5.9.0"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/anchor.ts

@@ -0,0 +1,72 @@
+/**
+ * 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/auto-capture.ts

@@ -0,0 +1,129 @@
+/**
+ * Auto-capture · Stage 28 G_auto.
+ *
+ * Quando HoldyConfig.autoCapture=true, instalamos hooks globais que
+ * emitem `session.activity` automaticamente:
+ *
+ *   · initial_load        · 1x ao init
+ *   · route_change        · cada history.pushState/replaceState/popstate
+ *   · visibility_change   · página voltou a ficar visível
+ *
+ * Tudo client-side · não precisa que o customer declare nada. Permite que
+ * o widget de install do Holdy mostre "✓ conectado" segundos após o user
+ * carregar a página.
+ *
+ * Idempotente · re-rodar `installAutoCapture` é no-op via guard global.
+ * Cleanup ao destroy via array de unsubscribers retornado.
+ */
+
+export interface AutoCaptureEmit {
+  (path: string, title: string | undefined, referrer: string | undefined, kind: 'initial_load' | 'route_change' | 'visibility_change'): void
+}
+
+const INSTALLED_FLAG = '__holdy_autocapture_installed__'
+const ROUTE_DEBOUNCE_MS = 50
+
+interface GlobalWithFlag {
+  [INSTALLED_FLAG]?: boolean
+  history?: History
+}
+
+export function installAutoCapture(emit: AutoCaptureEmit): () => void {
+  if (typeof window === 'undefined' || typeof history === 'undefined') {
+    return () => undefined
+  }
+  const w = window as unknown as GlobalWithFlag
+  if (w[INSTALLED_FLAG]) {
+    return () => undefined
+  }
+  w[INSTALLED_FLAG] = true
+
+  const cleanups: Array<() => void> = []
+  let lastPath = currentPath()
+  let pendingRouteEmit: ReturnType<typeof setTimeout> | null = null
+
+  function safeEmit(kind: 'initial_load' | 'route_change' | 'visibility_change'): void {
+    try {
+      const path = currentPath()
+      const title = typeof document !== 'undefined' ? document.title : undefined
+      const referrer = typeof document !== 'undefined' ? document.referrer || undefined : undefined
+      emit(path, title, referrer, kind)
+    } catch {
+      // never throw from auto-capture · não pode quebrar a app do cliente
+    }
+  }
+
+  function scheduleRouteEmit(): void {
+    // Debounce: pushState seguido de replaceState é 1 mudança lógica.
+    if (pendingRouteEmit) clearTimeout(pendingRouteEmit)
+    pendingRouteEmit = setTimeout(() => {
+      const path = currentPath()
+      if (path !== lastPath) {
+        lastPath = path
+        safeEmit('route_change')
+      }
+      pendingRouteEmit = null
+    }, ROUTE_DEBOUNCE_MS)
+  }
+
+  // 1) Initial load
+  safeEmit('initial_load')
+
+  // 2) Monkeypatch history.pushState/replaceState (SPA SDR navigation)
+  const origPush = history.pushState
+  const origReplace = history.replaceState
+  history.pushState = function patchedPush(...args: Parameters<History['pushState']>) {
+    const result = origPush.apply(this, args)
+    scheduleRouteEmit()
+    return result
+  }
+  history.replaceState = function patchedReplace(...args: Parameters<History['replaceState']>) {
+    const result = origReplace.apply(this, args)
+    scheduleRouteEmit()
+    return result
+  }
+  cleanups.push(() => {
+    history.pushState = origPush
+    history.replaceState = origReplace
+  })
+
+  // 3) popstate · botão voltar/avançar do browser
+  const popHandler = (): void => scheduleRouteEmit()
+  window.addEventListener('popstate', popHandler)
+  cleanups.push(() => window.removeEventListener('popstate', popHandler))
+
+  // 4) hashchange · single-page apps que usam hash routing (router antigo)
+  const hashHandler = (): void => scheduleRouteEmit()
+  window.addEventListener('hashchange', hashHandler)
+  cleanups.push(() => window.removeEventListener('hashchange', hashHandler))
+
+  // 5) visibility_change · tab voltou a ficar visível depois de >5min
+  let hiddenAt: number | null = null
+  const visHandler = (): void => {
+    if (typeof document === 'undefined') return
+    if (document.visibilityState === 'hidden') {
+      hiddenAt = Date.now()
+    } else if (document.visibilityState === 'visible' && hiddenAt) {
+      const elapsed = Date.now() - hiddenAt
+      hiddenAt = null
+      // Re-emit só se ficou hidden >5min · evita flood quando user troca aba rapidinho
+      if (elapsed > 5 * 60_000) safeEmit('visibility_change')
+    }
+  }
+  if (typeof document !== 'undefined') {
+    document.addEventListener('visibilitychange', visHandler)
+    cleanups.push(() => document.removeEventListener('visibilitychange', visHandler))
+  }
+
+  // Final cleanup function · usado pelo destroy()
+  return () => {
+    if (pendingRouteEmit) clearTimeout(pendingRouteEmit)
+    for (const c of cleanups) c()
+    w[INSTALLED_FLAG] = false
+  }
+}
+
+function currentPath(): string {
+  if (typeof window === 'undefined' || !window.location) return '/'
+  return window.location.pathname + window.location.search + window.location.hash
+}