@holdyapp/sdk 0.2.1 → 1.0.1

package/dist/server.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @holdyapp/sdk (server) · Node/Edge (source: sdk_server).
+ *
+ * Stateless por default: user_id/accountKey vão por chamada em overrides.
+ * identify()/group() de sessão existem mas em server multi-tenant prefira
+ * overrides — estado compartilhado entre requests vaza identidade.
+ */
+import { HoldyCore } from './core';
+import type { HoldyOptions } from './types';
+export declare class Holdy extends HoldyCore {
+    constructor(opts: HoldyOptions);
+}
+export { HoldyCore, DEFAULT_BASE_URL } from './core';
+export type { HoldyOptions, Properties, TrackOverrides, CanonicalEvent } from './types';
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +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"}

package/dist/server.mjs

@@ -0,0 +1,148 @@
+// src/core.ts
+var DEFAULT_BASE_URL = "https://holdy.chat/api/v1";
+var DEFAULT_FLUSH_AT = 20;
+var DEFAULT_FLUSH_INTERVAL_MS = 5e3;
+var MAX_QUEUE = 1e3;
+var BULK_LIMIT = 500;
+var HoldyCore = class {
+  apiKey;
+  baseUrl;
+  flushAt;
+  debug;
+  source;
+  queue = [];
+  timer = null;
+  flushing = null;
+  userId = null;
+  anonymousId = null;
+  accountKey = null;
+  constructor(source, opts) {
+    this.source = source;
+    this.apiKey = opts.apiKey;
+    this.accountKey = opts.accountKey ?? null;
+    this.baseUrl = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.flushAt = Math.max(1, opts.flushAt ?? DEFAULT_FLUSH_AT);
+    this.debug = opts.debug ?? false;
+    const intervalMs = opts.flushIntervalMs ?? DEFAULT_FLUSH_INTERVAL_MS;
+    if (intervalMs > 0) {
+      this.timer = setInterval(() => void this.flush(), intervalMs);
+      if (typeof this.timer.unref === "function") {
+        ;
+        this.timer.unref();
+      }
+    }
+  }
+  track(name, properties, overrides) {
+    if (!name || typeof name !== "string") return;
+    const userId = overrides?.userId ?? this.userId ?? void 0;
+    const accountKey = overrides?.accountKey ?? this.accountKey ?? void 0;
+    const occurredAt = overrides?.occurredAt ? new Date(overrides.occurredAt).toISOString() : (/* @__PURE__ */ new Date()).toISOString();
+    const context = {
+      ...this.environmentContext(),
+      ...overrides?.context ?? {}
+    };
+    if (accountKey) context.account_external_id = accountKey;
+    const event = {
+      event: name,
+      occurred_at: occurredAt,
+      source: this.source,
+      ...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);
+    if (this.queue.length >= this.flushAt) void this.flush();
+  }
+  identify(userId, traits) {
+    if (!userId || typeof userId !== "string") return;
+    this.userId = userId;
+    this.track("$identify", traits ?? {});
+  }
+  group(accountKey, traits) {
+    if (!accountKey || typeof accountKey !== "string") return;
+    this.accountKey = accountKey;
+    this.track("$group", traits ?? {});
+  }
+  /** Drena a fila. Nunca lança — falha re-enfileira e loga em debug. */
+  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;
+  }
+  /** Flush final + para o timer. Chamar em shutdown do server / unload do web. */
+  async shutdown() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    await this.flush();
+  }
+  async drain() {
+    while (this.queue.length > 0) {
+      const batch = this.queue.splice(0, BULK_LIMIT);
+      const ok = await this.send(batch);
+      if (!ok) {
+        this.queue.unshift(...batch);
+        return;
+      }
+    }
+  }
+  async send(events) {
+    try {
+      const res = await fetch(`${this.baseUrl}/events/bulk`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        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;
+      }
+      return true;
+    } catch (err) {
+      this.log(`bulk network error: ${err.message} \xB7 will retry`);
+      return false;
+    }
+  }
+  log(msg) {
+    if (this.debug) 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
+   * existe "página atual" num worker.
+   */
+  environmentContext() {
+    return {};
+  }
+  /** Interno · exposto pra testes. */
+  get pending() {
+    return this.queue.length;
+  }
+};
+
+// src/server.ts
+var Holdy = class extends HoldyCore {
+  constructor(opts) {
+    super("sdk_server", opts);
+  }
+};
+export {
+  DEFAULT_BASE_URL,
+  Holdy,
+  HoldyCore
+};
+//# sourceMappingURL=server.mjs.map

