@holdyapp/sdk 1.1.0 → 1.6.0

package/dist/server.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../src/server.ts", "../src/core.ts"],
-  "sourcesContent": ["/**\n * @holdyapp/sdk (server) \u00B7 Node/Edge (source: sdk_server).\n *\n * Stateless por default: user_id/accountKey v\u00E3o por chamada em overrides.\n * identify()/group() de sess\u00E3o existem mas em server multi-tenant prefira\n * overrides \u2014 estado compartilhado entre requests vaza identidade.\n */\n\nimport { HoldyCore } from './core'\nimport type { HoldyOptions } from './types'\n\nexport class Holdy extends HoldyCore {\n  constructor(opts: HoldyOptions) {\n    super('sdk_server', opts)\n  }\n}\n\nexport { HoldyCore, DEFAULT_BASE_URL } from './core'\nexport type { HoldyOptions, Properties, TrackOverrides, CanonicalEvent } from './types'\n", "/**\n * Core do @holdyapp/sdk \u00B7 fila + flush pra POST /api/v1/events/bulk.\n *\n * Retry de batch inteiro \u00E9 seguro (partial accept + dedupe server-side).\n * Fila \u00E9 bounded: acima de MAX_QUEUE dropa os mais antigos (telemetria nunca\n * derruba o app do cliente \u2014 nenhum m\u00E9todo p\u00FAblico lan\u00E7a).\n */\n\nimport type { CanonicalEvent, HoldyOptions, Properties, TrackOverrides } from './types'\n\nexport const DEFAULT_BASE_URL = 'https://holdy.chat/api/v1'\nconst DEFAULT_FLUSH_AT = 20\nconst DEFAULT_FLUSH_INTERVAL_MS = 5000\nconst MAX_QUEUE = 1000\nconst BULK_LIMIT = 500\n\nexport class HoldyCore {\n  private readonly apiKey: string\n  private readonly baseUrl: string\n  private readonly flushAt: number\n  private readonly debug: boolean\n  private readonly source: 'sdk_web' | 'sdk_server'\n\n  private queue: CanonicalEvent[] = []\n  private timer: ReturnType<typeof setInterval> | null = null\n  private flushing: Promise<void> | null = null\n\n  protected userId: string | null = null\n  protected anonymousId: string | null = null\n  protected accountKey: string | null = null\n\n  constructor(source: 'sdk_web' | 'sdk_server', opts: HoldyOptions) {\n    this.source = source\n    this.apiKey = opts.apiKey\n    this.accountKey = opts.accountKey ?? null\n    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/$/, '')\n    this.flushAt = Math.max(1, opts.flushAt ?? DEFAULT_FLUSH_AT)\n    this.debug = opts.debug ?? false\n\n    const intervalMs = opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS\n    if (intervalMs > 0) {\n      this.timer = setInterval(() => void this.flush(), intervalMs)\n      // Node: n\u00E3o segura o processo vivo s\u00F3 pelo timer do SDK.\n      if (typeof (this.timer as { unref?: () => void }).unref === 'function') {\n        ;(this.timer as unknown as { unref: () => void }).unref()\n      }\n    }\n  }\n\n  track(name: string, properties?: Properties, overrides?: TrackOverrides): void {\n    if (!name || typeof name !== 'string') return\n\n    const userId = overrides?.userId ?? this.userId ?? undefined\n    const accountKey = overrides?.accountKey ?? this.accountKey ?? undefined\n    const occurredAt = overrides?.occurredAt\n      ? new Date(overrides.occurredAt).toISOString()\n      : new Date().toISOString()\n\n    // Ordem: ambiente observado pelo SDK \u2192 context da chamada \u2192 carrier de\n    // account. O que o caller passou vence o inferido; o carrier vence tudo,\n    // porque \u00E9 o que a Data layer usa pra resolver a conta.\n    const context: Properties = {\n      ...this.environmentContext(),\n      ...(overrides?.context ?? {}),\n    }\n    if (accountKey) context.account_external_id = accountKey\n\n    const event: CanonicalEvent = {\n      event: name,\n      occurred_at: occurredAt,\n      source: this.source,\n      ...(userId ? { user_id: userId } : {}),\n      ...(this.anonymousId ? { anonymous_id: this.anonymousId } : {}),\n      properties: properties ?? {},\n      ...(Object.keys(context).length > 0 ? { context } : {}),\n    }\n\n    this.queue.push(event)\n    if (this.queue.length > MAX_QUEUE) this.queue.splice(0, this.queue.length - MAX_QUEUE)\n    if (this.queue.length >= this.flushAt) void this.flush()\n  }\n\n  identify(userId: string, traits?: Properties): void {\n    if (!userId || typeof userId !== 'string') return\n    this.userId = userId\n    this.track('$identify', traits ?? {})\n  }\n\n  group(accountKey: string, traits?: Properties): void {\n    if (!accountKey || typeof accountKey !== 'string') return\n    this.accountKey = accountKey\n    this.track('$group', traits ?? {})\n  }\n\n  /** Drena a fila. Nunca lan\u00E7a \u2014 falha re-enfileira e loga em debug. */\n  async flush(): Promise<void> {\n    // Serializa flushes concorrentes (timer + flushAt + manual).\n    if (this.flushing) return this.flushing\n    if (this.queue.length === 0) return\n\n    this.flushing = this.drain().finally(() => {\n      this.flushing = null\n    })\n    return this.flushing\n  }\n\n  /** Flush final + para o timer. Chamar em shutdown do server / unload do web. */\n  async shutdown(): Promise<void> {\n    if (this.timer) {\n      clearInterval(this.timer)\n      this.timer = null\n    }\n    await this.flush()\n  }\n\n  private async drain(): Promise<void> {\n    while (this.queue.length > 0) {\n      const batch = this.queue.splice(0, BULK_LIMIT)\n      const ok = await this.send(batch)\n      if (!ok) {\n        // Devolve pra frente da fila e para \u2014 pr\u00F3ximo flush re-tenta (dedupe-safe).\n        this.queue.unshift(...batch)\n        return\n      }\n    }\n  }\n\n  private async send(events: CanonicalEvent[]): Promise<boolean> {\n    try {\n      const res = await fetch(`${this.baseUrl}/events/bulk`, {\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({ events }),\n        ...(this.source === 'sdk_web' ? { keepalive: true } : {}),\n      })\n      if (!res.ok) {\n        // 4xx: batch estruturalmente inv\u00E1lido n\u00E3o re-tenta (evita loop infinito).\n        if (res.status >= 400 && res.status < 500) {\n          this.log(`bulk rejected ${res.status} \u00B7 batch dropped`)\n          return true\n        }\n        this.log(`bulk failed ${res.status} \u00B7 will retry`)\n        return false\n      }\n      return true\n    } catch (err) {\n      this.log(`bulk network error: ${(err as Error).message} \u00B7 will retry`)\n      return false\n    }\n  }\n\n  private log(msg: string): void {\n    if (this.debug) console.warn(`[holdy] ${msg}`)\n  }\n\n  /**\n   * Ambiente que o SDK observa sozinho (url, referrer, browser, utm\u2026).\n   * Vazio no core; `HoldyWeb` preenche. O server n\u00E3o infere ambiente \u2014 n\u00E3o\n   * existe \"p\u00E1gina atual\" num worker.\n   */\n  protected environmentContext(): Properties {\n    return {}\n  }\n\n  /** Interno \u00B7 exposto pra testes. */\n  get pending(): number {\n    return this.queue.length\n  }\n}\n"],
-  "mappings": "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",
+  "sources": ["../src/server.ts", "../src/core.ts", "../src/run.ts"],
+  "sourcesContent": ["/**\n * @holdyapp/sdk (server) \u00B7 Node/Edge (source: sdk_server).\n *\n * Stateless por default: user_id/accountKey v\u00E3o por chamada em overrides.\n * identify()/group() de sess\u00E3o existem mas em server multi-tenant prefira\n * overrides \u2014 estado compartilhado entre requests vaza identidade.\n */\n\nimport { HoldyCore } from './core'\nimport { withRun, type RunHandle, type RunOptions } from './run'\nimport type { HoldyOptions } from './types'\n\nexport class Holdy extends HoldyCore {\n  constructor(opts: HoldyOptions) {\n    super('sdk_server', opts)\n  }\n\n  /**\n   * Executa `fn` como UMA execu\u00E7\u00E3o de agente: todo evento l\u00E1 dentro carrega a\n   * mesma `ai_run_id`, e `<name>.started` / `.completed` / `.failed` saem\n   * sozinhos.\n   *\n   *   await holdy.run({ name: 'support_agent', accountKey: 'acme' }, async (run) => {\n   *     run.track('ticket_drafted', { ai_tokens: 1200, ai_cost_usd: 0.02 })\n   *     return resolveTicket(ticket)\n   *   })\n   */\n  run<T>(opts: RunOptions, fn: (run: RunHandle) => Promise<T> | T): Promise<T> {\n    return withRun((name, properties, overrides) => this.track(name, properties, overrides), opts, fn)\n  }\n}\n\nexport { HoldyCore, DEFAULT_BASE_URL } from './core'\nexport type { HoldyOptions, Properties, TrackOverrides, CanonicalEvent } from './types'\nexport { newRunId, runEventName } from './run'\nexport type { RunHandle, RunOptions } from './run'\n", "/**\n * Core do @holdyapp/sdk \u00B7 fila + flush pra POST /api/v1/events/bulk.\n *\n * Todo evento sai com `external_id` pr\u00F3prio, ent\u00E3o reenviar um lote nunca\n * duplica (dedupe server-side por source + external_id + occurred_at).\n * 429 respeita Retry-After; 5xx e rede esperam com backoff exponencial; o lote\n * volta pra frente da fila em vez de sumir. Chave inv\u00E1lida ou origem recusada\n * avisam uma vez no console, mesmo sem debug. Fila \u00E9 bounded: acima de\n * MAX_QUEUE dropa os mais antigos (telemetria nunca derruba o app do cliente \u2014\n * nenhum m\u00E9todo p\u00FAblico lan\u00E7a).\n */\n\nimport type { CanonicalEvent, HoldyOptions, Properties, TrackOverrides } from './types'\n\nexport const DEFAULT_BASE_URL = 'https://holdy.chat/api/v1'\nconst DEFAULT_FLUSH_AT = 20\nconst DEFAULT_FLUSH_INTERVAL_MS = 5000\nconst MAX_QUEUE = 1000\nconst BULK_LIMIT = 500\nconst MAX_BACKOFF_MS = 60_000\n\ntype SendOutcome = { kind: 'sent' } | { kind: 'dropped' } | { kind: 'retry'; afterMs: number | null }\n\nexport class HoldyCore {\n  protected readonly apiKey: string\n  protected readonly baseUrl: string\n  private readonly flushAt: number\n  private readonly debug: boolean\n  private readonly source: 'sdk_web' | 'sdk_server'\n\n  private queue: CanonicalEvent[] = []\n  private timer: ReturnType<typeof setInterval> | null = null\n  private flushing: Promise<void> | null = null\n  private retryAt = 0\n  private failures = 0\n  private readonly warned = new Set<string>()\n\n  protected userId: string | null = null\n  protected anonymousId: string | null = null\n  protected accountKey: string | null = null\n\n  constructor(source: 'sdk_web' | 'sdk_server', opts: HoldyOptions) {\n    this.source = source\n    this.apiKey = opts.apiKey\n    this.accountKey = opts.accountKey ?? null\n    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/$/, '')\n    this.flushAt = Math.max(1, opts.flushAt ?? DEFAULT_FLUSH_AT)\n    this.debug = opts.debug ?? false\n\n    const intervalMs = opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS\n    if (intervalMs > 0) {\n      this.timer = setInterval(() => void this.flush(), intervalMs)\n      // Node: n\u00E3o segura o processo vivo s\u00F3 pelo timer do SDK.\n      if (typeof (this.timer as { unref?: () => void }).unref === 'function') {\n        ;(this.timer as unknown as { unref: () => void }).unref()\n      }\n    }\n  }\n\n  track(name: string, properties?: Properties, overrides?: TrackOverrides): void {\n    if (!name || typeof name !== 'string') return\n\n    const userId = overrides?.userId ?? this.userId ?? undefined\n    const accountKey = overrides?.accountKey ?? this.accountKey ?? undefined\n    const occurredAt = overrides?.occurredAt\n      ? new Date(overrides.occurredAt).toISOString()\n      : new Date().toISOString()\n\n    // Ordem: ambiente observado pelo SDK \u2192 context da chamada \u2192 carrier de\n    // account. O que o caller passou vence o inferido; o carrier vence tudo,\n    // porque \u00E9 o que a Data layer usa pra resolver a conta.\n    const context: Properties = {\n      ...this.environmentContext(),\n      ...(overrides?.context ?? {}),\n    }\n    if (accountKey) context.account_external_id = accountKey\n\n    const event: CanonicalEvent = {\n      event: name,\n      occurred_at: occurredAt,\n      source: this.source,\n      external_id: newEventId(),\n      ...(userId ? { user_id: userId } : {}),\n      ...(this.anonymousId ? { anonymous_id: this.anonymousId } : {}),\n      properties: properties ?? {},\n      ...(Object.keys(context).length > 0 ? { context } : {}),\n    }\n\n    this.queue.push(event)\n    this.trimQueue()\n    if (this.queue.length >= this.flushAt) void this.flush()\n  }\n\n  identify(userId: string, traits?: Properties): void {\n    if (!userId || typeof userId !== 'string') return\n    this.userId = userId\n    this.track('$identify', traits ?? {})\n  }\n\n  group(accountKey: string, traits?: Properties): void {\n    if (!accountKey || typeof accountKey !== 'string') return\n    this.accountKey = accountKey\n    this.track('$group', traits ?? {})\n  }\n\n  /** Drena a fila. Nunca lan\u00E7a \u2014 falha re-enfileira e espera antes de tentar de novo. */\n  async flush(): Promise<void> {\n    return this.startFlush(false)\n  }\n\n  /** Flush final + para o timer. Chamar em shutdown do server / unload do web. */\n  async shutdown(): Promise<void> {\n    if (this.timer) {\n      clearInterval(this.timer)\n      this.timer = null\n    }\n    await this.startFlush(true)\n  }\n\n  private startFlush(force: boolean): Promise<void> {\n    // Serializa flushes concorrentes (timer + flushAt + manual).\n    if (this.flushing) return this.flushing\n    if (this.queue.length === 0) return Promise.resolve()\n    if (!force && Date.now() < this.retryAt) return Promise.resolve()\n\n    this.flushing = this.drain().finally(() => {\n      this.flushing = null\n    })\n    return this.flushing\n  }\n\n  private async drain(): Promise<void> {\n    while (this.queue.length > 0) {\n      const batch = this.queue.splice(0, BULK_LIMIT)\n      const outcome = await this.send(batch)\n      if (outcome.kind === 'retry') {\n        this.queue.unshift(...batch)\n        this.trimQueue()\n        this.scheduleRetry(outcome.afterMs)\n        return\n      }\n      this.failures = 0\n      this.retryAt = 0\n    }\n  }\n\n  private scheduleRetry(afterMs: number | null): void {\n    this.failures += 1\n    if (afterMs !== null) {\n      this.retryAt = Date.now() + afterMs\n      return\n    }\n    const backoff = Math.min(MAX_BACKOFF_MS, 1000 * 2 ** (this.failures - 1))\n    this.retryAt = Date.now() + backoff + Math.floor(Math.random() * backoff * 0.2)\n  }\n\n  private trimQueue(): void {\n    if (this.queue.length > MAX_QUEUE) this.queue.splice(0, this.queue.length - MAX_QUEUE)\n  }\n\n  private async send(events: CanonicalEvent[]): Promise<SendOutcome> {\n    try {\n      const res = await fetch(`${this.baseUrl}/events/bulk`, {\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({ events }),\n        ...(this.source === 'sdk_web' ? { keepalive: true } : {}),\n      })\n      if (res.ok) return { kind: 'sent' }\n\n      if (res.status === 429) {\n        this.log('rate limited \u00B7 will retry after Retry-After')\n        return { kind: 'retry', afterMs: retryAfterMs(res) }\n      }\n      if (res.status >= 500) {\n        this.log(`bulk failed ${res.status} \u00B7 will retry with backoff`)\n        return { kind: 'retry', afterMs: null }\n      }\n      if (res.status === 401) {\n        this.warnOnce('401', 'API key inv\u00E1lida ou revogada \u00B7 eventos descartados. Confira a chave em Configura\u00E7\u00F5es \u203A SDK.')\n        return { kind: 'dropped' }\n      }\n      if (res.status === 403) {\n        this.warnOnce('403', 'Origem n\u00E3o permitida ou chave sem escopo events:write \u00B7 eventos descartados.')\n        return { kind: 'dropped' }\n      }\n      this.log(`bulk rejected ${res.status} \u00B7 batch dropped`)\n      return { kind: 'dropped' }\n    } catch (err) {\n      this.log(`bulk network error: ${(err as Error).message} \u00B7 will retry with backoff`)\n      return { kind: 'retry', afterMs: null }\n    }\n  }\n\n  private log(msg: string): void {\n    if (this.debug) console.warn(`[holdy] ${msg}`)\n  }\n\n  private warnOnce(key: string, msg: string): void {\n    if (this.warned.has(key)) return\n    this.warned.add(key)\n    console.warn(`[holdy] ${msg}`)\n  }\n\n  /**\n   * Ambiente que o SDK observa sozinho (url, referrer, browser, utm\u2026).\n   * Vazio no core; `HoldyWeb` preenche. O server n\u00E3o infere ambiente \u2014 n\u00E3o\n   * existe \"p\u00E1gina atual\" num worker.\n   */\n  protected environmentContext(): Properties {\n    return {}\n  }\n\n  /** Interno \u00B7 exposto pra testes. */\n  get pending(): number {\n    return this.queue.length\n  }\n}\n\nfunction retryAfterMs(res: Response): number | null {\n  const raw = typeof res.headers?.get === 'function' ? res.headers.get('Retry-After') : null\n  if (!raw) return null\n  const seconds = Number(raw)\n  if (!Number.isFinite(seconds) || seconds < 0) return null\n  return Math.min(MAX_BACKOFF_MS, seconds * 1000)\n}\n\nfunction newEventId(): string {\n  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto\n  if (typeof c?.randomUUID === 'function') return c.randomUUID()\n  const rand = () => Math.random().toString(36).slice(2, 12)\n  return `${Date.now().toString(36)}-${rand()}-${rand()}`\n}\n", "/**\n * Execu\u00E7\u00E3o como unidade de trabalho (source: sdk_server).\n *\n * Produto de agente n\u00E3o tem sess\u00E3o de browser: o trabalho roda no servidor,\n * por API, em background. Pra Holdy dizer \"come\u00E7ou e concluiu na mesma\n * execu\u00E7\u00E3o\" e dividir recurso por resultado entregue, todos os eventos de uma\n * tarefa carregam a mesma `ai_run_id` \u2014 a chave que o composer usa por padr\u00E3o\n * no gr\u00E3o de execu\u00E7\u00E3o (lib/knowledge/compose-definition.ts).\n *\n * N\u00E3o inventa vocabul\u00E1rio: in\u00EDcio e fim saem com o nome que o cliente deu \u00E0\n * execu\u00E7\u00E3o (`support_agent.started`), e todo passo no meio \u00E9 nome dele. O\n * retorno passa direto e o erro propaga; s\u00F3 o NOME do erro vira propriedade,\n * porque a mensagem carrega dado do cliente com frequ\u00EAncia demais.\n */\n\nimport type { Properties, TrackOverrides } from './types'\n\nexport interface RunOptions {\n  /** Nome da execu\u00E7\u00E3o no vocabul\u00E1rio do produto, ex.: 'support_agent'. */\n  name: string\n  /** Conta (id externo) dona da execu\u00E7\u00E3o. */\n  accountKey?: string\n  userId?: string\n  /** Chave pr\u00F3pria (trace id do agente); ausente = gerada aqui. */\n  runId?: string\n  /** Propriedades repetidas em todos os eventos da execu\u00E7\u00E3o. */\n  properties?: Properties\n}\n\nexport interface RunHandle {\n  /** A chave que agrupa tudo desta execu\u00E7\u00E3o. */\n  id: string\n  /** Um passo dentro da execu\u00E7\u00E3o, j\u00E1 carimbado com ai_run_id. */\n  track(event: string, properties?: Properties): void\n}\n\nexport type TrackFn = (name: string, properties?: Properties, overrides?: TrackOverrides) => void\n\nexport function newRunId(): string {\n  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto\n  if (typeof c?.randomUUID === 'function') return c.randomUUID()\n  return `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`\n}\n\nexport function runEventName(name: string, suffix: 'started' | 'completed' | 'failed'): string {\n  const base = name.trim().replace(/\\.$/, '')\n  return `${base || 'run'}.${suffix}`\n}\n\nexport async function withRun<T>(\n  track: TrackFn,\n  opts: RunOptions,\n  fn: (run: RunHandle) => Promise<T> | T,\n): Promise<T> {\n  if (!opts || !opts.name) throw new Error('[holdy] run: name is required')\n\n  const id = opts.runId && opts.runId.length > 0 ? opts.runId : newRunId()\n  const base: Properties = { ...(opts.properties ?? {}), ai_run_id: id }\n  const overrides: TrackOverrides = {\n    ...(opts.accountKey ? { accountKey: opts.accountKey } : {}),\n    ...(opts.userId ? { userId: opts.userId } : {}),\n  }\n  const emit = (event: string, properties?: Properties) =>\n    track(event, { ...base, ...(properties ?? {}), ai_run_id: id }, overrides)\n\n  const startedAt = Date.now()\n  emit(runEventName(opts.name, 'started'))\n\n  try {\n    const result = await fn({ id, track: emit })\n    emit(runEventName(opts.name, 'completed'), { duration_ms: Date.now() - startedAt })\n    return result\n  } catch (err) {\n    emit(runEventName(opts.name, 'failed'), {\n      duration_ms: Date.now() - startedAt,\n      error: err instanceof Error ? err.name : 'Error',\n    })\n    throw err\n  }\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/server.d.ts

@@ -6,10 +6,24 @@
  * overrides — estado compartilhado entre requests vaza identidade.
  */
 import { HoldyCore } from './core';
+import { type RunHandle, type RunOptions } from './run';
 import type { HoldyOptions } from './types';
 export declare class Holdy extends HoldyCore {
     constructor(opts: HoldyOptions);
+    /**
+     * 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>;
 }
 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';
 //# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAClC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C,qBAAa,KAAM,SAAQ,SAAS;gBACtB,IAAI,EAAE,YAAY;CAG/B;AAED,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAA;AACpD,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAClC,OAAO,EAAW,KAAK,SAAS,EAAE,KAAK,UAAU,EAAE,MAAM,OAAO,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C,qBAAa,KAAM,SAAQ,SAAS;gBACtB,IAAI,EAAE,YAAY;IAI9B;;;;;;;;;OASG;IACH,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAG7E;AAED,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,QAAQ,CAAA;AACpD,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AACvF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,OAAO,CAAA;AAC9C,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,OAAO,CAAA"}

package/dist/server.mjs

@@ -4,6 +4,7 @@ var DEFAULT_FLUSH_AT = 20;
 var DEFAULT_FLUSH_INTERVAL_MS = 5e3;
 var MAX_QUEUE = 1e3;
 var BULK_LIMIT = 500;
+var MAX_BACKOFF_MS = 6e4;
 var HoldyCore = class {
   apiKey;
   baseUrl;
@@ -13,6 +14,9 @@ var HoldyCore = class {
   queue = [];
   timer = null;
   flushing = null;
+  retryAt = 0;
+  failures = 0;
+  warned = /* @__PURE__ */ new Set();
   userId = null;
   anonymousId = null;
   accountKey = null;
@@ -46,13 +50,14 @@ var HoldyCore = class {
       event: name,
       occurred_at: occurredAt,
       source: this.source,
+      external_id: newEventId(),
       ...userId ? { user_id: userId } : {},
       ...this.anonymousId ? { anonymous_id: this.anonymousId } : {},
       properties: properties ?? {},
       ...Object.keys(context).length > 0 ? { context } : {}
     };
     this.queue.push(event);
-    if (this.queue.length > MAX_QUEUE) this.queue.splice(0, this.queue.length - MAX_QUEUE);
+    this.trimQueue();
     if (this.queue.length >= this.flushAt) void this.flush();
   }
   identify(userId, traits) {
@@ -65,14 +70,9 @@ var HoldyCore = class {
     this.accountKey = accountKey;
     this.track("$group", traits ?? {});
   }
-  /** Drena a fila. Nunca lança — falha re-enfileira e loga em debug. */
+  /** Drena a fila. Nunca lança — falha re-enfileira e espera antes de tentar de novo. */
   async flush() {
-    if (this.flushing) return this.flushing;
-    if (this.queue.length === 0) return;
-    this.flushing = this.drain().finally(() => {
-      this.flushing = null;
-    });
-    return this.flushing;
+    return this.startFlush(false);
   }
   /** Flush final + para o timer. Chamar em shutdown do server / unload do web. */
   async shutdown() {
@@ -80,17 +80,42 @@ var HoldyCore = class {
       clearInterval(this.timer);
       this.timer = null;
     }
-    await this.flush();
+    await this.startFlush(true);
+  }
+  startFlush(force) {
+    if (this.flushing) return this.flushing;
+    if (this.queue.length === 0) return Promise.resolve();
+    if (!force && Date.now() < this.retryAt) return Promise.resolve();
+    this.flushing = this.drain().finally(() => {
+      this.flushing = null;
+    });
+    return this.flushing;
   }
   async drain() {
     while (this.queue.length > 0) {
       const batch = this.queue.splice(0, BULK_LIMIT);
-      const ok = await this.send(batch);
-      if (!ok) {
+      const outcome = await this.send(batch);
+      if (outcome.kind === "retry") {
         this.queue.unshift(...batch);
+        this.trimQueue();
+        this.scheduleRetry(outcome.afterMs);
         return;
       }
+      this.failures = 0;
+      this.retryAt = 0;
+    }
+  }
+  scheduleRetry(afterMs) {
+    this.failures += 1;
+    if (afterMs !== null) {
+      this.retryAt = Date.now() + afterMs;
+      return;
     }
+    const backoff = Math.min(MAX_BACKOFF_MS, 1e3 * 2 ** (this.failures - 1));
+    this.retryAt = Date.now() + backoff + Math.floor(Math.random() * backoff * 0.2);
+  }
+  trimQueue() {
+    if (this.queue.length > MAX_QUEUE) this.queue.splice(0, this.queue.length - MAX_QUEUE);
   }
   async send(events) {
     try {
@@ -103,23 +128,38 @@ var HoldyCore = class {
         body: JSON.stringify({ events }),
         ...this.source === "sdk_web" ? { keepalive: true } : {}
       });
-      if (!res.ok) {
-        if (res.status >= 400 && res.status < 500) {
-          this.log(`bulk rejected ${res.status} \xB7 batch dropped`);
-          return true;
-        }
-        this.log(`bulk failed ${res.status} \xB7 will retry`);
-        return false;
+      if (res.ok) return { kind: "sent" };
+      if (res.status === 429) {
+        this.log("rate limited \xB7 will retry after Retry-After");
+        return { kind: "retry", afterMs: retryAfterMs(res) };
+      }
+      if (res.status >= 500) {
+        this.log(`bulk failed ${res.status} \xB7 will retry with backoff`);
+        return { kind: "retry", afterMs: null };
       }
-      return true;
+      if (res.status === 401) {
+        this.warnOnce("401", "API key inv\xE1lida ou revogada \xB7 eventos descartados. Confira a chave em Configura\xE7\xF5es \u203A SDK.");
+        return { kind: "dropped" };
+      }
+      if (res.status === 403) {
+        this.warnOnce("403", "Origem n\xE3o permitida ou chave sem escopo events:write \xB7 eventos descartados.");
+        return { kind: "dropped" };
+      }
+      this.log(`bulk rejected ${res.status} \xB7 batch dropped`);
+      return { kind: "dropped" };
     } catch (err) {
-      this.log(`bulk network error: ${err.message} \xB7 will retry`);
-      return false;
+      this.log(`bulk network error: ${err.message} \xB7 will retry with backoff`);
+      return { kind: "retry", afterMs: null };
     }
   }
   log(msg) {
     if (this.debug) console.warn(`[holdy] ${msg}`);
   }
+  warnOnce(key, msg) {
+    if (this.warned.has(key)) return;
+    this.warned.add(key);
+    console.warn(`[holdy] ${msg}`);
+  }
   /**
    * Ambiente que o SDK observa sozinho (url, referrer, browser, utm…).
    * Vazio no core; `HoldyWeb` preenche. O server não infere ambiente — não
@@ -133,16 +173,78 @@ var HoldyCore = class {
     return this.queue.length;
   }
 };
+function retryAfterMs(res) {
+  const raw = typeof res.headers?.get === "function" ? res.headers.get("Retry-After") : null;
+  if (!raw) return null;
+  const seconds = Number(raw);
+  if (!Number.isFinite(seconds) || seconds < 0) return null;
+  return Math.min(MAX_BACKOFF_MS, seconds * 1e3);
+}
+function newEventId() {
+  const c = globalThis.crypto;
+  if (typeof c?.randomUUID === "function") return c.randomUUID();
+  const rand = () => Math.random().toString(36).slice(2, 12);
+  return `${Date.now().toString(36)}-${rand()}-${rand()}`;
+}
+
+// src/run.ts
+function newRunId() {
+  const c = globalThis.crypto;
+  if (typeof c?.randomUUID === "function") return c.randomUUID();
+  return `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+}
+function runEventName(name, suffix) {
+  const base = name.trim().replace(/\.$/, "");
+  return `${base || "run"}.${suffix}`;
+}
+async function withRun(track, opts, fn) {
+  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 = { ...opts.properties ?? {}, ai_run_id: id };
+  const overrides = {
+    ...opts.accountKey ? { accountKey: opts.accountKey } : {},
+    ...opts.userId ? { userId: opts.userId } : {}
+  };
+  const emit = (event, 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;
+  }
+}
 
 // src/server.ts
 var Holdy = class extends HoldyCore {
   constructor(opts) {
     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(opts, fn) {
+    return withRun((name, properties, overrides) => this.track(name, properties, overrides), opts, fn);
+  }
 };
 export {
   DEFAULT_BASE_URL,
   Holdy,
-  HoldyCore
+  HoldyCore,
+  newRunId,
+  runEventName
 };
 //# sourceMappingURL=server.mjs.map

package/dist/server.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
-  "sources": ["../src/core.ts", "../src/server.ts"],
-  "sourcesContent": ["/**\n * Core do @holdyapp/sdk \u00B7 fila + flush pra POST /api/v1/events/bulk.\n *\n * Retry de batch inteiro \u00E9 seguro (partial accept + dedupe server-side).\n * Fila \u00E9 bounded: acima de MAX_QUEUE dropa os mais antigos (telemetria nunca\n * derruba o app do cliente \u2014 nenhum m\u00E9todo p\u00FAblico lan\u00E7a).\n */\n\nimport type { CanonicalEvent, HoldyOptions, Properties, TrackOverrides } from './types'\n\nexport const DEFAULT_BASE_URL = 'https://holdy.chat/api/v1'\nconst DEFAULT_FLUSH_AT = 20\nconst DEFAULT_FLUSH_INTERVAL_MS = 5000\nconst MAX_QUEUE = 1000\nconst BULK_LIMIT = 500\n\nexport class HoldyCore {\n  private readonly apiKey: string\n  private readonly baseUrl: string\n  private readonly flushAt: number\n  private readonly debug: boolean\n  private readonly source: 'sdk_web' | 'sdk_server'\n\n  private queue: CanonicalEvent[] = []\n  private timer: ReturnType<typeof setInterval> | null = null\n  private flushing: Promise<void> | null = null\n\n  protected userId: string | null = null\n  protected anonymousId: string | null = null\n  protected accountKey: string | null = null\n\n  constructor(source: 'sdk_web' | 'sdk_server', opts: HoldyOptions) {\n    this.source = source\n    this.apiKey = opts.apiKey\n    this.accountKey = opts.accountKey ?? null\n    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/$/, '')\n    this.flushAt = Math.max(1, opts.flushAt ?? DEFAULT_FLUSH_AT)\n    this.debug = opts.debug ?? false\n\n    const intervalMs = opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS\n    if (intervalMs > 0) {\n      this.timer = setInterval(() => void this.flush(), intervalMs)\n      // Node: n\u00E3o segura o processo vivo s\u00F3 pelo timer do SDK.\n      if (typeof (this.timer as { unref?: () => void }).unref === 'function') {\n        ;(this.timer as unknown as { unref: () => void }).unref()\n      }\n    }\n  }\n\n  track(name: string, properties?: Properties, overrides?: TrackOverrides): void {\n    if (!name || typeof name !== 'string') return\n\n    const userId = overrides?.userId ?? this.userId ?? undefined\n    const accountKey = overrides?.accountKey ?? this.accountKey ?? undefined\n    const occurredAt = overrides?.occurredAt\n      ? new Date(overrides.occurredAt).toISOString()\n      : new Date().toISOString()\n\n    // Ordem: ambiente observado pelo SDK \u2192 context da chamada \u2192 carrier de\n    // account. O que o caller passou vence o inferido; o carrier vence tudo,\n    // porque \u00E9 o que a Data layer usa pra resolver a conta.\n    const context: Properties = {\n      ...this.environmentContext(),\n      ...(overrides?.context ?? {}),\n    }\n    if (accountKey) context.account_external_id = accountKey\n\n    const event: CanonicalEvent = {\n      event: name,\n      occurred_at: occurredAt,\n      source: this.source,\n      ...(userId ? { user_id: userId } : {}),\n      ...(this.anonymousId ? { anonymous_id: this.anonymousId } : {}),\n      properties: properties ?? {},\n      ...(Object.keys(context).length > 0 ? { context } : {}),\n    }\n\n    this.queue.push(event)\n    if (this.queue.length > MAX_QUEUE) this.queue.splice(0, this.queue.length - MAX_QUEUE)\n    if (this.queue.length >= this.flushAt) void this.flush()\n  }\n\n  identify(userId: string, traits?: Properties): void {\n    if (!userId || typeof userId !== 'string') return\n    this.userId = userId\n    this.track('$identify', traits ?? {})\n  }\n\n  group(accountKey: string, traits?: Properties): void {\n    if (!accountKey || typeof accountKey !== 'string') return\n    this.accountKey = accountKey\n    this.track('$group', traits ?? {})\n  }\n\n  /** Drena a fila. Nunca lan\u00E7a \u2014 falha re-enfileira e loga em debug. */\n  async flush(): Promise<void> {\n    // Serializa flushes concorrentes (timer + flushAt + manual).\n    if (this.flushing) return this.flushing\n    if (this.queue.length === 0) return\n\n    this.flushing = this.drain().finally(() => {\n      this.flushing = null\n    })\n    return this.flushing\n  }\n\n  /** Flush final + para o timer. Chamar em shutdown do server / unload do web. */\n  async shutdown(): Promise<void> {\n    if (this.timer) {\n      clearInterval(this.timer)\n      this.timer = null\n    }\n    await this.flush()\n  }\n\n  private async drain(): Promise<void> {\n    while (this.queue.length > 0) {\n      const batch = this.queue.splice(0, BULK_LIMIT)\n      const ok = await this.send(batch)\n      if (!ok) {\n        // Devolve pra frente da fila e para \u2014 pr\u00F3ximo flush re-tenta (dedupe-safe).\n        this.queue.unshift(...batch)\n        return\n      }\n    }\n  }\n\n  private async send(events: CanonicalEvent[]): Promise<boolean> {\n    try {\n      const res = await fetch(`${this.baseUrl}/events/bulk`, {\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({ events }),\n        ...(this.source === 'sdk_web' ? { keepalive: true } : {}),\n      })\n      if (!res.ok) {\n        // 4xx: batch estruturalmente inv\u00E1lido n\u00E3o re-tenta (evita loop infinito).\n        if (res.status >= 400 && res.status < 500) {\n          this.log(`bulk rejected ${res.status} \u00B7 batch dropped`)\n          return true\n        }\n        this.log(`bulk failed ${res.status} \u00B7 will retry`)\n        return false\n      }\n      return true\n    } catch (err) {\n      this.log(`bulk network error: ${(err as Error).message} \u00B7 will retry`)\n      return false\n    }\n  }\n\n  private log(msg: string): void {\n    if (this.debug) console.warn(`[holdy] ${msg}`)\n  }\n\n  /**\n   * Ambiente que o SDK observa sozinho (url, referrer, browser, utm\u2026).\n   * Vazio no core; `HoldyWeb` preenche. O server n\u00E3o infere ambiente \u2014 n\u00E3o\n   * existe \"p\u00E1gina atual\" num worker.\n   */\n  protected environmentContext(): Properties {\n    return {}\n  }\n\n  /** Interno \u00B7 exposto pra testes. */\n  get pending(): number {\n    return this.queue.length\n  }\n}\n", "/**\n * @holdyapp/sdk (server) \u00B7 Node/Edge (source: sdk_server).\n *\n * Stateless por default: user_id/accountKey v\u00E3o por chamada em overrides.\n * identify()/group() de sess\u00E3o existem mas em server multi-tenant prefira\n * overrides \u2014 estado compartilhado entre requests vaza identidade.\n */\n\nimport { HoldyCore } from './core'\nimport type { HoldyOptions } from './types'\n\nexport class Holdy extends HoldyCore {\n  constructor(opts: HoldyOptions) {\n    super('sdk_server', opts)\n  }\n}\n\nexport { HoldyCore, DEFAULT_BASE_URL } from './core'\nexport type { HoldyOptions, Properties, TrackOverrides, CanonicalEvent } from './types'\n"],
-  "mappings": "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",
+  "sources": ["../src/core.ts", "../src/run.ts", "../src/server.ts"],
+  "sourcesContent": ["/**\n * Core do @holdyapp/sdk \u00B7 fila + flush pra POST /api/v1/events/bulk.\n *\n * Todo evento sai com `external_id` pr\u00F3prio, ent\u00E3o reenviar um lote nunca\n * duplica (dedupe server-side por source + external_id + occurred_at).\n * 429 respeita Retry-After; 5xx e rede esperam com backoff exponencial; o lote\n * volta pra frente da fila em vez de sumir. Chave inv\u00E1lida ou origem recusada\n * avisam uma vez no console, mesmo sem debug. Fila \u00E9 bounded: acima de\n * MAX_QUEUE dropa os mais antigos (telemetria nunca derruba o app do cliente \u2014\n * nenhum m\u00E9todo p\u00FAblico lan\u00E7a).\n */\n\nimport type { CanonicalEvent, HoldyOptions, Properties, TrackOverrides } from './types'\n\nexport const DEFAULT_BASE_URL = 'https://holdy.chat/api/v1'\nconst DEFAULT_FLUSH_AT = 20\nconst DEFAULT_FLUSH_INTERVAL_MS = 5000\nconst MAX_QUEUE = 1000\nconst BULK_LIMIT = 500\nconst MAX_BACKOFF_MS = 60_000\n\ntype SendOutcome = { kind: 'sent' } | { kind: 'dropped' } | { kind: 'retry'; afterMs: number | null }\n\nexport class HoldyCore {\n  protected readonly apiKey: string\n  protected readonly baseUrl: string\n  private readonly flushAt: number\n  private readonly debug: boolean\n  private readonly source: 'sdk_web' | 'sdk_server'\n\n  private queue: CanonicalEvent[] = []\n  private timer: ReturnType<typeof setInterval> | null = null\n  private flushing: Promise<void> | null = null\n  private retryAt = 0\n  private failures = 0\n  private readonly warned = new Set<string>()\n\n  protected userId: string | null = null\n  protected anonymousId: string | null = null\n  protected accountKey: string | null = null\n\n  constructor(source: 'sdk_web' | 'sdk_server', opts: HoldyOptions) {\n    this.source = source\n    this.apiKey = opts.apiKey\n    this.accountKey = opts.accountKey ?? null\n    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/$/, '')\n    this.flushAt = Math.max(1, opts.flushAt ?? DEFAULT_FLUSH_AT)\n    this.debug = opts.debug ?? false\n\n    const intervalMs = opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS\n    if (intervalMs > 0) {\n      this.timer = setInterval(() => void this.flush(), intervalMs)\n      // Node: n\u00E3o segura o processo vivo s\u00F3 pelo timer do SDK.\n      if (typeof (this.timer as { unref?: () => void }).unref === 'function') {\n        ;(this.timer as unknown as { unref: () => void }).unref()\n      }\n    }\n  }\n\n  track(name: string, properties?: Properties, overrides?: TrackOverrides): void {\n    if (!name || typeof name !== 'string') return\n\n    const userId = overrides?.userId ?? this.userId ?? undefined\n    const accountKey = overrides?.accountKey ?? this.accountKey ?? undefined\n    const occurredAt = overrides?.occurredAt\n      ? new Date(overrides.occurredAt).toISOString()\n      : new Date().toISOString()\n\n    // Ordem: ambiente observado pelo SDK \u2192 context da chamada \u2192 carrier de\n    // account. O que o caller passou vence o inferido; o carrier vence tudo,\n    // porque \u00E9 o que a Data layer usa pra resolver a conta.\n    const context: Properties = {\n      ...this.environmentContext(),\n      ...(overrides?.context ?? {}),\n    }\n    if (accountKey) context.account_external_id = accountKey\n\n    const event: CanonicalEvent = {\n      event: name,\n      occurred_at: occurredAt,\n      source: this.source,\n      external_id: newEventId(),\n      ...(userId ? { user_id: userId } : {}),\n      ...(this.anonymousId ? { anonymous_id: this.anonymousId } : {}),\n      properties: properties ?? {},\n      ...(Object.keys(context).length > 0 ? { context } : {}),\n    }\n\n    this.queue.push(event)\n    this.trimQueue()\n    if (this.queue.length >= this.flushAt) void this.flush()\n  }\n\n  identify(userId: string, traits?: Properties): void {\n    if (!userId || typeof userId !== 'string') return\n    this.userId = userId\n    this.track('$identify', traits ?? {})\n  }\n\n  group(accountKey: string, traits?: Properties): void {\n    if (!accountKey || typeof accountKey !== 'string') return\n    this.accountKey = accountKey\n    this.track('$group', traits ?? {})\n  }\n\n  /** Drena a fila. Nunca lan\u00E7a \u2014 falha re-enfileira e espera antes de tentar de novo. */\n  async flush(): Promise<void> {\n    return this.startFlush(false)\n  }\n\n  /** Flush final + para o timer. Chamar em shutdown do server / unload do web. */\n  async shutdown(): Promise<void> {\n    if (this.timer) {\n      clearInterval(this.timer)\n      this.timer = null\n    }\n    await this.startFlush(true)\n  }\n\n  private startFlush(force: boolean): Promise<void> {\n    // Serializa flushes concorrentes (timer + flushAt + manual).\n    if (this.flushing) return this.flushing\n    if (this.queue.length === 0) return Promise.resolve()\n    if (!force && Date.now() < this.retryAt) return Promise.resolve()\n\n    this.flushing = this.drain().finally(() => {\n      this.flushing = null\n    })\n    return this.flushing\n  }\n\n  private async drain(): Promise<void> {\n    while (this.queue.length > 0) {\n      const batch = this.queue.splice(0, BULK_LIMIT)\n      const outcome = await this.send(batch)\n      if (outcome.kind === 'retry') {\n        this.queue.unshift(...batch)\n        this.trimQueue()\n        this.scheduleRetry(outcome.afterMs)\n        return\n      }\n      this.failures = 0\n      this.retryAt = 0\n    }\n  }\n\n  private scheduleRetry(afterMs: number | null): void {\n    this.failures += 1\n    if (afterMs !== null) {\n      this.retryAt = Date.now() + afterMs\n      return\n    }\n    const backoff = Math.min(MAX_BACKOFF_MS, 1000 * 2 ** (this.failures - 1))\n    this.retryAt = Date.now() + backoff + Math.floor(Math.random() * backoff * 0.2)\n  }\n\n  private trimQueue(): void {\n    if (this.queue.length > MAX_QUEUE) this.queue.splice(0, this.queue.length - MAX_QUEUE)\n  }\n\n  private async send(events: CanonicalEvent[]): Promise<SendOutcome> {\n    try {\n      const res = await fetch(`${this.baseUrl}/events/bulk`, {\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${this.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({ events }),\n        ...(this.source === 'sdk_web' ? { keepalive: true } : {}),\n      })\n      if (res.ok) return { kind: 'sent' }\n\n      if (res.status === 429) {\n        this.log('rate limited \u00B7 will retry after Retry-After')\n        return { kind: 'retry', afterMs: retryAfterMs(res) }\n      }\n      if (res.status >= 500) {\n        this.log(`bulk failed ${res.status} \u00B7 will retry with backoff`)\n        return { kind: 'retry', afterMs: null }\n      }\n      if (res.status === 401) {\n        this.warnOnce('401', 'API key inv\u00E1lida ou revogada \u00B7 eventos descartados. Confira a chave em Configura\u00E7\u00F5es \u203A SDK.')\n        return { kind: 'dropped' }\n      }\n      if (res.status === 403) {\n        this.warnOnce('403', 'Origem n\u00E3o permitida ou chave sem escopo events:write \u00B7 eventos descartados.')\n        return { kind: 'dropped' }\n      }\n      this.log(`bulk rejected ${res.status} \u00B7 batch dropped`)\n      return { kind: 'dropped' }\n    } catch (err) {\n      this.log(`bulk network error: ${(err as Error).message} \u00B7 will retry with backoff`)\n      return { kind: 'retry', afterMs: null }\n    }\n  }\n\n  private log(msg: string): void {\n    if (this.debug) console.warn(`[holdy] ${msg}`)\n  }\n\n  private warnOnce(key: string, msg: string): void {\n    if (this.warned.has(key)) return\n    this.warned.add(key)\n    console.warn(`[holdy] ${msg}`)\n  }\n\n  /**\n   * Ambiente que o SDK observa sozinho (url, referrer, browser, utm\u2026).\n   * Vazio no core; `HoldyWeb` preenche. O server n\u00E3o infere ambiente \u2014 n\u00E3o\n   * existe \"p\u00E1gina atual\" num worker.\n   */\n  protected environmentContext(): Properties {\n    return {}\n  }\n\n  /** Interno \u00B7 exposto pra testes. */\n  get pending(): number {\n    return this.queue.length\n  }\n}\n\nfunction retryAfterMs(res: Response): number | null {\n  const raw = typeof res.headers?.get === 'function' ? res.headers.get('Retry-After') : null\n  if (!raw) return null\n  const seconds = Number(raw)\n  if (!Number.isFinite(seconds) || seconds < 0) return null\n  return Math.min(MAX_BACKOFF_MS, seconds * 1000)\n}\n\nfunction newEventId(): string {\n  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto\n  if (typeof c?.randomUUID === 'function') return c.randomUUID()\n  const rand = () => Math.random().toString(36).slice(2, 12)\n  return `${Date.now().toString(36)}-${rand()}-${rand()}`\n}\n", "/**\n * Execu\u00E7\u00E3o como unidade de trabalho (source: sdk_server).\n *\n * Produto de agente n\u00E3o tem sess\u00E3o de browser: o trabalho roda no servidor,\n * por API, em background. Pra Holdy dizer \"come\u00E7ou e concluiu na mesma\n * execu\u00E7\u00E3o\" e dividir recurso por resultado entregue, todos os eventos de uma\n * tarefa carregam a mesma `ai_run_id` \u2014 a chave que o composer usa por padr\u00E3o\n * no gr\u00E3o de execu\u00E7\u00E3o (lib/knowledge/compose-definition.ts).\n *\n * N\u00E3o inventa vocabul\u00E1rio: in\u00EDcio e fim saem com o nome que o cliente deu \u00E0\n * execu\u00E7\u00E3o (`support_agent.started`), e todo passo no meio \u00E9 nome dele. O\n * retorno passa direto e o erro propaga; s\u00F3 o NOME do erro vira propriedade,\n * porque a mensagem carrega dado do cliente com frequ\u00EAncia demais.\n */\n\nimport type { Properties, TrackOverrides } from './types'\n\nexport interface RunOptions {\n  /** Nome da execu\u00E7\u00E3o no vocabul\u00E1rio do produto, ex.: 'support_agent'. */\n  name: string\n  /** Conta (id externo) dona da execu\u00E7\u00E3o. */\n  accountKey?: string\n  userId?: string\n  /** Chave pr\u00F3pria (trace id do agente); ausente = gerada aqui. */\n  runId?: string\n  /** Propriedades repetidas em todos os eventos da execu\u00E7\u00E3o. */\n  properties?: Properties\n}\n\nexport interface RunHandle {\n  /** A chave que agrupa tudo desta execu\u00E7\u00E3o. */\n  id: string\n  /** Um passo dentro da execu\u00E7\u00E3o, j\u00E1 carimbado com ai_run_id. */\n  track(event: string, properties?: Properties): void\n}\n\nexport type TrackFn = (name: string, properties?: Properties, overrides?: TrackOverrides) => void\n\nexport function newRunId(): string {\n  const c = (globalThis as { crypto?: { randomUUID?: () => string } }).crypto\n  if (typeof c?.randomUUID === 'function') return c.randomUUID()\n  return `run_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`\n}\n\nexport function runEventName(name: string, suffix: 'started' | 'completed' | 'failed'): string {\n  const base = name.trim().replace(/\\.$/, '')\n  return `${base || 'run'}.${suffix}`\n}\n\nexport async function withRun<T>(\n  track: TrackFn,\n  opts: RunOptions,\n  fn: (run: RunHandle) => Promise<T> | T,\n): Promise<T> {\n  if (!opts || !opts.name) throw new Error('[holdy] run: name is required')\n\n  const id = opts.runId && opts.runId.length > 0 ? opts.runId : newRunId()\n  const base: Properties = { ...(opts.properties ?? {}), ai_run_id: id }\n  const overrides: TrackOverrides = {\n    ...(opts.accountKey ? { accountKey: opts.accountKey } : {}),\n    ...(opts.userId ? { userId: opts.userId } : {}),\n  }\n  const emit = (event: string, properties?: Properties) =>\n    track(event, { ...base, ...(properties ?? {}), ai_run_id: id }, overrides)\n\n  const startedAt = Date.now()\n  emit(runEventName(opts.name, 'started'))\n\n  try {\n    const result = await fn({ id, track: emit })\n    emit(runEventName(opts.name, 'completed'), { duration_ms: Date.now() - startedAt })\n    return result\n  } catch (err) {\n    emit(runEventName(opts.name, 'failed'), {\n      duration_ms: Date.now() - startedAt,\n      error: err instanceof Error ? err.name : 'Error',\n    })\n    throw err\n  }\n}\n", "/**\n * @holdyapp/sdk (server) \u00B7 Node/Edge (source: sdk_server).\n *\n * Stateless por default: user_id/accountKey v\u00E3o por chamada em overrides.\n * identify()/group() de sess\u00E3o existem mas em server multi-tenant prefira\n * overrides \u2014 estado compartilhado entre requests vaza identidade.\n */\n\nimport { HoldyCore } from './core'\nimport { withRun, type RunHandle, type RunOptions } from './run'\nimport type { HoldyOptions } from './types'\n\nexport class Holdy extends HoldyCore {\n  constructor(opts: HoldyOptions) {\n    super('sdk_server', opts)\n  }\n\n  /**\n   * Executa `fn` como UMA execu\u00E7\u00E3o de agente: todo evento l\u00E1 dentro carrega a\n   * mesma `ai_run_id`, e `<name>.started` / `.completed` / `.failed` saem\n   * sozinhos.\n   *\n   *   await holdy.run({ name: 'support_agent', accountKey: 'acme' }, async (run) => {\n   *     run.track('ticket_drafted', { ai_tokens: 1200, ai_cost_usd: 0.02 })\n   *     return resolveTicket(ticket)\n   *   })\n   */\n  run<T>(opts: RunOptions, fn: (run: RunHandle) => Promise<T> | T): Promise<T> {\n    return withRun((name, properties, overrides) => this.track(name, properties, overrides), opts, fn)\n  }\n}\n\nexport { HoldyCore, DEFAULT_BASE_URL } from './core'\nexport type { HoldyOptions, Properties, TrackOverrides, CanonicalEvent } from './types'\nexport { newRunId, runEventName } from './run'\nexport type { RunHandle, RunOptions } from './run'\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/skeleton.d.ts

@@ -0,0 +1,50 @@
+export declare 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 declare const SKELETON_MAX_ELEMENTS = 80;
+export declare const SKELETON_DELAY_MS = 1500;
+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 declare function fnv1a(input: string): string;
+export declare function describeSkeletonElement(el: SkeletonElementLike, viewport: SkeletonViewport | null): SkeletonElement;
+export declare function collectSkeleton(root: SkeletonRootLike, path: string, viewport: SkeletonViewport | null): PageSkeleton;
+export interface SkeletonCaptureOptions {
+    onSkeleton: (skeleton: PageSkeleton) => void;
+    delayMs?: number;
+}
+export interface SkeletonCapture {
+    onNavigate: (path: string) => void;
+    teardown: () => void;
+}
+export declare function installSkeletonCapture(opts: SkeletonCaptureOptions): SkeletonCapture;
+//# sourceMappingURL=skeleton.d.ts.map

package/dist/skeleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skeleton.d.ts","sourceRoot":"","sources":["../src/skeleton.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,iBAAiB,+LACkJ,CAAA;AAChL,eAAO,MAAM,qBAAqB,KAAK,CAAA;AACvC,eAAO,MAAM,iBAAiB,OAAO,CAAA;AAIrC,MAAM,WAAW,YAAY;IAC3B,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,EAAE,MAAM,CAAA;IACT,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;IACzC,qBAAqB,CAAC,IAAI,YAAY,CAAA;CACvC;AAED,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC,mBAAmB,CAAC,CAAA;CACnE;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,CAAC,EAAE,MAAM,CAAA;IACT,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,CAAC,CAAC,EAAE,MAAM,CAAA;IACV,CAAC,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAA;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,eAAe,EAAE,CAAA;CAC5B;AAED,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO3C;AAoBD,wBAAgB,uBAAuB,CAAC,EAAE,EAAE,mBAAmB,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,GAAG,eAAe,CAgBnH;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,GAAG,IAAI,GAAG,YAAY,CAYrH;AAED,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,CAAC,QAAQ,EAAE,YAAY,KAAK,IAAI,CAAA;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAClC,QAAQ,EAAE,MAAM,IAAI,CAAA;CACrB;AAoBD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,sBAAsB,GAAG,eAAe,CAsCpF"}

package/dist/types.d.ts

@@ -10,6 +10,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/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEhD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,SAAS,GAAG,YAAY,CAAA;IAChC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,CAAC,EAAE,UAAU,CAAA;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAA;IACd,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,gCAAgC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,IAAI,GAAG,MAAM,CAAA;IAC1B,sCAAsC;IACtC,OAAO,CAAC,EAAE,UAAU,CAAA;CACrB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;AAEhD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,EAAE,MAAM,CAAA;IACnB,MAAM,EAAE,SAAS,GAAG,YAAY,CAAA;IAChC,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,UAAU,CAAA;IACtB,OAAO,CAAC,EAAE,UAAU,CAAA;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAA;IACd,mDAAmD;IACnD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sEAAsE;IACtE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,gCAAgC;IAChC,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,cAAc;IAC7B,+DAA+D;IAC/D,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2CAA2C;IAC3C,UAAU,CAAC,EAAE,IAAI,GAAG,MAAM,CAAA;IAC1B,sCAAsC;IACtC,OAAO,CAAC,EAAE,UAAU,CAAA;CACrB"}

package/dist/web.d.ts

@@ -11,6 +11,7 @@
  * carregamento inicial e cada mudança de rota, inclusive em SPA.
  */
 import { HoldyCore } from './core';
+import { type FrictionCaptureOptions } from './friction';
 import type { HoldyOptions, Properties } from './types';
 export interface HoldyWebOptions extends HoldyOptions {
     /**
@@ -18,9 +19,33 @@ 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 declare class HoldyWeb extends HoldyCore {
     private teardownAutoCapture;
+    private friction;
+    private changes;
+    private skeleton;
     constructor(opts: HoldyWebOptions);
     /**
      * Pageview. O `$` marca evento emitido pelo SDK, não pelo produto (mesma
@@ -30,6 +55,7 @@ export declare class HoldyWeb extends HoldyCore {
      * que é da página como conteúdo (nome e título).
      */
     page(name?: string, properties?: Properties): void;
+    group(accountKey: string, traits?: Properties): void;
     reset(): void;
     /** Flush final + desinstala o auto-capture (devolve `history` ao original). */
     shutdown(): Promise<void>;

package/dist/web.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAGlC,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAIvD,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;CACtB;AAED,qBAAa,QAAS,SAAQ,SAAS;IACrC,OAAO,CAAC,mBAAmB,CAA4B;gBAE3C,IAAI,EAAE,eAAe;IAkBjC;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI;IAQlD,KAAK,IAAI,IAAI;IAWb,+EAA+E;IAChE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;cAMrB,kBAAkB,IAAI,UAAU;CAGpD;AAgBD,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,IAAI,EAAE,eAAe,GAAG,QAAQ,CAYzD;AAED,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,CAAA"}
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../src/web.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAElC,OAAO,EAAgD,KAAK,sBAAsB,EAAE,MAAM,YAAY,CAAA;AAItG,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,SAAS,CAAA;AAIvD,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC,sBAAsB,EAAE,YAAY,CAAC,CAAA;IAC/D;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,qBAAa,QAAS,SAAQ,SAAS;IACrC,OAAO,CAAC,mBAAmB,CAA4B;IACvD,OAAO,CAAC,QAAQ,CAA+B;IAC/C,OAAO,CAAC,OAAO,CAAoC;IACnD,OAAO,CAAC,QAAQ,CAA+B;gBAEnC,IAAI,EAAE,eAAe;IAiDjC;;;;;;OAMG;IACH,IAAI,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,UAAU,GAAG,IAAI;IAQzC,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,IAAI;IAK7D,KAAK,IAAI,IAAI;IAYb,+EAA+E;IAChE,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;cAYrB,kBAAkB,IAAI,UAAU;CAGpD;AAgBD,wEAAwE;AACxE,wBAAgB,SAAS,CAAC,IAAI,EAAE,eAAe,GAAG,QAAQ,CAYzD;AAED,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,CAAA"}