@holdyapp/sdk 1.0.1 → 1.5.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/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,9 @@
 
 import { HoldyCore } from './core'
 import { installAutoCapture, type NavigationKind } from './auto-capture'
+import { installFrictionCapture, type FrictionCapture, type FrictionCaptureOptions } from './friction'
 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 +26,26 @@ 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
 }
 
 export class HoldyWeb extends HoldyCore {
   private teardownAutoCapture: (() => void) | null = null
+  private friction: FrictionCapture | null = null
+  private changes: ProductChangesHandle | null = null
 
   constructor(opts: HoldyWebOptions) {
     super('sdk_web', opts)
@@ -40,9 +58,32 @@ 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.autoCapture !== false) {
       this.teardownAutoCapture = installAutoCapture({
-        onNavigate: (kind: NavigationKind) => this.page(undefined, { navigation: kind }),
+        onNavigate: (kind: NavigationKind) => {
+          this.page(undefined, { navigation: kind })
+          this.friction?.onNavigate(typeof location !== 'undefined' ? location.pathname : '/')
+          this.changes?.onNavigate()
+        },
+      })
+    }
+
+    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 +103,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 +117,17 @@ 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
     await super.shutdown()
   }
 
@@ -101,7 +152,16 @@ let singleton: HoldyWeb | null = null
 
 /** Init idempotente — segunda chamada retorna a instância existente. */
 export function initHoldy(opts: HoldyWebOptions): HoldyWeb {
-  if (!singleton) singleton = new HoldyWeb(opts)
+  if (!singleton) {
+    singleton = new HoldyWeb(opts)
+    // Instância no window: track() inserido pelo `--instrument` do CLI não
+    // precisa importar nada nem saber onde o init mora. Mesma superfície do
+    // loader por script tag, então o snippet é um só nos dois caminhos.
+    if (typeof window !== 'undefined') {
+      const w = window as unknown as { Holdy?: HoldyWeb }
+      if (!w.Holdy) w.Holdy = singleton
+    }
+  }
   return singleton
 }