@holdyapp/sdk 1.1.0 → 1.6.0

package/src/run.ts

@@ -0,0 +1,80 @@
+/**
+ * Execução como unidade de trabalho (source: sdk_server).
+ *
+ * Produto de agente não tem sessão de browser: o trabalho roda no servidor,
+ * por API, em background. Pra Holdy dizer "começou e concluiu na mesma
+ * execução" e dividir recurso por resultado entregue, todos os eventos de uma
+ * tarefa carregam a mesma `ai_run_id` — a chave que o composer usa por padrão
+ * no grão de execução (lib/knowledge/compose-definition.ts).
+ *
+ * Não inventa vocabulário: início e fim saem com o nome que o cliente deu à
+ * execução (`support_agent.started`), e todo passo no meio é nome dele. O
+ * retorno passa direto e o erro propaga; só o NOME do erro vira propriedade,
+ * porque a mensagem carrega dado do cliente com frequência demais.
+ */
+
+import type { Properties, TrackOverrides } from './types'
+
+export interface RunOptions {
+  /** Nome da execução no vocabulário do produto, ex.: 'support_agent'. */
+  name: string
+  /** Conta (id externo) dona da execução. */
+  accountKey?: string
+  userId?: string
+  /** Chave própria (trace id do agente); ausente = gerada aqui. */
+  runId?: string
+  /** Propriedades repetidas em todos os eventos da execução. */
+  properties?: Properties
+}
+
+export interface RunHandle {
+  /** A chave que agrupa tudo desta execução. */
+  id: string
+  /** Um passo dentro da execução, já carimbado com ai_run_id. */
+  track(event: string, properties?: Properties): void
+}
+
+export type TrackFn = (name: string, properties?: Properties, overrides?: TrackOverrides) => void
+
+export function newRunId(): string {
+  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto
+  if (typeof c?.randomUUID === 'function') return c.randomUUID()
+  return `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`
+}
+
+export function runEventName(name: string, suffix: 'started' | 'completed' | 'failed'): string {
+  const base = name.trim().replace(/\.$/, '')
+  return `${base || 'run'}.${suffix}`
+}
+
+export async function withRun<T>(
+  track: TrackFn,
+  opts: RunOptions,
+  fn: (run: RunHandle) => Promise<T> | T,
+): Promise<T> {
+  if (!opts || !opts.name) throw new Error('[holdy] run: name is required')
+
+  const id = opts.runId && opts.runId.length > 0 ? opts.runId : newRunId()
+  const base: Properties = { ...(opts.properties ?? {}), ai_run_id: id }
+  const overrides: TrackOverrides = {
+    ...(opts.accountKey ? { accountKey: opts.accountKey } : {}),
+    ...(opts.userId ? { userId: opts.userId } : {}),
+  }
+  const emit = (event: string, properties?: Properties) =>
+    track(event, { ...base, ...(properties ?? {}), ai_run_id: id }, overrides)
+
+  const startedAt = Date.now()
+  emit(runEventName(opts.name, 'started'))
+
+  try {
+    const result = await fn({ id, track: emit })
+    emit(runEventName(opts.name, 'completed'), { duration_ms: Date.now() - startedAt })
+    return result
+  } catch (err) {
+    emit(runEventName(opts.name, 'failed'), {
+      duration_ms: Date.now() - startedAt,
+      error: err instanceof Error ? err.name : 'Error',
+    })
+    throw err
+  }
+}

package/src/server.ts

@@ -7,13 +7,30 @@
  */
 
 import { HoldyCore } from './core'
