@leapio/web 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+Leapio Web SDK
+Copyright 2026 Elevate Labs LLC

package/README.md

@@ -1,3 +1,306 @@
-# Temporary Holding Version
+# @leapio/web
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Leapio SDK for browser applications built with React, Next.js, Angular, etc.
+
+## Installation
+
+```sh
+npm install @leapio/web
+# or
+pnpm add @leapio/web
+# or
+yarn add @leapio/web
+# or
+bun add @leapio/web
+```
+
+## Usage
+
+### Init
+
+```js
+import leapio from "@leapio/web";
+
+leapio.init({ publicKey: "YOUR_PUBLIC_KEY", cookiesDisabled: true });
+```
+
+The named export is the same instance: `import { leapio } from "@leapio/web"`.
+CommonJS works too: `const { leapio } = require("@leapio/web")`.
+
+- `publicKey` - project public key
+- `cookiesDisabled` - use this property to disable cookie persistence (anonymous id falls back to localStorage / in-memory)
+- `enableAutoPageviews` - enable auto tracking of pageviews, including SPA route changes (default: true)
+- `legacySpaDetection` - fall back to the legacy MutationObserver-based SPA route detection instead of the default History-API method (default: false; see [Single-page apps](#single-page-apps-spa-pageviews))
+- `stickyCampaigns` - enable storing UTM parameters in cookies (default: true)
+- `stickyCampaignsExpirationInSeconds` - timeout for sticky campaigns (default: 7 days)
+- `enableAutoClicks` - enable auto capture of user clicks (default: false)
+- `externalApiUrl` - provide here API proxy url for the track endpoint (e.g. `https://api.example.com/i`)
+- `identifyApiUrl` - optional override for the identify endpoint. If omitted and `externalApiUrl` ends in `/i` or `/track`, the SDK derives `/identify` from the same origin; otherwise defaults to `https://api.leapio.com/identify`
+- `tagPaymentLinks` - add the anonymous id as `client_reference_id` to Stripe Payment Links (`buy.stripe.com`) when they are clicked, so payments are attributed without building the URL yourself. An existing `client_reference_id` is never overwritten, and nothing is tagged while consent withholds sending (default: true)
+- `engagement` - engaged-time tracking: `"leave"` sends a `Page Leave` event when a page is hidden or left, `"heartbeat"` also sends a `Page Heartbeat` each visible minute (capped at 30 per page). Both carry `engaged_seconds`, count as events, and make session duration reflect when the visitor actually left. Overrides the project's dashboard setting, which defaults to off
+- `trackAutomatedBrowsers` - track browsers driven by WebDriver (`navigator.webdriver`, e.g. Playwright or Selenium). Off by default so test runs and scrapers don't count as visitors (default: false)
+- `onLoad` - use this function to perform actions when Leapio is loaded. E.g. register super properties before initial pageview
+
+### Track
+
+```js
+leapio.track({
+  event: "UserSubscribed",
+  channel: "Sign ups",
+  notify: true,
+  message: "john@doe.com has subscribed",
+  userId: "john@doe.com",
+  metadata: { additionalData: "123" },
+});
+```
+
+### Pageview
+
+```js
+leapio.pageview({
+  userId: "john@doe.com",
+  metadata: { additionalData: "123" },
+});
+```
+
+### Single-page apps (SPA pageviews)
+
+With `enableAutoPageviews` on (the default), the SDK tracks client-side route
+changes in single-page apps as additional pageviews. Detection uses the History
+API: it patches `history.pushState` / `history.replaceState` and listens for
+`popstate` (back/forward) and `hashchange` (hash routers). A route change whose
+resulting URL is unchanged is ignored, so a `replaceState` that only normalizes
+the URL does not double-count. The patched history methods are restored on
+`reset()`.
+
+This is **core behavior**, independent of [Autocapture](#autocapture) — it works
+whether autocapture is on or off. Set `legacySpaDetection: true` to fall back to
+the older MutationObserver heuristic if you depend on it.
+
+### Register
+
+```js
+leapio.register({
+  email: "john@doe.com",
+  authenticated: true,
+  project: "SuperStartup",
+});
+```
+
+### Identify
+
+Associate the current anonymous browser session with a known user. Subsequent
+`track()` and `pageview()` calls include both the `anonymous_id` and the
+identified `user_id`.
+
+```js
+await leapio.identify("user_123", {
+  email: "user@example.com",
+  plan: "pro",
+});
+```
+
+With Secure Mode (server-issued JWT verifying the user id):
+
+```js
+const result = await leapio.identify(
+  "user_123",
+  { email: "user@example.com" },
+  { identityVerification: { token: jwtFromYourBackend } }
+);
+
+if (!result.ok) {
+  // result.status / result.reason indicate why (e.g. 401 / "invalid_token")
+}
+```
+
+### Reset
+
+Clear registered super-properties, drop the identified user, and rotate the
+`anonymous_id`. Use on logout. Does not call the network.
+
+```js
+leapio.reset();
+```
+
+## Autocapture
+
+Autocapture lets you collect common interactions without writing per-element
+tracking code. It is **off by default** and privacy-first: it never records what
+people type, form-field values, or sensitive inputs, and autocaptured events
+flow through the same consent pipeline as every other event.
+
+### Capture types
+
+When autocapture is enabled, each type can be toggled independently:
+
+| Type | Event name | Metadata | Default (when autocapture on) |
+|---|---|---|---|
+| `outboundLinks` | `Outbound Link` | `{ href, text }` | on |
+| `fileDownloads` | `File Downloaded` | `{ href, fileName, fileExtension }` | on |
+| `formSubmissions` | `Form Submitted` | `{ id, name, action }` (never field values) | on |
+| `clicks` | `Click` | `{ tag, id, text, href }` | off (noisy) |
+| `inputChanges` | `Input Changed` | `{ name, type }` (never the value) | off |
+| `mediaPlayback` | `Media Played/Paused/Progress/Completed` | `{ src, duration, current_time, percent }` (never a recording) | off |
+
+File downloads fire on a click of an `<a href>` that either carries a
+`download` attribute or whose URL ends in a known download extension. The
+built-in default list is
+`pdf, zip, csv, xlsx, doc, docx, ppt, pptx, dmg, pkg, mp3, mp4, wav`; your
+project's dashboard can override it (the server-provided list **replaces** the
+defaults). Matching is case-insensitive and ignores a leading dot.
+
+### Enabling autocapture (npm)
+
+```js
+leapio.init({ publicKey: "YOUR_PUBLIC_KEY", autocapture: true });
+
+// or per-type:
+leapio.init({
+  publicKey: "YOUR_PUBLIC_KEY",
+  autocapture: { outboundLinks: true, fileDownloads: true, formSubmissions: false },
+});
+```
+
+### Enabling autocapture (CDN snippet)
+
+The CDN wrapper (`leapio-js`, served as `lp.js`) reads `data-*` attributes off
+the `<script>` tag:
+
+| Attribute | Effect |
+|---|---|
+| `data-autocapture` | master toggle (`true` / `false`) |
+| `data-autocapture-outbound` | toggle outbound-link capture |
+| `data-autocapture-downloads` | toggle file-download capture |
+| `data-autocapture-forms` | toggle form-submission capture |
+| `data-autocapture-clicks` | toggle generic element-click capture |
+| `data-autocapture-inputs` | toggle input-change capture |
+
+```html
+<script
+  src="https://cdn.leapio.com/lp.js"
+  data-leapio-pk="YOUR_PUBLIC_KEY"
+  data-autocapture="true"
+  data-autocapture-forms="false"
+></script>
+```
+
+`data-autocapture` is the **master** switch — it (or the dashboard) is what turns
+autocapture on or off. A per-type `data-autocapture-<type>` attribute overrides
+that one type (on *or* off) but does **not** by itself enable autocapture: a bare
+`data-autocapture-forms="false"` on a project whose dashboard setting is *off*
+leaves autocapture off. To turn autocapture on, set `data-autocapture` (or enable
+it in the dashboard).
+
+### Configuration precedence
+
+The dashboard sets your project defaults; the snippet overrides any setting it
+names; **enabling requires the master**. Concretely:
+
+- **Master (enablement)** resolves as
+  `data-autocapture (if set) ?? server "enabled" ?? off`.
+  A bare per-type attribute does not participate in enablement.
+- **Per-type** (applies only once the master is on) resolves **per key**, snippet
+  winning both directions:
+
+  ```
+  effective(type) = snippet data-autocapture-<type> (if set) ?? server config ?? built-in default
+  ```
+
+`outboundLinks`, `fileDownloads`, and `formSubmissions` are server-configurable;
+`clicks` and `inputChanges` are snippet-only. If no config enables autocapture at
+all, it stays **off** — core pageview tracking is independent and unaffected.
+
+### Declarative events (`data-leapio-*`)
+
+Tag any element to fire a named event on click, with optional metadata props.
+This works whenever autocapture is enabled and takes precedence over the
+built-in capture types:
+
+```html
+<button
+  data-leapio-event="Upgrade Clicked"
+  data-leapio-prop-plan="pro"
+  data-leapio-prop-source="hero"
+>
+  Upgrade
+</button>
+```
+
+- `data-leapio-event="<Event Name>"` — the event name to emit on click. The
+  handler walks up to the nearest ancestor carrying the attribute.
+- `data-leapio-prop-<key>="<value>"` — each becomes a metadata key/value.
+
+### Sensitive data
+
+- Form submissions and input-change events capture **metadata only** — never the
+  field values.
+- Inputs marked sensitive are skipped entirely: `type="password"`, fields with
+  `autocomplete` of `one-time-code` / `current-password` / `new-password` /
+  `cc-*`, and any element (or ancestor) carrying `data-leapio-sensitive`.
+
+### Anonymous ID storage
+
+On init the SDK ensures an `anonymous_id` exists, persisted with this chain:
+
+1. First-party cookie `leapio_anonymous_id`
+2. `localStorage` key `leapio_anonymous_id`
+3. In-memory fallback
+
+You can read the current value via `leapio.getAnonymousId()`.
+
+## Browser storage reference
+
+All keys are first-party (set on the customer's domain, not `leapio.com`).
+Cookie domain is configurable via `cookieDomain`.
+
+| Key | Where | Default TTL | Purpose | Set when |
+|---|---|---|---|---|
+| `leapio_anonymous_id` | cookie | 1 year (override: `cookieExpirationInSeconds`) | anonymous browser id sent on every track/identify | `init()` |
+| `leapio_anonymous_id` | localStorage | persistent | fallback for the anonymous id when cookies are unavailable or `cookiesDisabled: true` | `init()` |
+| `leapio_p` | cookie | 30 days | base64-encoded JSON of registered super-properties, merged into every event | `register()` |
+| `leapio_c` | cookie | 7 days (override: `stickyCampaignsExpirationInSeconds`) | base64-encoded JSON of sticky UTM/campaign params | first pageview when `stickyCampaigns: true` |
+| `leapio_ft` | cookie | 1 year | base64-encoded JSON of durable first-touch attribution (UTM/click-ids, external referrer, landing url); set once, never overwritten; sent as `first_touch` inside `identify()` traits | first visit carrying a campaign param or external referrer |
+| `leapio_consent` | cookie (localStorage/in-memory fallback) | 1 year | current consent snapshot (categories, privacy signals, source) stamped on every event | first consent snapshot (CMP adapter, `setConsent()`, or Google Consent Mode read) |
+| `leapio_cfg_<publicKey>` | localStorage | 24h freshness window | cached per-project remote config (autocapture settings) delivered on track responses | first successful track response |
+| `leapio_acov_<publicKey>` | localStorage | persistent | fingerprint of the last reported snippet-override set (dashboard "overridden by snippet" flag) | when the snippet overrides dashboard autocapture settings |
+| `leapio_dnt` | localStorage | persistent | explicit opt-out marker; while present, no events are sent | visiting any page with `?dnt` in the query string; `?dnt=false` (or `?dnt=0`) removes it |
+
+### Disabling persistence
+
+- `cookiesDisabled: true` — the SDK skips cookie writes entirely. The anonymous
+  id falls back to localStorage, then to in-memory if localStorage is also
+  unavailable. Other cookies (`leapio_p`, `leapio_c`) are simply not written.
+- `?dnt` in the URL or `enableBrowserDNT: true` (with browser DNT on) — the SDK
+  no-ops on every track/identify call for this visitor. Visit with `?dnt=false`
+  to opt the browser back in. Use `?dnt` to exclude your own visits.
+
+### Consent
+
+A granular consent layer works alongside the binary `leapio_dnt` flag:
+
+- `setConsent({ analytics, functional, marketing, doNotSellShare })` /
+  `getConsent()` manage an explicit snapshot (source `leapio_api`, highest
+  priority).
+- `consentSources: ["concord", "onetrust", "usercentrics", "cookiebot", "gcm"]`
+  registers read-only CMP adapters that mirror the vendor banner's state and
+  subscribe to its change events.
+- `consentBehavior` controls egress: `notRequired` (default) always sends and
+  lets the server enforce; `implied` sends until analytics is explicitly
+  denied; `express` queues events in memory (max 100) until analytics is
+  explicitly granted, and drops the queue on denial.
+- Browser privacy signals (Global Privacy Control, GPP presence/string) are
+  detected at init and merged into every snapshot; every track/identify payload
+  is stamped with `privacy_categories` / `privacy_signals` / `consent_source`,
+  and accepted snapshot changes are pushed to `POST /consent` once per change.
+
+### URL privacy (query-param stripping)
+
+- `stripQueryParams: true` removes non-allow-listed query params and the hash
+  from the event `url` and `referrer` (and any URL the SDK reports, e.g. the
+  snippet-override sample url and first-touch urls) before sending.
+- `queryParamAllowlist: string[]` overrides the kept params (default: UTM
+  params incl. `utm_id`, ad click-ids, `ref`; exported as
+  `DEFAULT_QUERY_PARAM_ALLOWLIST`).
+- CDN equivalents: `data-strip-query-params`, `data-query-param-allowlist`.
+- This is defense-in-depth; the server strips authoritatively regardless.