@holdyapp/sdk 0.2.1 → 1.0.1

package/src/web-context.test.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest'
+import { parseUserAgent, parseUtm, stripUrl } from './web-context'
+
+describe('stripUrl', () => {
+  it('tira query e hash — href cru vira dimensão de cardinalidade quase-única', () => {
+    expect(stripUrl('https://app.x.com/rel/42?utm_source=x&t=9#top')).toBe(
+      'https://app.x.com/rel/42',
+    )
+    expect(stripUrl('https://app.x.com/')).toBe('https://app.x.com/')
+  })
+
+  it('devolve null pro que não é URL', () => {
+    expect(stripUrl('/só-o-path')).toBeNull()
+    expect(stripUrl('')).toBeNull()
+  })
+})
+
+describe('parseUtm', () => {
+  it('captura os cinco parâmetros de campanha em minúsculas', () => {
+    const utm = parseUtm(
+      'https://x.com/?utm_source=Google&utm_medium=CPC&utm_campaign=Lançamento&utm_term=abc&utm_content=v2',
+    )
+    expect(utm).toEqual({
+      utm_source: 'google',
+      utm_medium: 'cpc',
+      utm_campaign: 'lançamento',
+      utm_term: 'abc',
+      utm_content: 'v2',
+    })
+  })
+
+  it('ignora ausentes e vazios em vez de gravar string vazia', () => {
+    expect(parseUtm('https://x.com/?utm_source=&foo=1')).toEqual({})
+    expect(parseUtm('https://x.com/')).toEqual({})
+    expect(parseUtm('nem-url')).toEqual({})
+  })
+})
+
+describe('parseUserAgent', () => {
+  const CHROME_MAC =
+    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36'
+  const SAFARI_IPHONE =
+    'Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1'
+  const EDGE_WINDOWS =
+    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36 Edg/126.0.0.0'
+  const FIREFOX_LINUX = 'Mozilla/5.0 (X11; Linux x86_64; rv:127.0) Gecko/20100101 Firefox/127.0'
+  const CHROME_ANDROID_TABLET =
+    'Mozilla/5.0 (Linux; Android 13; SM-X700) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36'
+
+  it('separa navegador, sistema e classe de dispositivo', () => {
+    expect(parseUserAgent(CHROME_MAC)).toEqual({ browser: 'Chrome', os: 'macOS', device: 'desktop' })
+    expect(parseUserAgent(SAFARI_IPHONE)).toEqual({ browser: 'Safari', os: 'iOS', device: 'mobile' })
+    expect(parseUserAgent(FIREFOX_LINUX)).toEqual({
+      browser: 'Firefox',
+      os: 'Linux',
+      device: 'desktop',
+    })
+  })
+
+  it('não confunde Edge com Chrome (o UA do Edge contém "chrome")', () => {
+    expect(parseUserAgent(EDGE_WINDOWS).browser).toBe('Edge')
+  })
+
+  it('android sem "mobile" é tablet', () => {
+    expect(parseUserAgent(CHROME_ANDROID_TABLET).device).toBe('tablet')
+  })
+
+  it('UA vazio não inventa campo', () => {
+    expect(parseUserAgent('')).toEqual({})
+  })
+})

package/src/web-context.ts

