@holdyapp/sdk 0.2.0

package/src/store.ts

@@ -0,0 +1,106 @@
+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 class InterventionStore {
+  private readonly tooltipsByAnchor = new Map<string, ActiveSlot>()
+  private readonly spotlightsByAnchor = new Map<string, ActiveSlot>()
+  private banner: ActiveSlot | null = null
+  private modal: ActiveSlot | null = null
+  private checklist: ActiveSlot | null = null
+  private cta: ActiveSlot | null = null
+
+  /** 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 {
+    const slot: ActiveSlot = { decisionId, confidence, kind, dismiss }
+
+    if (kind === 'tooltip') {
+      const key = anchorSelector ?? '__no_anchor__'
+      const prev = this.tooltipsByAnchor.get(key)
+      if (prev && prev.confidence >= confidence) return slot
+      this.tooltipsByAnchor.set(key, slot)
+      return prev ?? null
+    }
+
+    if (kind === 'spotlight') {
+      const key = anchorSelector ?? '__no_anchor__'
+      const prev = this.spotlightsByAnchor.get(key)
+      if (prev && prev.confidence >= confidence) return slot
+      this.spotlightsByAnchor.set(key, slot)
+      return prev ?? null
+    }
+
+    if (kind === 'banner') {
+      const prev = this.banner
+      if (prev && prev.confidence >= confidence) return slot
+      this.banner = slot
+      return prev ?? null
+    }
+
+    if (kind === 'modal') {
+      const prev = this.modal
+      if (prev && prev.confidence >= confidence) return slot
+      this.modal = slot
+      return prev ?? null
+    }
+
+    if (kind === 'checklist') {
+      const prev = this.checklist
+      if (prev && prev.confidence >= confidence) return slot
+      this.checklist = slot
+      return prev ?? null
+    }
+
+    if (kind === 'cta') {
+      const prev = this.cta
+      if (prev && prev.confidence >= confidence) return slot
+      this.cta = slot
+      return prev ?? null
+    }
+
+    return null
+  }
+
+  release(decisionId: string): void {
+    if (this.banner?.decisionId === decisionId) this.banner = null
+    if (this.modal?.decisionId === decisionId) this.modal = null
+    if (this.checklist?.decisionId === decisionId) this.checklist = null
+    if (this.cta?.decisionId === decisionId) this.cta = null
+    for (const map of [this.tooltipsByAnchor, this.spotlightsByAnchor]) {
+      for (const [k, slot] of map) {
+        if (slot.decisionId === decisionId) {
+          map.delete(k)
+          break
+        }
+      }
+    }
+  }
+}

package/src/transport.ts

@@ -0,0 +1,182 @@
+import type {
+  AccountIdentity,
+  CanonicalPrimitive,
+  DecisionResult,
+  HoldyConfig,
+  RuntimeConfig,
+  UserIdentity,
+} from './types'
+import { EventQueue } from './queue'
+
+const DEFAULT_API_URL = 'https://app.holdy.com.br/api/v1'
+
+export class Transport {
+  private readonly apiKey: string
+  private readonly apiUrl: string
+  private readonly debug: boolean
+  private readonly queue: EventQueue
+
+  constructor(config: HoldyConfig) {
+    this.apiKey = config.apiKey
+    this.apiUrl = (config.apiUrl ?? DEFAULT_API_URL).replace(/\/$/, '')
+    this.debug = config.debug ?? false
+    this.queue = new EventQueue(
+      (body) => this.sendBatch(body.events),
+      (...args) => this.log(...args),
+    )
+  }
+
+  private headers(): Record<string, string> {
+    return {
+      'content-type': 'application/json',
+      authorization: `Bearer ${this.apiKey}`,
+    }
+  }
+
+  async fetchRuntimeConfig(): Promise<RuntimeConfig | null> {
+    try {
+      const res = await fetch(`${this.apiUrl}/runtime/config`, {
+        method: 'GET',
+        headers: this.headers(),
+        credentials: 'omit',
+        mode: 'cors',
+      })
+      if (!res.ok) {
+        this.log('runtime/config failed', res.status)
+        return null
+      }
+      return (await res.json()) as RuntimeConfig
+    } catch (e) {
+      this.log('runtime/config error', e)
+      return null
+    }
+  }
+
+  async 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> {
+    try {
+      const res = await fetch(`${this.apiUrl}/decisions/evaluate`, {
+        method: 'POST',
+        headers: this.headers(),
+        body: JSON.stringify({ consumer: 'ui', ...input }),
+        credentials: 'omit',
+        mode: 'cors',
+      })
+      if (!res.ok) {
+        this.log('decisions/evaluate failed', res.status)
+        return null
+      }
+      return (await res.json()) as DecisionResult
+    } catch (e) {
+      this.log('decisions/evaluate error', e)
+      return 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 {
+    if (events.length === 0) return
+    void this.queue.enqueue(events)
+  }
+
+  /**
+   * 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 async sendBatch(events: unknown[]): Promise<boolean> {
+    try {
+      const res = await fetch(`${this.apiUrl}/events/batch`, {
+        method: 'POST',
+        headers: this.headers(),
+        body: JSON.stringify({ events }),
+        credentials: 'omit',
+        mode: 'cors',
+        keepalive: true,
+      })
+      return res.ok
+    } catch (e) {
+      this.log('events/batch network error', e)
+      return false
+    }
+  }
+
+  /**
+   * 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.
+   */
+  async upsertAccount(payload: {
+    account: AccountIdentity
+    user?: UserIdentity
+  }): Promise<{ account_id: string; account_user_id: string | null } | null> {
+    try {
+      const res = await fetch(`${this.apiUrl}/accounts/upsert`, {
+        method: 'POST',
+        headers: this.headers(),
+        body: JSON.stringify(payload),
+        credentials: 'omit',
+        mode: 'cors',
+        keepalive: true,
+      })
+      if (!res.ok) {
+        this.log('accounts/upsert failed', res.status)
+        return null
+      }
+      return (await res.json()) as { account_id: string; account_user_id: string | null }
+    } catch (e) {
+      this.log('accounts/upsert error', e)
+      return null
+    }
+  }
+
+  reportOutcome(
+    decisionId: string,
+    outcome: 'executed' | 'dismissed' | 'converted' | 'no_show' | 'failed',
+    metadata?: Record<string, unknown>,
+  ): void {
+    const url = `${this.apiUrl}/decisions/${encodeURIComponent(decisionId)}/outcome`
+    fetch(url, {
+      method: 'POST',
+      headers: this.headers(),
+      body: JSON.stringify({ outcome, metadata }),
+      credentials: 'omit',
+      mode: 'cors',
+      keepalive: true,
+    }).catch((e) => this.log('decisions/outcome error', e))
+  }
+
+  private log(...args: unknown[]): void {
+    if (this.debug && typeof console !== 'undefined') {
+      console.warn('[holdy]', ...args)
+    }
+  }
+
+  destroy(): void {
+    this.queue.destroy()
+  }
+}

package/src/types.ts

@@ -0,0 +1,173 @@
+// 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'
+
+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 const DEFAULT_THEME: ThemeConfig = {
+  primary_color: '#ca2121',
+  font_family: 'inherit',
+  border_radius_px: 8,
+  position_offset_px: 8,
+}
+
+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