@holdyapp/sdk 0.2.0 → 1.0.0

package/src/index.ts

@@ -1,427 +1,4 @@
-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
+export { Holdy, HoldyCore, DEFAULT_BASE_URL } from './server'
+export { HoldyWeb, initHoldy } from './web'
+export type { HoldyWebOptions } from './web'
+export type { HoldyOptions, Properties, TrackOverrides, CanonicalEvent } from './types'

package/src/server.ts

@@ -0,0 +1,19 @@
+/**
+ * @holdyapp/sdk (server) · Node/Edge (source: sdk_server).
+ *
+ * Stateless por default: user_id/accountKey vão por chamada em overrides.
+ * identify()/group() de sessão existem mas em server multi-tenant prefira
+ * overrides — estado compartilhado entre requests vaza identidade.
+ */
+
+import { HoldyCore } from './core'
+import type { HoldyOptions } from './types'
+
+export class Holdy extends HoldyCore {
+  constructor(opts: HoldyOptions) {
+    super('sdk_server', opts)
+  }
+}
+
+export { HoldyCore, DEFAULT_BASE_URL } from './core'
+export type { HoldyOptions, Properties, TrackOverrides, CanonicalEvent } from './types'

package/src/types.ts

@@ -1,173 +1,49 @@
-// Public types — keep in sync with backend canonical-v1.ts + decisions/engine.ts.
-
-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'
+/**
+ * Tipos públicos do @holdyapp/sdk (entry-contract.md §2 + §6).
+ *
+ * Envelope idêntico ao CanonicalEventInputSchema do servidor — o SDK nunca
+ * inventa campo. account_id (uuid Holdy) não existe aqui: a chave do cliente
+ * viaja em context.account_external_id e a Data layer resolve (regra 4).
+ */
 
-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 type Properties = Record<string, unknown>
 
-export interface ThemeConfig {
-  primary_color: string
-  font_family: string
-  border_radius_px: number
-  position_offset_px: number
+export interface CanonicalEvent {
+  event: string
+  occurred_at: string
+  source: 'sdk_web' | 'sdk_server'
+  user_id?: string
+  anonymous_id?: string
+  properties: Properties
+  context?: Properties
 }
 
-export const DEFAULT_THEME: ThemeConfig = {
-  primary_color: '#ca2121',
-  font_family: 'inherit',
-  border_radius_px: 8,
-  position_offset_px: 8,
-}
-
-export interface HoldyConfig {
+export interface HoldyOptions {
+  /** API key `hol_{env}_...` com scope events:write. */
   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
+  /** Override · default https://holdy.chat/api/v1 */
+  baseUrl?: string
+  /** Flush automático quando a fila atinge este tamanho · default 20. */
+  flushAt?: number
+  /** Flush automático a cada N ms · default 5000. 0 desliga o timer. */
+  flushIntervalMs?: number
   /**
-   * 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.
+   * Chave da account do cliente (`context.account_external_id`). Define o
+   * vínculo sem emitir evento — `group()` continua sendo a chamada pra
+   * declarar a account COM traits.
    */
-  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'
+  accountKey?: string
+  /** Logs de debug no console. */
+  debug?: boolean
 }
 
-export interface IdentifyOptions {
-  /** ID interno Holdy (UUID) · opcional · usado pra retro-compat. */
-  accountId?: string
+export interface TrackOverrides {
+  /** Server-side: end-user do evento (stateless por chamada). */
   userId?: string
-  sessionId?: string
-  /** Metadata rica · gera best-effort upsert em /v1/accounts/upsert. */
-  account?: AccountIdentity
-  user?: UserIdentity
+  /** Server-side: chave de account do cliente (context.account_external_id). */
+  accountKey?: string
+  /** Timestamp do evento · default agora. */
+  occurredAt?: Date | string
+  /** Metadata adicional pro context. */
+  context?: Properties
 }
-
-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