@holdyapp/sdk 0.2.0

package/src/index.ts

@@ -0,0 +1,427 @@
+import type {
+  AccountIdentity,
+  CanonicalPrimitive,
+  DecisionListener,
+  DecisionResult,
+  HoldyConfig,
+  IdentifyOptions,
+  InterventionPayload,
+  OutcomeValue,
+  RuntimeConfig,
+  ThemeConfig,
+  TrackOptions,
+  UserIdentity,
+} from './types'
+import { Transport } from './transport'
+import { OutcomeTracker } from './outcome'
+import { InterventionStore } from './store'
+import { resolveAnchor } from './anchor'
+import { installAutoCapture } from './auto-capture'
+import { appendToRoot, ensureRoot } from './render/root'
+import { renderTooltip } from './render/kinds/tooltip'
+import { renderBanner } from './render/kinds/banner'
+import { renderCta } from './render/kinds/cta'
+import { renderModal } from './render/kinds/modal'
+import { renderChecklist } from './render/kinds/checklist'
+import { renderSpotlight } from './render/kinds/spotlight'
+import type { RenderControl, RenderHandlers } from './render/kinds/shared'
+
+const RING_BUFFER_LIMIT = 20
+const CONFIG_CACHE_KEY = '__holdy_runtime_config_v1'
+const CONFIG_CACHE_TTL_MS = 60 * 60 * 1000
+const EVAL_THROTTLE_MS = 1500
+
+interface RingEntry {
+  primitive: CanonicalPrimitive
+  payload: Record<string, unknown>
+  occurred_at: string
+}
+
+class HoldySdk {
+  private config: HoldyConfig | null = null
+  private transport: Transport | null = null
+  private outcomeTracker: OutcomeTracker | null = null
+  private store: InterventionStore = new InterventionStore()
+  private runtime: RuntimeConfig | null = null
+  private activeWorkflow: string | null = null
+  private sentiment: 'positivo' | 'neutro' | 'negativo' | 'urgente' | null = null
+  private readonly ring: RingEntry[] = []
+  private listeners: DecisionListener[] = []
+  private lastEvalAt = 0
+  private initialized = false
+  private autoCaptureCleanup: (() => void) | null = null
+
+  async init(config: HoldyConfig): Promise<void> {
+    if (this.initialized) {
+      this.log('init called twice · ignoring')
+      return
+    }
+    if (!config.apiKey) {
+      throw new Error('[holdy] apiKey is required')
+    }
+    this.config = config
+    this.transport = new Transport(config)
+    this.outcomeTracker = new OutcomeTracker(this.transport)
+    this.initialized = true
+
+    const cached = this.readCachedConfig()
+    if (cached) this.runtime = cached
+
+    const fresh = await this.transport.fetchRuntimeConfig()
+    if (fresh) {
+      this.runtime = fresh
+      this.writeCachedConfig(fresh)
+    }
+
+    if (this.shouldRender()) {
+      ensureRoot(this.themeFromRuntime())
+    }
+
+    // Stage 28 G_auto · auto-capture de page views.
+    // Habilita só quando customer pediu explicitamente · default off pra
+    // back-compat. Ring buffer + transport recebem session.activity igual
+    // se viesse de track() manual · decision engine consome no contexto.
+    if (config.autoCapture) {
+      this.autoCaptureCleanup = installAutoCapture((path, title, referrer, kind) => {
+        void this.track('session.activity', {
+          kind,
+          path,
+          ...(title ? { title } : {}),
+          ...(referrer ? { referrer } : {}),
+        }, { skipEval: kind !== 'route_change' })
+      })
+    }
+  }
+
+  /**
+   * Identifica conta + usuário corrente.
+   *
+   * - `accountId/userId/sessionId` hidratam config local pra evaluate/track.
+   * - `account/user` (metadata rica) disparam upsert best-effort em
+   *   /v1/accounts/upsert. Backend COALESCE → nunca sobrescreve campos do
+   *   wizard manual. Em sucesso, account_id Holdy retornado hidrata config
+   *   local automaticamente (cliente não precisa saber UUID).
+   */
+  identify(opts: IdentifyOptions): void {
+    if (!this.config) return
+    if (opts.accountId !== undefined) this.config.accountId = opts.accountId
+    if (opts.userId !== undefined) this.config.userId = opts.userId
+    if (opts.sessionId !== undefined) this.config.sessionId = opts.sessionId
+
+    if (opts.account || opts.user) {
+      void this.upsertIdentityRich(opts.account, opts.user)
+    }
+  }
+
+  private async upsertIdentityRich(
+    account: AccountIdentity | undefined,
+    user: UserIdentity | undefined,
+  ): Promise<void> {
+    if (!this.transport || !account) return
+    const result = await this.transport.upsertAccount({ account, user })
+    if (!result || !this.config) return
+    if (!this.config.accountId) this.config.accountId = result.account_id
+    if (!this.config.userId && result.account_user_id) {
+      this.config.userId = result.account_user_id
+    }
+  }
+
+  setWorkflow(workflowKey: string | null | undefined): void {
+    this.activeWorkflow = workflowKey ?? null
+  }
+
+  setSentiment(sentiment: 'positivo' | 'neutro' | 'negativo' | 'urgente' | null): void {
+    this.sentiment = sentiment
+  }
+
+  async track(
+    primitive: CanonicalPrimitive,
+    payload: Record<string, unknown> = {},
+    opts: TrackOptions = {},
+  ): Promise<void> {
+    if (!this.config || !this.transport) {
+      this.log('track called before init')
+      return
+    }
+    const occurred_at = new Date().toISOString()
+    const entry: RingEntry = { primitive, payload, occurred_at }
+    this.pushRing(entry)
+
+    // workflow tracking auto-sync
+    if (primitive === 'workflow.started' && typeof payload.workflow === 'string') {
+      this.activeWorkflow = payload.workflow
+    }
+    if (
+      (primitive === 'workflow.completed' || primitive === 'workflow.abandoned') &&
+      typeof payload.workflow === 'string' &&
+      this.activeWorkflow === payload.workflow
+    ) {
+      this.activeWorkflow = null
+    }
+    if (opts.workflow !== undefined) this.activeWorkflow = opts.workflow
+
+    // ingest fire-and-forget
+    this.transport.ingestBatch([
+      {
+        primitive,
+        occurred_at,
+        account_id: this.config.accountId,
+        user_id: this.config.userId,
+        session_id: this.config.sessionId,
+        payload,
+      },
+    ])
+
+    if (opts.skipEval) return
+    if (!this.shouldTriggerEval(primitive)) return
+
+    await this.evaluateInternal()
+  }
+
+  async evaluate(): Promise<DecisionResult | null> {
+    return this.evaluateInternal(true)
+  }
+
+  onDecision(listener: DecisionListener): () => void {
+    this.listeners.push(listener)
+    return () => {
+      this.listeners = this.listeners.filter((l) => l !== listener)
+    }
+  }
+
+  reportOutcome(
+    decisionId: string,
+    outcome: OutcomeValue,
+    metadata?: Record<string, unknown>,
+  ): void {
+    this.outcomeTracker?.dispatch(decisionId, outcome, metadata)
+  }
+
+  destroy(): void {
+    this.transport?.destroy()
+    if (this.autoCaptureCleanup) {
+      try { this.autoCaptureCleanup() } catch { /* ignore */ }
+      this.autoCaptureCleanup = null
+    }
+    this.config = null
+    this.transport = null
+    this.outcomeTracker = null
+    this.runtime = null
+    this.activeWorkflow = null
+    this.listeners = []
+    this.ring.length = 0
+    this.initialized = false
+  }
+
+  /* ───────── internals ───────── */
+
+  private async evaluateInternal(force = false): Promise<DecisionResult | null> {
+    if (!this.transport || !this.config?.accountId) {
+      this.log('evaluate skipped · no accountId set · call identify first')
+      return null
+    }
+    const now = Date.now()
+    if (!force && now - this.lastEvalAt < EVAL_THROTTLE_MS) {
+      return null
+    }
+    this.lastEvalAt = now
+
+    const evalInput: {
+      account_id: string
+      current_workflow?: string
+      recent_primitives: Array<{
+        primitive: CanonicalPrimitive
+        payload: Record<string, unknown>
+        occurred_at: string
+      }>
+      consumer: 'ui' | 'csm' | 'agent'
+      recent_sentiment?: 'positivo' | 'neutro' | 'negativo' | 'urgente'
+    } = {
+      account_id: this.config.accountId,
+      recent_primitives: [...this.ring],
+      consumer: this.config.consumer ?? 'ui',
+    }
+    if (this.activeWorkflow) evalInput.current_workflow = this.activeWorkflow
+    if (this.sentiment) evalInput.recent_sentiment = this.sentiment
+
+    const result = await this.transport.evaluate(evalInput)
+    if (!result) return null
+
+    this.listeners.forEach((l) => {
+      try {
+        l(result)
+      } catch (e) {
+        this.log('listener error', e)
+      }
+    })
+
+    if (result.decision_type === 'intervention' && this.shouldRender()) {
+      void this.renderDecision(result)
+    }
+
+    return result
+  }
+
+  private async renderDecision(decision: DecisionResult): Promise<void> {
+    const payload = decision.decision_payload as InterventionPayload
+    if (!payload || typeof payload.kind !== 'string' || typeof payload.text !== 'string') {
+      this.outcomeTracker?.dispatch(decision.decision_id, 'failed', { reason: 'invalid_payload' })
+      return
+    }
+
+    const handlers: RenderHandlers = {
+      onExecuted: (meta) => this.outcomeTracker?.dispatch(decision.decision_id, 'executed', meta),
+      onDismissed: (meta) => this.outcomeTracker?.dispatch(decision.decision_id, 'dismissed', meta),
+      onFailed: (meta) => this.outcomeTracker?.dispatch(decision.decision_id, 'failed', meta),
+    }
+
+    let control: RenderControl | null = null
+    try {
+      switch (payload.kind) {
+        case 'tooltip': {
+          const anchor = await resolveAnchor(payload.anchor_selector)
+          if (!anchor) {
+            this.outcomeTracker?.dispatch(decision.decision_id, 'no_show', {
+              reason: 'anchor_unresolved',
+              selector: payload.anchor_selector ?? null,
+            })
+            return
+          }
+          control = renderTooltip(payload, anchor, handlers)
+          break
+        }
+        case 'banner':
+          control = renderBanner(payload, handlers)
+          break
+        case 'cta':
+          control = renderCta(payload, handlers)
+          break
+        case 'modal':
+          control = renderModal(payload, handlers)
+          break
+        case 'checklist':
+          control = renderChecklist(payload, decision.decision_id, handlers)
+          break
+        case 'spotlight': {
+          const anchor = await resolveAnchor(payload.anchor_selector)
+          if (!anchor) {
+            this.outcomeTracker?.dispatch(decision.decision_id, 'no_show', {
+              reason: 'anchor_unresolved',
+              selector: payload.anchor_selector ?? null,
+            })
+            return
+          }
+          control = renderSpotlight(payload, anchor, handlers)
+          break
+        }
+        default:
+          this.outcomeTracker?.dispatch(decision.decision_id, 'no_show', {
+            reason: 'kind_not_supported',
+            kind: payload.kind,
+          })
+          return
+      }
+    } catch (e) {
+      this.log('render error', e)
+      handlers.onFailed({ error: String(e) })
+      return
+    }
+
+    if (!control) return
+
+    // Slot collision: store decide quem fica · sup ersedido é dismissado.
+    const superseded = this.store.claim(
+      payload.kind,
+      decision.decision_id,
+      decision.confidence,
+      payload.anchor_selector,
+      () => control!.dismiss('dismissed'),
+    )
+    if (superseded && superseded.decisionId !== decision.decision_id) {
+      superseded.dismiss()
+      this.outcomeTracker?.dispatch(superseded.decisionId, 'dismissed', {
+        reason: 'superseded',
+        by: decision.decision_id,
+      })
+    }
+
+    this.outcomeTracker?.registerPending(decision.decision_id, this.activeWorkflow ?? undefined)
+    appendToRoot(control.el)
+  }
+
+  private shouldRender(): boolean {
+    if (this.config?.renderInterventions === false) return false
+    if (this.runtime?.features && this.runtime.features.interventions_enabled === false) return false
+    return typeof document !== 'undefined'
+  }
+
+  private shouldTriggerEval(primitive: CanonicalPrimitive): boolean {
+    // Eventos que tipicamente disparam decisão (state-change ou friction).
+    return (
+      primitive === 'workflow.started' ||
+      primitive === 'workflow.blocked' ||
+      primitive === 'workflow.completed' ||
+      primitive === 'workflow.abandoned' ||
+      primitive === 'friction.detected' ||
+      primitive === 'support.sentiment_negative' ||
+      primitive === 'expansion.intent_detected' ||
+      primitive === 'expansion.ceiling_hit'
+    )
+  }
+
+  private pushRing(entry: RingEntry): void {
+    this.ring.push(entry)
+    while (this.ring.length > RING_BUFFER_LIMIT) this.ring.shift()
+  }
+
+  private themeFromRuntime(): ThemeConfig | undefined {
+    return this.runtime?.theme
+  }
+
+  private readCachedConfig(): RuntimeConfig | null {
+    if (typeof localStorage === 'undefined') return null
+    try {
+      const raw = localStorage.getItem(CONFIG_CACHE_KEY)
+      if (!raw) return null
+      const parsed = JSON.parse(raw) as { at: number; data: RuntimeConfig }
+      if (Date.now() - parsed.at > CONFIG_CACHE_TTL_MS) return null
+      return parsed.data
+    } catch {
+      return null
+    }
+  }
+
+  private writeCachedConfig(config: RuntimeConfig): void {
+    if (typeof localStorage === 'undefined') return
+    try {
+      localStorage.setItem(CONFIG_CACHE_KEY, JSON.stringify({ at: Date.now(), data: config }))
+    } catch {
+      // storage quota · ignore
+    }
+  }
+
+  private log(...args: unknown[]): void {
+    if (this.config?.debug && typeof console !== 'undefined') {
+      console.warn('[holdy]', ...args)
+    }
+  }
+}
+
+export const Holdy = new HoldySdk()
+
+export type {
+  AccountIdentity,
+  CanonicalPrimitive,
+  DecisionResult,
+  DecisionListener,
+  HoldyConfig,
+  IdentifyOptions,
+  InterventionPayload,
+  OutcomeValue,
+  RuntimeConfig,
+  ThemeConfig,
+  TrackOptions,
+  UserIdentity,
+} from './types'
+
+export default Holdy

package/src/outcome.ts

@@ -0,0 +1,51 @@
+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)
+  }
+}