+import { withRun, type RunHandle, type RunOptions } from './run'
 import type { HoldyOptions } from './types'
 
 export class Holdy extends HoldyCore {
   constructor(opts: HoldyOptions) {
     super('sdk_server', opts)
   }
+
+  /**
+   * Executa `fn` como UMA execução de agente: todo evento lá dentro carrega a
+   * mesma `ai_run_id`, e `<name>.started` / `.completed` / `.failed` saem
+   * sozinhos.
+   *
+   *   await holdy.run({ name: 'support_agent', accountKey: 'acme' }, async (run) => {
+   *     run.track('ticket_drafted', { ai_tokens: 1200, ai_cost_usd: 0.02 })
+   *     return resolveTicket(ticket)
+   *   })
+   */
+  run<T>(opts: RunOptions, fn: (run: RunHandle) => Promise<T> | T): Promise<T> {
+    return withRun((name, properties, overrides) => this.track(name, properties, overrides), opts, fn)
+  }
 }
 
 export { HoldyCore, DEFAULT_BASE_URL } from './core'
 export type { HoldyOptions, Properties, TrackOverrides, CanonicalEvent } from './types'
+export { newRunId, runEventName } from './run'
+export type { RunHandle, RunOptions } from './run'

package/src/skeleton.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, it } from 'vitest'
+import { collectSkeleton, describeSkeletonElement, fnv1a, SKELETON_MAX_ELEMENTS, type SkeletonElementLike } from './skeleton'
+
+function el(tag: string, attrs: Record<string, string> = {}, rect = { x: 10, y: 20, width: 100, height: 40 }): SkeletonElementLike {
+  return {
+    tagName: tag.toUpperCase(),
+    getAttribute: (name) => attrs[name] ?? null,
+    getBoundingClientRect: () => rect,
+  }
+}
+
+const viewport = { width: 1000, height: 2000, scrollY: 0 }
+
+describe('fnv1a', () => {
+  it('é estável e conhecido', () => {
+    expect(fnv1a('')).toBe('811c9dc5')
+    expect(fnv1a('a')).toBe('e40c292c')
+    expect(fnv1a('holdy')).toBe(fnv1a('holdy'))
+  })
+})
+
+describe('describeSkeletonElement', () => {
+  it('guarda tag, role, data-testid, name, aria-label e tipo, nunca texto nem valor', () => {
+    const out = describeSkeletonElement(
+      el('input', { type: 'Email', name: 'email', 'aria-label': '  Seu   e-mail ', value: 'segredo@x.com', placeholder: 'Digite' }),
+      viewport,
+    )
+    expect(out).toEqual({ t: 'input', n: 'email', l: 'Seu e-mail', k: 'email', b: [1, 1, 10, 2] })
+    expect(JSON.stringify(out)).not.toContain('segredo')
+  })
+
+  it('sem viewport não há geometria', () => {
+    expect(describeSkeletonElement(el('button', { 'data-testid': 'continue' }), null)).toEqual({ t: 'button', id: 'continue' })
+  })
+})
+
+describe('collectSkeleton', () => {
+  const root = (items: SkeletonElementLike[]) => ({ querySelectorAll: () => items })
+
+  it('o hash ignora a geometria e muda com a estrutura', () => {
+    const a = collectSkeleton(root([el('button', { 'data-testid': 'go' }, { x: 0, y: 0, width: 50, height: 20 })]), '/x', viewport)
+    const b = collectSkeleton(root([el('button', { 'data-testid': 'go' }, { x: 300, y: 900, width: 80, height: 30 })]), '/x', viewport)
+    const c = collectSkeleton(root([el('button', { 'data-testid': 'stop' })]), '/x', viewport)
+    expect(a.hash).toBe(b.hash)
+    expect(a.hash).not.toBe(c.hash)
+    expect(a.elements[0].b).toEqual([0, 0, 5, 1])
+  })
+
+  it('deixa fora input hidden e elemento sem tamanho, e conta o total antes do teto', () => {
+    const many = Array.from({ length: SKELETON_MAX_ELEMENTS + 10 }, (_, i) => el('a', { href: `/p/${i}` }))
+    const out = collectSkeleton(
+      root([el('input', { type: 'hidden', name: 'csrf' }), el('button', {}, { x: 0, y: 0, width: 0, height: 0 }), ...many]),
+      '/lista',
+      viewport,
+    )
+    expect(out.count).toBe(SKELETON_MAX_ELEMENTS + 10)
+    expect(out.elements).toHaveLength(SKELETON_MAX_ELEMENTS)
+    expect(out.elements.every((e) => e.t === 'a')).toBe(true)
+  })
+})