package/dist/server.mjs.map

@@ -0,0 +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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",
+  "names": []
+}

package/dist/types.d.ts

@@ -1,114 +1,46 @@
-export type CanonicalPrimitive = 'workflow.started' | 'workflow.progressed' | 'workflow.blocked' | 'workflow.completed' | 'workflow.abandoned' | 'outcome.progressed' | 'outcome.completed' | 'outcome.regressed' | 'friction.detected' | 'collaboration.invited' | 'collaboration.joined' | 'collaboration.deepened' | 'collaboration.weakened' | 'collaboration.champion_lost' | 'support.escalated' | 'support.sentiment_negative' | 'support.theme_detected' | 'expansion.intent_detected' | 'expansion.ceiling_hit' | 'memory.append' | 'session.activity';
-export type DecisionType = 'intervention' | 'briefing' | 'cs_task' | 'track_journey' | 'no_action';
-export type InterventionKind = 'tooltip' | 'banner' | 'modal' | 'checklist' | 'spotlight' | 'cta';
-export interface ChecklistItem {
-    /** ID estável · persistência local + dedup. */
-    id: string;
-    label: string;
-    /** Opcional · link aberto ao clicar. Sem href, item só marca completed. */
-    href?: string;
-    /** Workflow ou outcome primitive que marca esse item como completed quando emitido. */
-    completed_event?: string;
-    /** Pré-marcado · server pode indicar que cliente já fez essa etapa. */
-    completed?: boolean;
-}
-export interface InterventionPayload {
-    kind: InterventionKind;
-    text: string;
-    /** Título opcional · usado em modal/checklist headers. */
-    title?: string;
-    cta_text?: string;
-    cta_href?: string;
-    anchor_selector?: string;
-    /** Items pro kind=checklist. */
-    items?: ChecklistItem[];
-}
-export interface DecisionResult {
-    decision_id: string;
-    decision_type: DecisionType;
-    decision_payload: InterventionPayload | Record<string, unknown>;
-    rule_key: string;
-    confidence: number;
-    reason: string;
-    decided_at: string;
-}
-export type OutcomeValue = 'executed' | 'dismissed' | 'converted' | 'no_show' | 'failed';
-export interface RuntimeConfig {
-    api_version: string;
-    taxonomy_version: string;
-    organization_id: string;
-    thresholds: Record<string, number | string>;
-    features: {
-        auto_attribution: boolean;
-        interventions_enabled: boolean;
-        consent_required: boolean;
-    };
-    theme?: ThemeConfig;
-}
-export interface ThemeConfig {
-    primary_color: string;
-    font_family: string;
-    border_radius_px: number;
-    position_offset_px: number;
-}
-export declare const DEFAULT_THEME: ThemeConfig;
-export interface HoldyConfig {
-    apiKey: string;
-    apiUrl?: string;
-    accountId?: string;
-    userId?: string;
-    sessionId?: string;
-    consumer?: 'ui' | 'csm' | 'agent';
-    debug?: boolean;
-    /** Disables render runtime · SDK só captura telemetry. */
-    renderInterventions?: boolean;
-    /**
-     * Stage 28 · auto-capture de page views (initial_load + route_change +
-     * visibility_change). Quando true, SDK monkeypatcha history.pushState/
-     * replaceState + escuta popstate/visibilitychange e emite session.activity
-     * sem código manual. Default false pra back-compat.
-     */
-    autoCapture?: boolean;
-}
 /**
- * Rich account metadata enviado pra /v1/accounts/upsert.
- * Backend usa COALESCE — não sobrescreve campos preenchidos no wizard manual.
+ * Tipos públicos do @holdyapp/sdk (entry-contract.md §2 + §6).
  *
- * `external_id` é o identificador do cliente (string opaca · ex "acct_abc123").
- * Backend resolve via customer_identities(source='sdk') → accounts.id.
+ * Envelope idêntico ao CanonicalEventInputSchema do servidor — o SDK nunca
+ * inventa campo. account_id (uuid Holdy) não existe aqui: a chave do cliente
+ * viaja em context.account_external_id e a Data layer resolve (regra 4).
  */
