form-attribution 1.0.0

package/LICENSE.md

@@ -0,0 +1,201 @@
+                                 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 2025 Ben Sabic
+
+   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/README.md

@@ -0,0 +1,227 @@
+# form-attribution
+
+Automatically capture and persist marketing attribution parameters (UTM tags, referrer data, landing pages) and inject them into HTML forms as hidden fields.
+
+## Features
+
+- **Zero dependencies** - Self-contained script using only browser APIs
+- **Automatic capture** - Captures UTM parameters, referrer, landing page, and timestamps
+- **Persistent storage** - Stores attribution data across page visits with smart fallbacks
+- **Form injection** - Injects hidden fields into all forms automatically
+- **Dynamic form support** - Detects and injects into dynamically added forms via MutationObserver
+- **First-touch attribution** - Preserves initial attribution data across subsequent visits
+- **Privacy-respecting** - Honors Global Privacy Control (GPC) and Do Not Track (DNT) signals
+- **XSS-safe** - Sanitizes all values before injection
+
+## Installation
+
+### CDN
+
+*jsDelivr:*
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/form-attribution@latest/dist/script.min.js"></script>
+```
+
+*unpkg:*
+
+```html
+<script src="https://unpkg.com/form-attribution@latest/dist/script.min.js"></script>
+```
+
+## Quick Start
+
+Add the script to your HTML before the closing `</body>` tag:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/form-attribution@latest/dist/script.min.js"></script>
+```
+
+That's it! The script will automatically:
+
+1. Capture UTM parameters from the URL
+2. Store them in sessionStorage
+3. Inject hidden fields into all forms on the page
+
+## Parameters Captured
+
+### URL Parameters (default)
+
+| Parameter | Description |
+|-----------|-------------|
+| `utm_source` | Traffic source (e.g., google, newsletter) |
+| `utm_medium` | Marketing medium (e.g., cpc, email) |
+| `utm_campaign` | Campaign name |
+| `utm_term` | Paid search keywords |
+| `utm_content` | Content variant for A/B testing |
+| `utm_id` | Campaign ID |
+| `ref` | Referrer tracking parameter |
+
+### Metadata (automatically captured)
+
+| Parameter | Description |
+|-----------|-------------|
+| `landing_page` | First page URL visited (without query string) |
+| `current_page` | Current page URL (without query string) |
+| `referrer_url` | Document referrer |
+| `first_touch_timestamp` | ISO 8601 timestamp of first visit |
+
+## Configuration
+
+Configure the script using `data-*` attributes on the script tag:
+
+```html
+<script src="/dist/script.js"
+  data-storage="sessionStorage"
+  data-field-prefix="attr_"
+  data-extra-params="gclid,fbclid"
+  data-exclude-forms=".no-track"
+  data-debug="true">
+</script>
+```
+
+### Options
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `data-storage` | `sessionStorage` | Storage method: `sessionStorage`, `localStorage`, or `cookie` |
+| `data-field-prefix` | `""` | Prefix for hidden field names (e.g., `attr_` creates `attr_utm_source`) |
+| `data-extra-params` | `""` | Comma-separated list of additional URL parameters to capture |
+| `data-exclude-forms` | `""` | CSS selector for forms to exclude from injection |
+| `data-storage-key` | `form_attribution_data` | Custom key name for stored data |
+| `data-debug` | `false` | Enable console logging |
+
+### Cookie Options
+
+When using `data-storage="cookie"`:
+
+| Attribute | Default | Description |
+|-----------|---------|-------------|
+| `data-cookie-domain` | `""` | Cookie domain (e.g., `.example.com`) |
+| `data-cookie-path` | `/` | Cookie path |
+| `data-cookie-expires` | `30` | Expiration in days |
+| `data-cookie-samesite` | `lax` | SameSite policy: `lax`, `strict`, or `none` |
+
+## Usage Examples
+
+### Capture Google and Facebook Click IDs
+
+```html
+<script src="/dist/script.js"
+  data-extra-params="gclid,fbclid,msclkid">
+</script>
+```
+
+### Use localStorage for Longer Persistence
+
+```html
+<script src="/dist/script.js"
+  data-storage="localStorage">
+</script>
+```
+
+### Use Cookies for Cross-Subdomain Tracking
+
+```html
+<script src="/dist/script.js"
+  data-storage="cookie"
+  data-cookie-domain=".example.com"
+  data-cookie-expires="90">
+</script>
+```
+
+### Exclude Specific Forms
+
+```html
+<script src="/dist/script.js"
+  data-exclude-forms=".login-form, [data-no-attribution]">
+</script>
+```
+
+### Add Field Prefix for CRM Compatibility
+
+```html
+<script src="/dist/script.js"
+  data-field-prefix="lead_">
+</script>
+```
+
+This creates fields like `lead_utm_source`, `lead_utm_medium`, etc.
+
+## Script Builder
+
+Use the interactive [Script Builder](script-builder/index.html) tool to generate a configured script tag with a visual interface.
+
+## Storage Fallback Chain
+
+The script uses intelligent fallback when storage is unavailable:
+
+| Requested | Fallback Chain |
+|-----------|----------------|
+| `localStorage` | localStorage → sessionStorage → cookie → memory |
+| `sessionStorage` | sessionStorage → cookie → memory |
+| `cookie` | cookie → memory |
+
+## Privacy
+
+The script respects user privacy preferences:
+
+- **Global Privacy Control (GPC)** - Disables tracking when `navigator.globalPrivacyControl` is true
+- **Do Not Track (DNT)** - Disables tracking when DNT is enabled
+
+When privacy signals are detected, no data is captured or stored.
+
+## Injected Fields
+
+Hidden fields are injected with the following attributes:
+
+```html
+<input type="hidden"
+  name="utm_source"
+  value="google"
+  data-form-attribution="true"
+  data-form-attribution-managed="true">
+```
+
+- Existing hidden fields with matching names are updated (no duplicates created)
+- User-visible form fields are never modified
+- All values are HTML-entity encoded for XSS protection
+
+## Development
+
+### Prerequisites
+
+- Node.js
+- pnpm
+
+### Setup
+
+```bash
+pnpm install
+```
+
+### Commands
+
+```bash
+pnpm test                         # Run Playwright tests (Chromium, Firefox, WebKit)
+pnpm exec playwright test --ui    # Run tests with interactive UI
+pnpm check                        # Lint with Biome
+pnpm fix                          # Auto-fix lint issues
+```
+
+## Browser Support
+
+The script uses standard browser APIs with graceful fallbacks:
+
+- URL API for query parameter parsing
+- MutationObserver for dynamic form detection
+- Web Storage API (sessionStorage/localStorage)
+- CookieStore API with legacy `document.cookie` fallback
+
+## License
+
+[Apache-2.0](LICENSE.md)
+
+## Author
+
+[Ben Sabic](https://bensabic.ca)

package/dist/script.js

@@ -0,0 +1,859 @@
+(() => {
+  const SCRIPT_ELEMENT =
+    document.currentScript ??
+    [...document.scripts]
+      .reverse()
+      .find((s) => {
+        const src = s.getAttribute("src") || "";
+        return (
+          src.includes("cdn.jsdelivr.net/npm/form-attribution@") &&
+          src.endsWith("/dist/script.min.js")
+        );
+      }) ??
+    null;
+
+  const DEFAULT_PARAMS = [
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_term",
+    "utm_content",
+    "utm_id",
+    "ref",
+  ];
+
+  const META_PARAMS = [
+    "landing_page",
+    "current_page",
+    "referrer_url",
+    "first_touch_timestamp",
+  ];
+
+  const VALID_STORAGE_TYPES = ["sessionStorage", "localStorage", "cookie"];
+  const VALID_SAMESITE_VALUES = ["lax", "strict", "none"];
+  const MAX_COOKIE_SIZE = 4000;
+  const MAX_PARAM_LENGTH = 500;
+  const MAX_URL_LENGTH = 2000;
+
+  const safeParse = (data) => {
+    const parsed = JSON.parse(data);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      const safe = Object.create(null);
+      for (const key of Object.keys(parsed)) {
+        if (key !== "__proto__" && key !== "constructor" && key !== "prototype") {
+          safe[key] = parsed[key];
+        }
+      }
+      return safe;
+    }
+    return parsed;
+  };
+
+  const sanitizeValue = (val) => {
+    return String(val).replace(/[<>'"]/g, (char) => {
+      const entities = { "<": "&lt;", ">": "&gt;", "'": "&#39;", '"': "&quot;" };
+      return entities[char];
+    });
+  };
+
+  const validateStorageKey = (key) => {
+    const safeKey = String(key ?? "form_attribution_data").trim();
+    return /^[a-zA-Z0-9_-]+$/.test(safeKey) ? safeKey : "form_attribution_data";
+  };
+
+  const validateFieldPrefix = (prefix) => {
+    const safePrefix = String(prefix ?? "").trim();
+    return /^[a-zA-Z0-9_-]*$/.test(safePrefix) ? safePrefix : "";
+  };
+
+  const validateCookiePath = (path) => {
+    const safePath = String(path ?? "/").trim();
+    return safePath.startsWith("/") && !/[;\s]/.test(safePath) ? safePath : "/";
+  };
+
+  const validateExcludeForms = (selector) => {
+    if (!selector) {
+      return "";
+    }
+    const safe = String(selector ?? "").trim();
+    if (!/^[a-zA-Z0-9._#\[\]="':\s,>+~-]*$/.test(safe)) {
+      return "";
+    }
+    return safe;
+  };
+
+  const validateCookieDomain = (domain) => {
+    if (!domain) {
+      return undefined;
+    }
+    const safeDomain = String(domain).trim().toLowerCase();
+    if (!safeDomain) {
+      return undefined;
+    }
+    const currentHost = window.location.hostname.toLowerCase();
+
+    // Must be exact match or a parent domain of current host
+    if (safeDomain === currentHost) {
+      return safeDomain;
+    }
+    if (currentHost.endsWith("." + safeDomain)) {
+      return safeDomain;
+    }
+
+    return undefined;
+  };
+
+  const parseExtraParams = (value) => {
+    if (!value) {
+      return [];
+    }
+    const safeValue = String(value ?? "").trim();
+    return safeValue
+      ? safeValue
+          .split(",")
+          .map((p) => p.trim())
+          .filter(Boolean)
+      : [];
+  };
+
+  const parseStorageType = (value) => {
+    const raw = String(value ?? "sessionStorage").trim();
+    return VALID_STORAGE_TYPES.includes(raw) ? raw : "sessionStorage";
+  };
+
+  const parseCookieExpires = (value) => {
+    const raw = Number.parseInt(value ?? "30", 10);
+    return Number.isFinite(raw) && raw >= 0 ? raw : 30;
+  };
+
+  const parseSameSite = (value) => {
+    const raw = String(value ?? "lax")
+      .trim()
+      .toLowerCase();
+    return VALID_SAMESITE_VALUES.includes(raw) ? raw : "lax";
+  };
+
+  const getConfig = () => {
+    const dataset = SCRIPT_ELEMENT?.dataset ?? {};
+
+    return {
+      storage: parseStorageType(dataset.storage),
+      cookieDomain: validateCookieDomain(dataset.cookieDomain),
+      cookiePath: validateCookiePath(dataset.cookiePath),
+      cookieExpires: parseCookieExpires(dataset.cookieExpires),
+      cookieSameSite: parseSameSite(dataset.cookieSamesite),
+      fieldPrefix: validateFieldPrefix(dataset.fieldPrefix),
+      extraParams: parseExtraParams(dataset.extraParams),
+      excludeForms: validateExcludeForms(dataset.excludeForms),
+      debug: dataset.debug === "true",
+      storageKey: validateStorageKey(dataset.storageKey),
+    };
+  };
+
+  const CONFIG = getConfig();
+  const TRACKED_PARAMS = [
+    ...new Set([...DEFAULT_PARAMS, ...CONFIG.extraParams]),
+  ];
+  const PARAMS_TO_INJECT = [...new Set([...TRACKED_PARAMS, ...META_PARAMS])];
+
+  const log = (...args) => {
+    if (CONFIG.debug) {
+      console.log("[FormAttribution]", ...args);
+    }
+  };
+
+  const parseUrlParams = (url) => {
+    try {
+      const urlObj = new URL(url, window.location.origin);
+      return Object.fromEntries(urlObj.searchParams.entries());
+    } catch {
+      return {};
+    }
+  };
+
+  const isPrivacySignalEnabled = () => {
+    if (navigator.globalPrivacyControl === true) {
+      return true;
+    }
+
+    const dnt = navigator.doNotTrack || window.doNotTrack;
+    return dnt === "1" || dnt === "yes";
+  };
+
+  const createMemoryAdapter = () => {
+    const map = new Map();
+
+    return {
+      get(key) {
+        return Promise.resolve(map.has(key) ? map.get(key) : null);
+      },
+
+      set(key, value) {
+        map.set(key, value);
+        return Promise.resolve(true);
+      },
+
+      remove(key) {
+        map.delete(key);
+        return Promise.resolve(true);
+      },
+    };
+  };
+
+  const getUsableWebStorage = (type) => {
+    try {
+      const storage = window[type];
+      if (!storage) {
+        return null;
+      }
+
+      const testKey = "__form_attribution_test__";
+      storage.setItem(testKey, testKey);
+      storage.removeItem(testKey);
+      return storage;
+    } catch {
+      return null;
+    }
+  };
+
+  const getStorageCandidates = (requested) => {
+    if (requested === "localStorage") {
+      return ["localStorage", "sessionStorage", "cookie", "memory"];
+    }
+    if (requested === "sessionStorage") {
+      return ["sessionStorage", "cookie", "memory"];
+    }
+    if (requested === "cookie") {
+      return ["cookie", "memory"];
+    }
+    return ["sessionStorage", "cookie", "memory"];
+  };
+
+  const tryCreateAdapter = (candidate) => {
+    if (candidate === "cookie") {
+      log("Using cookie storage");
+      return createCookieAdapter();
+    }
+    if (candidate === "memory") {
+      log("Using in-memory storage");
+      return createMemoryAdapter();
+    }
+    const storage = getUsableWebStorage(candidate);
+    if (storage) {
+      log(`Using ${candidate} storage`);
+      return createWebStorageAdapter(storage);
+    }
+    return null;
+  };
+
+  const createStorageAdapter = (type) => {
+    const requested = String(type ?? "").trim();
+    const candidates = getStorageCandidates(requested);
+
+    for (const candidate of candidates) {
+      const adapter = tryCreateAdapter(candidate);
+      if (adapter) {
+        return adapter;
+      }
+    }
+
+    log("Falling back to in-memory storage");
+    return createMemoryAdapter();
+  };
+
+  const createWebStorageAdapter = (storage) => ({
+    get(key) {
+      try {
+        const data = storage.getItem(key);
+        return Promise.resolve(data ? safeParse(data) : null);
+      } catch (e) {
+        log("Storage get error:", e);
+        return Promise.resolve(null);
+      }
+    },
+
+    set(key, value) {
+      try {
+        storage.setItem(key, JSON.stringify(value));
+        return Promise.resolve(true);
+      } catch (e) {
+        log("Storage set error:", e);
+        return Promise.resolve(false);
+      }
+    },
+
+    remove(key) {
+      try {
+        storage.removeItem(key);
+        return Promise.resolve(true);
+      } catch (e) {
+        log("Storage remove error:", e);
+        return Promise.resolve(false);
+      }
+    },
+  });
+
+  const createCookieAdapter = () => {
+    const fallback = createMemoryAdapter();
+    let primaryWriteFailed = false;
+    let cookieStoreApi = null;
+
+    try {
+      cookieStoreApi = window.cookieStore ?? null;
+    } catch {
+      cookieStoreApi = null;
+    }
+
+    const useCookieStore = Boolean(
+      cookieStoreApi &&
+        typeof cookieStoreApi.get === "function" &&
+        typeof cookieStoreApi.set === "function" &&
+        typeof cookieStoreApi.delete === "function"
+    );
+
+    let forceLegacy = !useCookieStore;
+
+    const getExpirationDate = () => {
+      const date = new Date();
+      date.setDate(date.getDate() + CONFIG.cookieExpires);
+      return date;
+    };
+
+    const shouldUseSecure =
+      CONFIG.cookieSameSite === "none" || window.location.protocol === "https:";
+
+    const getSameSiteForCookieString = () => {
+      switch (CONFIG.cookieSameSite) {
+        case "strict":
+          return "Strict";
+        case "none":
+          return "None";
+        default:
+          return "Lax";
+      }
+    };
+
+    const legacyCookieAdapter = {
+      async get(key) {
+        try {
+          if (primaryWriteFailed) {
+            return await fallback.get(key);
+          }
+
+          const cookies = document.cookie.split(";");
+          for (const cookie of cookies) {
+            const [name, ...valueParts] = cookie.trim().split("=");
+            if (name === key) {
+              const value = valueParts.join("=");
+              return safeParse(decodeURIComponent(value));
+            }
+          }
+
+          return await fallback.get(key);
+        } catch (e) {
+          log("Legacy cookie get error:", e);
+          return await fallback.get(key);
+        }
+      },
+
+      async set(key, value) {
+        try {
+          const encodedValue = encodeURIComponent(JSON.stringify(value));
+          const expires = getExpirationDate().toUTCString();
+
+          let cookieStr = `${key}=${encodedValue}; path=${CONFIG.cookiePath}; expires=${expires}; SameSite=${getSameSiteForCookieString()}`;
+
+          if (CONFIG.cookieDomain) {
+            cookieStr += `; domain=${CONFIG.cookieDomain}`;
+          }
+
+          if (shouldUseSecure) {
+            cookieStr += "; Secure";
+          }
+
+          if (cookieStr.length > MAX_COOKIE_SIZE) {
+            log(
+              `Cookie size (${cookieStr.length}) exceeds limit (${MAX_COOKIE_SIZE}), falling back to memory storage`
+            );
+            primaryWriteFailed = true;
+            await fallback.set(key, value);
+            return true;
+          }
+
+          // biome-ignore lint/suspicious/noDocumentCookie: Needed for legacy cookie fallback when CookieStore API isn't available.
+          document.cookie = cookieStr;
+          await fallback.set(key, value);
+          return true;
+        } catch (e) {
+          log("Legacy cookie set error:", e);
+          primaryWriteFailed = true;
+          await fallback.set(key, value);
+          return true;
+        }
+      },
+
+      async remove(key) {
+        try {
+          let cookieStr = `${key}=; path=${CONFIG.cookiePath}; expires=Thu, 01 Jan 1970 00:00:00 GMT; SameSite=${getSameSiteForCookieString()}`;
+          if (CONFIG.cookieDomain) {
+            cookieStr += `; domain=${CONFIG.cookieDomain}`;
+          }
+
+          if (shouldUseSecure) {
+            cookieStr += "; Secure";
+          }
+
+          // biome-ignore lint/suspicious/noDocumentCookie: Needed for legacy cookie fallback when CookieStore API isn't available.
+          document.cookie = cookieStr;
+          await fallback.remove(key);
+          return true;
+        } catch (e) {
+          log("Legacy cookie remove error:", e);
+          await fallback.remove(key);
+          return true;
+        }
+      },
+    };
+
+    const cookieStoreAdapter = {
+      async get(key) {
+        try {
+          if (primaryWriteFailed) {
+            return fallback.get(key);
+          }
+
+          if (forceLegacy) {
+            return legacyCookieAdapter.get(key);
+          }
+
+          const cookie = await cookieStoreApi.get(key);
+          if (cookie?.value) {
+            return safeParse(decodeURIComponent(cookie.value));
+          }
+          return fallback.get(key);
+        } catch (e) {
+          log("CookieStore get error:", e);
+          forceLegacy = true;
+          return legacyCookieAdapter.get(key);
+        }
+      },
+
+      async set(key, value) {
+        try {
+          if (forceLegacy) {
+            return legacyCookieAdapter.set(key, value);
+          }
+
+          const encodedValue = encodeURIComponent(JSON.stringify(value));
+
+          if (encodedValue.length > MAX_COOKIE_SIZE) {
+            log(
+              `Cookie value size (${encodedValue.length}) exceeds limit (${MAX_COOKIE_SIZE}), falling back to memory storage`
+            );
+            primaryWriteFailed = true;
+            await fallback.set(key, value);
+            return true;
+          }
+
+          const cookieOptions = {
+            name: key,
+            value: encodedValue,
+            path: CONFIG.cookiePath,
+            expires: getExpirationDate(),
+            sameSite: CONFIG.cookieSameSite,
+            secure: shouldUseSecure,
+          };
+
+          if (CONFIG.cookieDomain) {
+            cookieOptions.domain = CONFIG.cookieDomain;
+          }
+
+          await cookieStoreApi.set(cookieOptions);
+          await fallback.set(key, value);
+          return true;
+        } catch (e) {
+          log("CookieStore set error:", e);
+          forceLegacy = true;
+          return legacyCookieAdapter.set(key, value);
+        }
+      },
+
+      async remove(key) {
+        try {
+          if (forceLegacy) {
+            return legacyCookieAdapter.remove(key);
+          }
+
+          const deleteOptions = { name: key, path: CONFIG.cookiePath };
+
+          if (CONFIG.cookieDomain) {
+            deleteOptions.domain = CONFIG.cookieDomain;
+          }
+
+          await cookieStoreApi.delete(deleteOptions);
+          await fallback.remove(key);
+          return true;
+        } catch (e) {
+          log("CookieStore remove error:", e);
+          forceLegacy = true;
+          return legacyCookieAdapter.remove(key);
+        }
+      },
+    };
+
+    log(
+      `Using ${useCookieStore ? "CookieStore API" : "legacy document.cookie"}`
+    );
+    return useCookieStore ? cookieStoreAdapter : legacyCookieAdapter;
+  };
+
+  const captureAttributionData = () => {
+    const currentUrl = window.location.href;
+    const urlParams = parseUrlParams(currentUrl);
+    const trackedParams = TRACKED_PARAMS;
+
+    const attributionData = {};
+
+    for (const param of trackedParams) {
+      if (urlParams[param] !== undefined) {
+        attributionData[param] = String(urlParams[param]).substring(
+          0,
+          MAX_PARAM_LENGTH
+        );
+      }
+    }
+
+    attributionData.landing_page = currentUrl
+      .split("?")[0]
+      .substring(0, MAX_URL_LENGTH);
+    attributionData.referrer_url = (document.referrer || "").substring(
+      0,
+      MAX_URL_LENGTH
+    );
+    attributionData.first_touch_timestamp = new Date().toISOString();
+
+    return attributionData;
+  };
+
+  const mergeAttributionData = (existing, current) => {
+    if (!existing) {
+      return current;
+    }
+
+    const merged = { ...existing };
+    const trackedParams = TRACKED_PARAMS;
+
+    for (const param of trackedParams) {
+      if (current[param] !== undefined && existing[param] === undefined) {
+        merged[param] = current[param];
+      }
+    }
+
+    if (!merged.landing_page) {
+      merged.landing_page = current.landing_page;
+    }
+
+    if (!merged.referrer_url && current.referrer_url) {
+      merged.referrer_url = current.referrer_url;
+    }
+
+    if (!merged.first_touch_timestamp) {
+      merged.first_touch_timestamp = current.first_touch_timestamp;
+    }
+
+    return merged;
+  };
+
+  const shouldIncludeForm = (form) => {
+    if (!CONFIG.excludeForms) {
+      return true;
+    }
+
+    try {
+      return !form.matches(CONFIG.excludeForms);
+    } catch {
+      return true;
+    }
+  };
+
+  const getAttributionEntries = (data) => {
+    const entries = [];
+
+    if (!data || typeof data !== "object") {
+      return entries;
+    }
+
+    for (const param of PARAMS_TO_INJECT) {
+      if (param === "current_page") {
+        continue;
+      }
+      const value = data[param];
+      if (value !== undefined && value !== null && value !== "") {
+        entries.push({
+          name: `${CONFIG.fieldPrefix}${param}`,
+          value: String(value),
+        });
+      }
+    }
+
+    entries.push({
+      name: `${CONFIG.fieldPrefix}current_page`,
+      value: window.location.href.split("?")[0],
+    });
+
+    return entries;
+  };
+
+  const getTargetForms = () =>
+    Array.from(document.querySelectorAll("form")).filter(shouldIncludeForm);
+
+  const removeExistingFields = (form) => {
+    const existingFields = form.querySelectorAll(
+      'input[data-form-attribution="true"]'
+    );
+
+    for (const field of existingFields) {
+      field.remove();
+    }
+  };
+
+  const clearManagedFieldValues = (form) => {
+    const managedFields = form.querySelectorAll(
+      'input[type="hidden"][data-form-attribution-managed="true"]'
+    );
+    for (const field of managedFields) {
+      field.value = "";
+    }
+  };
+
+  const getFormElements = (form) => {
+    try {
+      return Object.getOwnPropertyDescriptor(
+        HTMLFormElement.prototype,
+        "elements"
+      ).get.call(form);
+    } catch {
+      return form.elements;
+    }
+  };
+
+  const getHiddenInputsByName = (form, name) => {
+    const matches = [];
+    const elements = getFormElements(form);
+    if (!elements) {
+      return matches;
+    }
+
+    for (const el of elements) {
+      if (!el || el.tagName !== "INPUT") {
+        continue;
+      }
+
+      const input = el;
+      if (input.type === "hidden" && input.name === name) {
+        matches.push(input);
+      }
+    }
+
+    return matches;
+  };
+
+  const syncFormAttributionFields = (form, entries) => {
+    removeExistingFields(form);
+
+    if (!entries || entries.length === 0) {
+      clearManagedFieldValues(form);
+      return;
+    }
+
+    const fragment = document.createDocumentFragment();
+
+    for (const entry of entries) {
+      const existingInputs = getHiddenInputsByName(form, entry.name);
+      const safeValue = sanitizeValue(entry.value);
+
+      if (existingInputs.length > 0) {
+        for (const input of existingInputs) {
+          input.value = safeValue;
+          input.dataset.formAttributionManaged = "true";
+        }
+
+        continue;
+      }
+
+      const input = document.createElement("input");
+      input.type = "hidden";
+      input.name = entry.name;
+      input.value = safeValue;
+
+      input.dataset.formAttribution = "true";
+      input.dataset.formAttributionManaged = "true";
+      fragment.appendChild(input);
+    }
+
+    if (fragment.hasChildNodes()) {
+      form.appendChild(fragment);
+    }
+  };
+
+  const injectIntoForms = (data) => {
+    const forms = getTargetForms();
+
+    if (forms.length === 0) {
+      log("No forms found on page");
+      return;
+    }
+
+    const entries = getAttributionEntries(data);
+
+    for (const form of forms) {
+      syncFormAttributionFields(form, entries);
+
+      log(
+        "Synced attribution fields in form:",
+        form.id || form.name || "[unnamed]"
+      );
+    }
+
+    log(
+      entries.length === 0
+        ? `Cleared attribution fields in ${forms.length} form(s)`
+        : `Injected attribution data into ${forms.length} form(s)`
+    );
+  };
+
+  const setupFormObserver = (getData) => {
+    const pendingForms = new Set();
+    let scheduled = false;
+
+    const flush = () => {
+      scheduled = false;
+      if (pendingForms.size === 0) {
+        return;
+      }
+
+      const entries = getAttributionEntries(getData());
+      for (const form of pendingForms) {
+        if (document.contains(form)) {
+          syncFormAttributionFields(form, entries);
+        }
+      }
+      pendingForms.clear();
+    };
+
+    const scheduleFlush = () => {
+      if (scheduled) {
+        return;
+      }
+      scheduled = true;
+
+      if (typeof queueMicrotask === "function") {
+        queueMicrotask(flush);
+      } else {
+        Promise.resolve().then(flush);
+      }
+    };
+
+    const addFormIfIncluded = (form) => {
+      if (shouldIncludeForm(form)) {
+        pendingForms.add(form);
+      }
+    };
+
+    const collectFormsFromNode = (node) => {
+      if (node.tagName === "FORM") {
+        addFormIfIncluded(node);
+      }
+
+      if (node.querySelectorAll) {
+        const nestedForms = node.querySelectorAll("form");
+        for (const form of nestedForms) {
+          addFormIfIncluded(form);
+        }
+      }
+    };
+
+    const processAddedNodes = (addedNodes) => {
+      for (const node of addedNodes) {
+        if (node.nodeType !== Node.ELEMENT_NODE) {
+          continue;
+        }
+        collectFormsFromNode(node);
+      }
+    };
+
+    const handleMutations = (mutations) => {
+      for (const mutation of mutations) {
+        processAddedNodes(mutation.addedNodes);
+      }
+
+      if (pendingForms.size > 0) {
+        scheduleFlush();
+      }
+    };
+
+    const observer = new MutationObserver(handleMutations);
+
+    if (!document.body) {
+      log("Form observer could not initialize: document.body not found");
+      return observer;
+    }
+
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+    });
+
+    log("Form observer initialized");
+    return observer;
+  };
+
+  const init = async () => {
+    log("Initializing with config:", CONFIG);
+
+    const storage = createStorageAdapter(CONFIG.storage);
+    let latestData = null;
+
+    const existingData = await storage.get(CONFIG.storageKey);
+    log("Existing attribution data:", existingData);
+
+    const currentData = captureAttributionData();
+    log("Current attribution data:", currentData);
+
+    const mergedData = mergeAttributionData(existingData, currentData);
+    latestData = mergedData;
+    log("Merged attribution data:", mergedData);
+
+    if (Object.keys(mergedData).length > 0) {
+      await storage.set(CONFIG.storageKey, mergedData);
+      log("Attribution data saved");
+    }
+
+    injectIntoForms(latestData);
+
+    setupFormObserver(() => latestData);
+
+    log("Initialization complete");
+  };
+
+  const run = async () => {
+    if (isPrivacySignalEnabled()) {
+      log("Tracking disabled due to privacy signal (GPC/DNT)");
+      return;
+    }
+
+    if (document.readyState === "loading") {
+      document.addEventListener(
+        "DOMContentLoaded",
+        () => {
+          init().catch((e) => log("Initialization error:", e));
+        },
+        { once: true }
+      );
+    } else {
+      await init().catch((e) => log("Initialization error:", e));
+    }
+  };
+
+  run();
+})();

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "form-attribution",
+  "version": "1.0.0",
+  "description": "Automatically capture and persist marketing attribution data in your web forms.",
+  "homepage": "https://github.com/flash-brew-digital/form-attribution#readme",
+  "sideEffects": false,
+  "type": "module",
+  "main": "dist/script.js",
+  "files": [
+    "dist/script.js"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flash-brew-digital/form-attribution.git"
+  },
+  "keywords": [
+    "forms",
+    "lead-generation",
+    "attribution",
+    "marketing",
+    "utm",
+    "analytics",
+    "crm"
+  ],
+  "author": {
+    "name": "Ben Sabic",
+    "url": "https://bensabic.ca"
+  },
+  "license": "Apache-2.0",
+  "bugs": {
+    "url": "https://github.com/flash-brew-digital/form-attribution/issues"
+  },
+  "scripts": {
+    "release": "npm publish --access public",
+    "check": "npx ultracite check",
+    "fix": "npx ultracite fix",
+    "test": "npx playwright test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.10",
+    "@playwright/test": "^1.57.0",
+    "@types/node": "^25.0.3",
+    "ultracite": "6.5.0"
+  },
+  "packageManager": "pnpm@10.24.0+sha512.01ff8ae71b4419903b65c60fb2dc9d34cf8bb6e06d03bde112ef38f7a34d6904c424ba66bea5cdcf12890230bf39f9580473140ed9c946fef328b6e5238a345a"
+}