package/src/skeleton.ts

@@ -0,0 +1,173 @@
+export const SKELETON_SELECTOR =
+  'a[href], button, input, select, textarea, [role="button"], [role="link"], [role="tab"], [role="menuitem"], [role="checkbox"], [role="radio"], [role="switch"], [data-testid]'
+export const SKELETON_MAX_ELEMENTS = 80
+export const SKELETON_DELAY_MS = 1500
+const SENT_STORAGE_KEY = 'holdy_skeletons'
+const SENT_STORAGE_MAX = 200
+
+export interface SkeletonRect {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface SkeletonElementLike {
+  tagName: string
+  getAttribute(name: string): string | null
+  getBoundingClientRect?(): SkeletonRect
+}
+
+export interface SkeletonRootLike {
+  querySelectorAll(selector: string): ArrayLike<SkeletonElementLike>
+}
+
+export interface SkeletonViewport {
+  width: number
+  height: number
+  scrollY: number
+}
+
+export interface SkeletonElement {
+  t: string
+  r?: string
+  id?: string
+  n?: string
+  l?: string
+  k?: string
+  b?: [number, number, number, number]
+}
+
+export interface PageSkeleton {
+  path: string
+  hash: string
+  count: number
+  elements: SkeletonElement[]
+}
+
+export function fnv1a(input: string): string {
+  let hash = 0x811c9dc5
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i)
+    hash = Math.imul(hash, 0x01000193) >>> 0
+  }
+  return hash.toString(16).padStart(8, '0')
+}
+
+function attr(el: SkeletonElementLike, name: string, max: number): string | undefined {
+  const value = el.getAttribute(name)
+  if (!value) return undefined
+  const trimmed = value.replace(/\s+/g, ' ').trim().slice(0, max)
+  return trimmed || undefined
+}
+
+function isVisible(el: SkeletonElementLike): boolean {
+  if (!el.getBoundingClientRect) return true
+  const rect = el.getBoundingClientRect()
+  return rect.width > 0 && rect.height > 0
+}
+
+function relativeBox(rect: SkeletonRect, viewport: SkeletonViewport): [number, number, number, number] {
+  const pct = (value: number, base: number) => (base > 0 ? Math.max(0, Math.min(100, Math.round((value / base) * 100))) : 0)
+  return [pct(rect.x, viewport.width), pct(rect.y + viewport.scrollY, viewport.height), pct(rect.width, viewport.width), pct(rect.height, viewport.height)]
+}
+
+export function describeSkeletonElement(el: SkeletonElementLike, viewport: SkeletonViewport | null): SkeletonElement {
+  const out: SkeletonElement = { t: el.tagName.toLowerCase() }
+  const role = attr(el, 'role', 40)
+  if (role) out.r = role
+  const testid = attr(el, 'data-testid', 80)
+  if (testid) out.id = testid
+  const name = attr(el, 'name', 80)
+  if (name) out.n = name
+  const label = attr(el, 'aria-label', 80)
+  if (label) out.l = label
+  if (out.t === 'input' || out.t === 'button') {
+    const type = attr(el, 'type', 20)
+    if (type) out.k = type.toLowerCase()
+  }
+  if (viewport && el.getBoundingClientRect) out.b = relativeBox(el.getBoundingClientRect(), viewport)
+  return out
+}
+
+export function collectSkeleton(root: SkeletonRootLike, path: string, viewport: SkeletonViewport | null): PageSkeleton {
+  const found = root.querySelectorAll(SKELETON_SELECTOR)
+  const visible: SkeletonElementLike[] = []
+  for (let i = 0; i < found.length; i++) {
+    const el = found[i]
+    if (el.tagName.toLowerCase() === 'input' && (el.getAttribute('type') ?? '').toLowerCase() === 'hidden') continue
+    if (!isVisible(el)) continue
+    visible.push(el)
+  }
+  const elements = visible.slice(0, SKELETON_MAX_ELEMENTS).map((el) => describeSkeletonElement(el, viewport))
+  const structural = elements.map(({ b: _b, ...rest }) => rest)
+  return { path, hash: fnv1a(JSON.stringify(structural)), count: visible.length, elements }
+}
+
+export interface SkeletonCaptureOptions {
+  onSkeleton: (skeleton: PageSkeleton) => void
+  delayMs?: number
+}
+
+export interface SkeletonCapture {
+  onNavigate: (path: string) => void
+  teardown: () => void
+}
+
+function loadSent(): Set<string> {
+  try {
+    const raw = sessionStorage.getItem(SENT_STORAGE_KEY)
+    const list = raw ? (JSON.parse(raw) as unknown) : []
+    return new Set(Array.isArray(list) ? list.filter((x): x is string => typeof x === 'string') : [])
+  } catch {
+    return new Set()
+  }
+}
+
+function saveSent(sent: Set<string>): void {
+  try {
+    sessionStorage.setItem(SENT_STORAGE_KEY, JSON.stringify([...sent].slice(-SENT_STORAGE_MAX)))
+  } catch {
+    return
+  }
+}
+
+export function installSkeletonCapture(opts: SkeletonCaptureOptions): SkeletonCapture {
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return { onNavigate: () => undefined, teardown: () => undefined }
+  }
+  const delay = opts.delayMs ?? SKELETON_DELAY_MS
+  const sent = loadSent()
+  let pending: ReturnType<typeof setTimeout> | null = null
+
+  const capture = (path: string): void => {
+    pending = null
+    if (location.pathname !== path) return
+    try {
+      const viewport: SkeletonViewport = {
+        width: window.innerWidth,
+        height: Math.max(document.documentElement.scrollHeight, window.innerHeight),
+        scrollY: window.scrollY,
+      }
+      const skeleton = collectSkeleton(document, path, viewport)
+      const key = `${path}:${skeleton.hash}`
+      if (sent.has(key)) return
+      sent.add(key)
+      saveSent(sent)
+      opts.onSkeleton(skeleton)
+    } catch {
+      return
+    }
+  }
+
+  return {
+    onNavigate: (path: string) => {
+      if (pending) clearTimeout(pending)
+      pending = setTimeout(() => capture(path), delay)
+    },
+    teardown: () => {
+      if (pending) clearTimeout(pending)
+      pending = null
+    },
+  }
+}