-export interface AccountIdentity {
-    external_id: string;
-    name?: string;
-    logo_url?: string;
-    domain?: string;
-    plan?: string;
-    mrr?: number;
-    contract_start?: string;
-    contract_end?: string;
-    lifecycle_stage?: 'onboarding' | 'adoption' | 'expansion' | 'renewal' | 'churned';
-    traits?: Record<string, string | number | boolean | null>;
-}
-export interface UserIdentity {
-    external_id: string;
-    email?: string;
-    name?: string;
-    job_title?: string;
-    role?: 'decision_maker' | 'champion' | 'admin' | 'user' | 'unknown';
+export type Properties = Record<string, unknown>;
+export interface CanonicalEvent {
+    event: string;
+    occurred_at: string;
+    source: 'sdk_web' | 'sdk_server';
+    user_id?: string;
+    anonymous_id?: string;
+    properties: Properties;
+    context?: Properties;
+}
+export interface HoldyOptions {
+    /** API key `hol_{env}_...` com scope events:write. */
+    apiKey: string;
+    /** Override · default https://holdy.chat/api/v1 */
+    baseUrl?: string;
+    /** Flush automático quando a fila atinge este tamanho · default 20. */
+    flushAt?: number;
+    /** Flush automático a cada N ms · default 5000. 0 desliga o timer. */
+    flushIntervalMs?: number;
+    /**
+     * Chave da account do cliente (`context.account_external_id`). Define o
+     * vínculo sem emitir evento — `group()` continua sendo a chamada pra
+     * declarar a account COM traits.
+     */
+    accountKey?: string;
+    /** Logs de debug no console. */
+    debug?: boolean;
 }
-export interface IdentifyOptions {
-    /** ID interno Holdy (UUID) · opcional · usado pra retro-compat. */
-    accountId?: string;
+export interface TrackOverrides {
+    /** Server-side: end-user do evento (stateless por chamada). */
     userId?: string;
-    sessionId?: string;
-    /** Metadata rica · gera best-effort upsert em /v1/accounts/upsert. */
-    account?: AccountIdentity;
-    user?: UserIdentity;
-}
-export interface TrackOptions {
-    /** Pula chamada implícita ao decisions/evaluate. */
-    skipEval?: boolean;
-    /** Workflow corrente · override do estado interno. */
-    workflow?: string;
-}
-export type DecisionListener = (decision: DecisionResult) => void;
+    /** Server-side: chave de account do cliente (context.account_external_id). */
+    accountKey?: string;
+    /** Timestamp do evento · default agora. */
+    occurredAt?: Date | string;
+    /** Metadata adicional pro context. */
+    context?: Properties;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +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"}

package/dist/web-context.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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>;
+/** `https://app.x.com/a/b?q=1#z` → `https://app.x.com/a/b`. */
+export declare function stripUrl(href: string): string | null;
+/** Parâmetros de campanha presentes na URL, já em lowercase. */
+export declare function parseUtm(href: string): WebContext;
+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 declare function parseUserAgent(ua: string): UaParts;
+/** ID da sessão de browser · vive enquanto a aba viver. */
+export declare function resolveSessionId(): string;
+/**
+ * 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 declare function resolveAttribution(href: string, referrer: string, currentHost: string): WebContext;
+/**
+ * Contexto completo do evento atual. Fora do browser devolve `{}` — o SDK
+ * server tem o próprio caminho e não deve inventar ambiente.
+ */
+export declare function buildWebContext(): WebContext;
+export {};
+//# sourceMappingURL=web-context.d.ts.map

package/dist/web-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-context.d.ts","sourceRoot":"","sources":["../src/web-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;AAe/C,+DAA+D;AAC/D,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOpD;AAED,gEAAgE;AAChE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAYjD;AAID,UAAU,OAAO;IACf,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CA6ClD;AA8BD,2DAA2D;AAC3D,wBAAgB,gBAAgB,IAAI,MAAM,CAMzC;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,CAsBlG;AAYD;;;GAGG;AACH,wBAAgB,eAAe,IAAI,UAAU,CAyB5C"}

package/dist/web.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @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 type { HoldyOptions, Properties } from './types';
+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 declare class HoldyWeb extends HoldyCore {
+    private teardownAutoCapture;
+    constructor(opts: HoldyWebOptions);
+    /**
+     * 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;
+    reset(): void;
+    /** Flush final + desinstala o auto-capture (devolve `history` ao original). */
+    shutdown(): Promise<void>;
+    protected environmentContext(): Properties;
+}
+/** Init idempotente — segunda chamada retorna a instância existente. */
+export declare function initHoldy(opts: HoldyWebOptions): HoldyWeb;
+export type { HoldyOptions, Properties };
+//# sourceMappingURL=web.d.ts.map

package/dist/web.d.ts.map

@@ -0,0 +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,CAGzD;AAED,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,CAAA"}