@@ -0,0 +1,227 @@
+/**
+ * Contexto de ambiente do browser · @holdyapp/sdk/web.
+ *
+ * Vai em `context` de todo evento, nunca em `properties`: properties é o
+ * vocabulário do produto do cliente (`workflow_key`, `plan`), context é o que o
+ * SDK observou sozinho. A Data layer persiste os dois (facts.context, 00247) e
+ * a leitura de dimensão consulta os dois.
+ *
+ * Três decisões que definem se esse dado é útil ou lixo:
+ *   · `url` sai sem query e sem hash. Href cru tem uma variação por sessão, e
+ *     dimensão com cardinalidade quase-única é descartada na leitura — a
+ *     página vira ruído exatamente por excesso de precisão.
+ *   · utm é capturado na primeira página e carregado pelo resto da sessão.
+ *     Atribuição que só existe no primeiro evento não responde nada.
+ *   · referrer só quando é externo. Navegação interna preenchendo "Origem do
+ *     tráfego" com o próprio domínio esconde a origem real.
+ *
+ * Tudo aqui é best-effort: browser em modo privativo, SSR e webview sem
+ * storage precisam funcionar. Nenhuma função lança.
+ */
+
+export type WebContext = Record<string, string>
+
+const UTM_KEYS = [
+  'utm_source',
+  'utm_medium',
+  'utm_campaign',
+  'utm_term',
+  'utm_content',
+] as const
+
+const SESSION_STORAGE_KEY = 'holdy_session'
+const ATTRIBUTION_STORAGE_KEY = 'holdy_attribution'
+
+/* ── URL ──────────────────────────────────────────────────────────────────── */
+
+/** `https://app.x.com/a/b?q=1#z` → `https://app.x.com/a/b`. */
+export function stripUrl(href: string): string | null {
+  try {
+    const url = new URL(href)
+    return `${url.origin}${url.pathname}`
+  } catch {
+    return null
+  }
+}
+
+/** Parâmetros de campanha presentes na URL, já em lowercase. */
+export function parseUtm(href: string): WebContext {
+  const out: WebContext = {}
+  try {
+    const params = new URL(href).searchParams
+    for (const key of UTM_KEYS) {
+      const value = params.get(key)?.trim()
+      if (value) out[key] = value.toLowerCase().slice(0, 120)
+    }
+  } catch {
+    // href inválido — sem utm, sem drama.
+  }
+  return out
+}
+
+/* ── User agent ───────────────────────────────────────────────────────────── */
+
+interface UaParts {
+  browser?: string
+  os?: string
+  device?: string
+}
+
+/**
+ * Fatia mínima do UA: navegador, sistema e classe de dispositivo.
+ *
+ * Não é biblioteca de UA parsing e não deve virar uma — o valor está em
+ * separar mobile de desktop e Safari de Chrome, não em cravar a versão.
+ */
+export function parseUserAgent(ua: string): UaParts {
+  if (!ua) return {}
+  const s = ua.toLowerCase()
+
+  const browser = s.includes('edg/')
+    ? 'Edge'
+    : s.includes('opr/') || s.includes('opera')
+      ? 'Opera'
+      : s.includes('samsungbrowser')
+        ? 'Samsung Internet'
+        : s.includes('firefox') || s.includes('fxios')
+          ? 'Firefox'
+          : s.includes('chrome') || s.includes('crios')
+            ? 'Chrome'
+            : s.includes('safari')
+              ? 'Safari'
+              : undefined
+
+  const os = s.includes('iphone') || s.includes('ipad') || s.includes('ipod')
+    ? 'iOS'
+    : s.includes('android')
+      ? 'Android'
+      : s.includes('windows')
+        ? 'Windows'
+        : s.includes('mac os') || s.includes('macintosh')
+          ? 'macOS'
+          : s.includes('cros')
+            ? 'ChromeOS'
+            : s.includes('linux')
+              ? 'Linux'
+              : undefined
+
+  // iPad moderno se declara macOS; a pista que sobra é o suporte a toque, que
+  // o parser puro não vê. Tablet aqui cobre o caso declarado no UA.
+  const device = s.includes('ipad') || (s.includes('android') && !s.includes('mobile'))
+    ? 'tablet'
+    : s.includes('mobi') || s.includes('iphone') || s.includes('ipod')
+      ? 'mobile'
+      : 'desktop'
+
+  return {
+    ...(browser ? { browser } : {}),
+    ...(os ? { os } : {}),
+    device,
+  }
+}
+
+/* ── Storage · nunca lança ────────────────────────────────────────────────── */
+
+function readStorage(storage: 'session' | 'local', key: string): string | null {
+  try {
+    const s = storage === 'session' ? sessionStorage : localStorage
+    return s.getItem(key)
+  } catch {
+    return null
+  }
+}
+
+function writeStorage(storage: 'session' | 'local', key: string, value: string): void {
+  try {
+    const s = storage === 'session' ? sessionStorage : localStorage
+    s.setItem(key, value)
+  } catch {
+    // Modo privativo / storage bloqueado — o contexto degrada, o evento segue.
+  }
+}
+
+function randomId(): string {
+  try {
+    return crypto.randomUUID()
+  } catch {
+    return `hol-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+  }
+}
+
+/** ID da sessão de browser · vive enquanto a aba viver. */
+export function resolveSessionId(): string {
+  const existing = readStorage('session', SESSION_STORAGE_KEY)
+  if (existing) return existing
+  const fresh = randomId()
+  writeStorage('session', SESSION_STORAGE_KEY, fresh)
+  return fresh
+}
+
+/**
+ * Atribuição da sessão: utm da primeira página + referrer externo de entrada.
+ * Gravada uma vez e repetida em todo evento da sessão.
+ */
+export function resolveAttribution(href: string, referrer: string, currentHost: string): WebContext {
+  const stored = readStorage('session', ATTRIBUTION_STORAGE_KEY)
+  if (stored) {
+    try {
+      return JSON.parse(stored) as WebContext
+    } catch {
+      // Valor corrompido — recalcula por cima.
+    }
+  }
+
+  const attribution: WebContext = { ...parseUtm(href) }
+
+  const referrerHost = hostOf(referrer)
+  // Referrer interno não é origem de tráfego, é navegação.
+  if (referrerHost && referrerHost !== currentHost) {
+    const clean = stripUrl(referrer)
+    if (clean) attribution.referrer = clean
+    attribution.referrer_host = referrerHost
+  }
+
+  writeStorage('session', ATTRIBUTION_STORAGE_KEY, JSON.stringify(attribution))
+  return attribution
+}
+
+function hostOf(href: string): string | null {
+  try {
+    return new URL(href).hostname.toLowerCase() || null
+  } catch {
+    return null
+  }
+}
+
+/* ── Montagem ─────────────────────────────────────────────────────────────── */
+
+/**
+ * Contexto completo do evento atual. Fora do browser devolve `{}` — o SDK
+ * server tem o próprio caminho e não deve inventar ambiente.
+ */
+export function buildWebContext(): WebContext {
+  if (typeof window === 'undefined' || typeof location === 'undefined') return {}
+
+  const href = location.href
+  const referrer = typeof document !== 'undefined' ? document.referrer : ''
+  const host = location.hostname.toLowerCase()
+
+  const ua = typeof navigator !== 'undefined' ? navigator.userAgent : ''
+  const { browser, os, device } = parseUserAgent(ua)
+
+  const url = stripUrl(href)
+
+  return {
+    ...(url ? { url } : {}),
+    path: location.pathname || '/',
+    host,
+    ...(browser ? { browser } : {}),
+    ...(os ? { os } : {}),
+    ...(device ? { device } : {}),
+    ...(typeof navigator !== 'undefined' && navigator.language
+      ? { locale: navigator.language }
+      : {}),
+    session_id: resolveSessionId(),
+    ...resolveAttribution(href, referrer, host),
+  }
+}

package/src/web.ts

@@ -0,0 +1,108 @@
+/**
+ * @holdyapp/sdk/web · browser (source: sdk_web).
+ *
+ * anonymous_id gerado e persistido em localStorage (holdy_anon_id) — enviado em
+ * todo event até identify() promover pra user_id (identity graph faz o merge
+ * downstream, nunca o SDK). Flush no pagehide via fetch keepalive.
+ *
+ * Todo evento carrega o contexto de ambiente (url, path, referrer externo,
+ * utm da sessão, browser, os, device, locale, session_id) em `context` —
+ * separado das properties do produto. Pageview é automático por default:
+ * carregamento inicial e cada mudança de rota, inclusive em SPA.
+ */
+
+import { HoldyCore } from './core'
+import { installAutoCapture, type NavigationKind } from './auto-capture'
+import { buildWebContext } from './web-context'
+import type { HoldyOptions, Properties } from './types'
+
+const ANON_STORAGE_KEY = 'holdy_anon_id'
+
+export interface HoldyWebOptions extends HoldyOptions {
+  /**
+   * Emitir `$pageview` sozinho no load e a cada mudança de rota · default true.
+   * Desligue só se o produto já chama `page()` na mão em cada tela.
+   */
+  autoCapture?: boolean
+}
+
+export class HoldyWeb extends HoldyCore {
+  private teardownAutoCapture: (() => void) | null = null
+
+  constructor(opts: HoldyWebOptions) {
+    super('sdk_web', opts)
+    this.anonymousId = resolveAnonymousId()
+
+    if (typeof window !== 'undefined') {
+      window.addEventListener('pagehide', () => void this.flush())
+      document.addEventListener('visibilitychange', () => {
+        if (document.visibilityState === 'hidden') void this.flush()
+      })
+    }
+
+    if (opts.autoCapture !== false) {
+      this.teardownAutoCapture = installAutoCapture({
+        onNavigate: (kind: NavigationKind) => this.page(undefined, { navigation: kind }),
+      })
+    }
+  }
+
+  /**
+   * Pageview. O `$` marca evento emitido pelo SDK, não pelo produto (mesma
+   * convenção de `$identify`/`$group`); a canonicalização downstream remove o
+   * sigilo, então `$pageview` e `pageview` são o mesmo evento na leitura.
+   * url/path/referrer/utm já vêm no context de todo evento — aqui só entra o
+   * que é da página como conteúdo (nome e título).
+   */
+  page(name?: string, properties?: Properties): void {
+    this.track('$pageview', {
+      ...(properties ?? {}),
+      ...(name ? { page_name: name } : {}),
+      ...(typeof document !== 'undefined' && document.title ? { title: document.title } : {}),
+    })
+  }
+
+  reset(): void {
+    this.userId = null
+    this.accountKey = null
+    try {
+      localStorage.removeItem(ANON_STORAGE_KEY)
+    } catch {
+      // storage indisponível (SSR/privacy mode) — ok
+    }
+    this.anonymousId = resolveAnonymousId()
+  }
+
+  /** Flush final + desinstala o auto-capture (devolve `history` ao original). */
+  override async shutdown(): Promise<void> {
+    this.teardownAutoCapture?.()
+    this.teardownAutoCapture = null
+    await super.shutdown()
+  }
+
+  protected override environmentContext(): Properties {
+    return buildWebContext()
+  }
+}
+
+function resolveAnonymousId(): string {
+  try {
+    const existing = localStorage.getItem(ANON_STORAGE_KEY)
+    if (existing) return existing
+    const fresh = crypto.randomUUID()
+    localStorage.setItem(ANON_STORAGE_KEY, fresh)
+    return fresh
+  } catch {
+    return crypto.randomUUID()
+  }
+}
+
+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)
+  return singleton
+}
+
+export type { HoldyOptions, Properties }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Holdy
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/dist/anchor.d.ts

@@ -1,8 +0,0 @@
-/**
- * Anchor resolver · MutationObserver-based.
- *
- * Cliente do produto pode renderizar o anchor depois do decision chegar
- * (SPA route, lazy mount). Resolver espera até 5s antes de desistir.
- * Single observer global · cap retries por selector.
- */
-export declare function resolveAnchor(selector: string | undefined): Promise<Element | null>;