package/src/types.ts

@@ -12,6 +12,8 @@ export interface CanonicalEvent {
   event: string
   occurred_at: string
   source: 'sdk_web' | 'sdk_server'
+  /** Id do evento gerado no SDK · torna o reenvio de um lote idempotente. */
+  external_id?: string
   user_id?: string
   anonymous_id?: string
   properties: Properties

package/src/web.ts

@@ -13,7 +13,10 @@
 
 import { HoldyCore } from './core'
 import { installAutoCapture, type NavigationKind } from './auto-capture'
+import { installFrictionCapture, type FrictionCapture, type FrictionCaptureOptions } from './friction'
+import { installSkeletonCapture, type SkeletonCapture } from './skeleton'
 import { buildWebContext } from './web-context'
+import { installProductChanges, type ProductChangesHandle } from './changes'
 import type { HoldyOptions, Properties } from './types'
 
 const ANON_STORAGE_KEY = 'holdy_anon_id'
@@ -24,10 +27,34 @@ export interface HoldyWebOptions extends HoldyOptions {
    * Desligue só se o produto já chama `page()` na mão em cada tela.
    */
   autoCapture?: boolean
+  /**
+   * Capturar fricção sozinho · default true. Emite `$dead_click`, `$rage_click`,
+   * `$form_abandon`, `$js_error`, `$slow_request`, `$nav_loop` e `$http_error`
+   * (requisição com status ≥ 400 ou sem resposta, e a própria página que abre
+   * com erro) — eventos determinísticos, sem DOM nem replay. Objeto ajusta os
+   * limiares; a URL da Holdy nunca conta como erro.
+   */
+  friction?: boolean | Omit<FrictionCaptureOptions, 'onFriction'>
+  /**
+   * Aplicar as mudanças de texto e dica que a org pôs no ar na Holdy · default
+   * true. Parte das contas fica de fora por sorteio pra medir; sem conta
+   * identificada (`group()` ou `accountKey`) nada é aplicado.
+   */
+  productChanges?: boolean
+  /**
+   * Mandar o esqueleto da página · default true. Uma vez por (rota, estrutura)
+   * por aba: `$page_skeleton` com os elementos interativos (tag, role,
+   * data-testid, name, aria-label, tipo, posição relativa). Sem texto livre,
+   * sem valor de input, sem pixel.
+   */
+  skeleton?: boolean
 }
 
 export class HoldyWeb extends HoldyCore {
   private teardownAutoCapture: (() => void) | null = null
+  private friction: FrictionCapture | null = null
+  private changes: ProductChangesHandle | null = null
+  private skeleton: SkeletonCapture | null = null
 
   constructor(opts: HoldyWebOptions) {
     super('sdk_web', opts)
@@ -40,9 +67,40 @@ export class HoldyWeb extends HoldyCore {
       })
     }
 
+    if (opts.friction !== false) {
+      const frictionOpts = typeof opts.friction === 'object' ? opts.friction : {}
+      this.friction = installFrictionCapture({
+        ...frictionOpts,
+        ignoreUrls: [...(frictionOpts.ignoreUrls ?? []), this.baseUrl],
+        onFriction: (signal) => this.track(`$${signal.kind}`, signal.properties),
+      })
+    }
+
+    if (opts.skeleton !== false) {
+      this.skeleton = installSkeletonCapture({
+        onSkeleton: (skeleton) => this.track('$page_skeleton', { ...skeleton }),
+      })
+    }
+
     if (opts.autoCapture !== false) {
       this.teardownAutoCapture = installAutoCapture({
-        onNavigate: (kind: NavigationKind) => this.page(undefined, { navigation: kind }),
+        onNavigate: (kind: NavigationKind) => {
+          this.page(undefined, { navigation: kind })
+          const path = typeof location !== 'undefined' ? location.pathname : '/'
+          this.friction?.onNavigate(path)
+          this.changes?.onNavigate()
+          this.skeleton?.onNavigate(path)
+        },
+      })
+    }
+
+    if (opts.productChanges !== false && typeof window !== 'undefined') {
+      this.changes = installProductChanges({
+        baseUrl: this.baseUrl,
+        apiKey: this.apiKey,
+        getAccountKey: () => this.accountKey,
+        track: (name, properties) => this.track(name, properties),
+        debug: opts.debug,
       })
     }
   }
@@ -62,6 +120,11 @@ export class HoldyWeb extends HoldyCore {
     })
   }
 
+  override group(accountKey: string, traits?: Properties): void {
+    super.group(accountKey, traits)
+    this.changes?.onNavigate()
+  }
+
   reset(): void {
     this.userId = null
     this.accountKey = null
@@ -71,12 +134,19 @@ export class HoldyWeb extends HoldyCore {
       // storage indisponível (SSR/privacy mode) — ok
     }
     this.anonymousId = resolveAnonymousId()
+    this.changes?.onNavigate()
   }
 
   /** Flush final + desinstala o auto-capture (devolve `history` ao original). */
   override async shutdown(): Promise<void> {
     this.teardownAutoCapture?.()
     this.teardownAutoCapture = null
+    this.friction?.teardown()
+    this.friction = null
+    this.changes?.teardown()
+    this.changes = null
+    this.skeleton?.teardown()
+    this.skeleton = null
     await super.shutdown()
   }