lucia-sdk 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 
 
+## [0.9.0](https://github.com/ondecentral/Lucia-Browser-SDK/compare/v0.8.0...v0.9.0) (2025-11-20)
+
+
+### Features
+
+* add auto-init with api key provided in script tag ([fa358a7](https://github.com/ondecentral/Lucia-Browser-SDK/commit/fa358a77151203d90252bbe00f44a407b97b129d))
+* add automated click tracking ([af95407](https://github.com/ondecentral/Lucia-Browser-SDK/commit/af95407d021a4dc464e41fd255a20782d9f235b3))
+* use closest to find trackable elements ([aae6ff6](https://github.com/ondecentral/Lucia-Browser-SDK/commit/aae6ff61fd42f447867130921370d22cc10e7761))
+
+
+### Documentation
+
+* update readme ([160130c](https://github.com/ondecentral/Lucia-Browser-SDK/commit/160130c9f82fc39b520b89360523b25bfba65ada))
+
+
+### Code Refactoring
+
+* optimize click tracking with closest() and add cleanup ([78cf55f](https://github.com/ondecentral/Lucia-Browser-SDK/commit/78cf55f09ff8fbb2ccb69ea50887ec11366e98d1))
+
 ## [0.8.0](https://github.com/ondecentral/Lucia-Browser-SDK/compare/v0.7.2...v0.8.0) (2025-11-13)
 
 

package/README.md

@@ -24,20 +24,150 @@ yarn add lucia-sdk
 
 You can add the following script to use global `LuciaSDK` object.
 
+**Option 1: Auto-initialization (Recommended)**
+
+The SDK will automatically initialize when you provide the `data-api-key` attribute:
+
+```html
+<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js" data-api-key="your-api-key-here"></script>
 ```
+
+Optional configuration attributes:
+
+- `data-api-key` (required) - Your Lucia API key
+- `data-debug-url` (optional) - Custom debug endpoint URL
+- `data-auto-track-clicks` (optional) - Enable automatic click tracking (`"true"` or `"false"`)
+- `data-track-selectors` (optional) - Custom CSS selectors for click tracking (comma-separated)
+
+**Option 2: Manual initialization**
+
+Load the script without attributes and initialize programmatically:
+
+```html
 <script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
+<script>
+  LuciaSDK.init({
+    apiKey: 'your-api-key-here',
+    debugURL: 'https://custom-debug-url.com', // optional
+  });
+</script>
 ```
 
 ## Usage
 
 ### Initialize the SDK
 
+#### For CDN (Manual Initialization)
+
 ```javascript
 LuciaSDK.init({
-  apiKey,
+  apiKey: 'your-api-key-here',
+  debugURL: 'https://custom-debug-url.com', // optional
+});
+```
+
+#### For npm/yarn Installation
+
+```javascript
+import LuciaSDK from 'lucia-sdk';
+
+await LuciaSDK.init({
+  apiKey: 'your-api-key-here',
+  autoTrackClicks: true, // optional: enable automatic click tracking
+});
+```
+
+#### For Next.js
+
+The SDK seamlessly works with Next.js using both CDN auto-init and npm import:
+
+```jsx
+import Script from 'next/script';
+import LuciaSDK from 'lucia-sdk';
+
+export default function Page() {
+  const handleClick = () => {
+    // NPM import works with CDN-initialized instance
+    LuciaSDK.buttonClick('cta-button');
+  };
+
+  return (
+    <>
+      <Script
+        src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"
+        data-api-key="your-api-key-here"
+        strategy="afterInteractive"
+      />
+      <button onClick={handleClick}>Click me</button>
+    </>
+  );
+}
+```
+
+### Automated Click Tracking
+
+Lucia SDK provides zero-config automated click tracking. When enabled, it automatically tracks clicks on buttons, links, and other interactive elements.
+
+#### Enable via CDN
+
+```html
+<script
+  src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"
+  data-api-key="your-api-key-here"
+  data-auto-track-clicks="true"
+></script>
+```
+
+#### Enable Programmatically
+
+```javascript
+await LuciaSDK.init({
+  apiKey: 'your-api-key-here',
+  autoTrackClicks: true, // Enable with defaults
 });
+
+// Or with custom configuration
+await LuciaSDK.init({
+  apiKey: 'your-api-key-here',
+  autoTrackClicks: {
+    enabled: true,
+    selectors: ['button', '.cta', '[data-track]'], // Custom selectors
+    ignore: ['.no-track'], // Elements to ignore
+  },
+});
+```
+
+#### Element-Level Control
+
+Add tracking attributes to specific elements:
+
+```html
+<!-- Explicit tracking with custom identifier -->
+<button data-lucia-track="signup-cta">Sign Up</button>
+
+<!-- Add metadata to tracked clicks -->
+<button data-lucia-track="purchase-btn" data-lucia-meta-variant="primary" data-lucia-meta-location="hero">
+  Buy Now
+</button>
+
+<!-- Ignore specific elements -->
+<button data-lucia-ignore>Don't Track This</button>
 ```
 
+**Default Tracked Elements:**
+
+- `<button>` elements
+- `<a>` elements with `href` attribute
+- Elements with `role="button"`
+- Any element with `data-lucia-track` attribute
+
+**Privacy Features:**
+
+- Automatically ignores password inputs
+- Skips credit card fields
+- Filters sensitive data from text content
+- Respects `data-lucia-ignore` attribute
+
 ### Track events
 
 Page views, conversions, and user information can be tracked using the following methods:
@@ -63,7 +193,12 @@ LuciaSDK.trackConversion(
   },
 );
 
-LuciaSDK.buttonClick('cta-button');
+// Manual click tracking (optional with auto-tracking enabled)
+LuciaSDK.buttonClick('cta-button', {
+  elementType: 'button',
+  text: 'Sign Up Now',
+  meta: { variant: 'primary', location: 'hero' },
+});
 
 LuciaSDK.sendWalletInfo('0x1234567890', 59141);
 ```

package/dist/README.md

@@ -24,20 +24,150 @@ yarn add lucia-sdk
 
 You can add the following script to use global `LuciaSDK` object.
 
+**Option 1: Auto-initialization (Recommended)**
+
+The SDK will automatically initialize when you provide the `data-api-key` attribute:
+
+```html
+<script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js" data-api-key="your-api-key-here"></script>
 ```
+
+Optional configuration attributes:
+
+- `data-api-key` (required) - Your Lucia API key
+- `data-debug-url` (optional) - Custom debug endpoint URL
+- `data-auto-track-clicks` (optional) - Enable automatic click tracking (`"true"` or `"false"`)
+- `data-track-selectors` (optional) - Custom CSS selectors for click tracking (comma-separated)
+
+**Option 2: Manual initialization**
+
+Load the script without attributes and initialize programmatically:
+
+```html
 <script src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"></script>
+<script>
+  LuciaSDK.init({
+    apiKey: 'your-api-key-here',
+    debugURL: 'https://custom-debug-url.com', // optional
+  });
+</script>
 ```
 
 ## Usage
 
 ### Initialize the SDK
 
+#### For CDN (Manual Initialization)
+
 ```javascript
 LuciaSDK.init({
-  apiKey,
+  apiKey: 'your-api-key-here',
+  debugURL: 'https://custom-debug-url.com', // optional
+});
+```
+
+#### For npm/yarn Installation
+
+```javascript
+import LuciaSDK from 'lucia-sdk';
+
+await LuciaSDK.init({
+  apiKey: 'your-api-key-here',
+  autoTrackClicks: true, // optional: enable automatic click tracking
+});
+```
+
+#### For Next.js
+
+The SDK seamlessly works with Next.js using both CDN auto-init and npm import:
+
+```jsx
+import Script from 'next/script';
+import LuciaSDK from 'lucia-sdk';
+
+export default function Page() {
+  const handleClick = () => {
+    // NPM import works with CDN-initialized instance
+    LuciaSDK.buttonClick('cta-button');
+  };
+
+  return (
+    <>
+      <Script
+        src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"
+        data-api-key="your-api-key-here"
+        strategy="afterInteractive"
+      />
+      <button onClick={handleClick}>Click me</button>
+    </>
+  );
+}
+```
+
+### Automated Click Tracking
+
+Lucia SDK provides zero-config automated click tracking. When enabled, it automatically tracks clicks on buttons, links, and other interactive elements.
+
+#### Enable via CDN
+
+```html
+<script
+  src="https://cdn.luciaprotocol.com/lucia-sdk-latest.min.js"
+  data-api-key="your-api-key-here"
+  data-auto-track-clicks="true"
+></script>
+```
+
+#### Enable Programmatically
+
+```javascript
+await LuciaSDK.init({
+  apiKey: 'your-api-key-here',
+  autoTrackClicks: true, // Enable with defaults
 });
+
+// Or with custom configuration
+await LuciaSDK.init({
+  apiKey: 'your-api-key-here',
+  autoTrackClicks: {
+    enabled: true,
+    selectors: ['button', '.cta', '[data-track]'], // Custom selectors
+    ignore: ['.no-track'], // Elements to ignore
+  },
+});
+```
+
+#### Element-Level Control
+
+Add tracking attributes to specific elements:
+
+```html
+<!-- Explicit tracking with custom identifier -->
+<button data-lucia-track="signup-cta">Sign Up</button>
+
+<!-- Add metadata to tracked clicks -->
+<button data-lucia-track="purchase-btn" data-lucia-meta-variant="primary" data-lucia-meta-location="hero">
+  Buy Now
+</button>
+
+<!-- Ignore specific elements -->
+<button data-lucia-ignore>Don't Track This</button>
 ```
 
+**Default Tracked Elements:**
+
+- `<button>` elements
+- `<a>` elements with `href` attribute
+- Elements with `role="button"`
+- Any element with `data-lucia-track` attribute
+
+**Privacy Features:**
+
+- Automatically ignores password inputs
+- Skips credit card fields
+- Filters sensitive data from text content
+- Respects `data-lucia-ignore` attribute
+
 ### Track events
 
 Page views, conversions, and user information can be tracked using the following methods:
@@ -63,7 +193,12 @@ LuciaSDK.trackConversion(
   },
 );
 
-LuciaSDK.buttonClick('cta-button');
+// Manual click tracking (optional with auto-tracking enabled)
+LuciaSDK.buttonClick('cta-button', {
+  elementType: 'button',
+  text: 'Sign Up Now',
+  meta: { variant: 'primary', location: 'hero' },
+});
 
 LuciaSDK.sendWalletInfo('0x1234567890', 59141);
 ```

package/dist/__tests__/auto-init.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Auto-initialization tests for Lucia SDK
+ * Tests the data-api-key attribute detection and automatic initialization
+ */
+import '@testing-library/jest-dom';

package/dist/__tests__/integration/auto-init-integration.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Integration tests for auto-initialization with hybrid CDN + npm usage
+ *
+ * NOTE: These tests focus on the conceptual aspects of auto-init that can be tested
+ * in a Jest environment. Full CDN auto-init behavior (script tag detection,
+ * DOMContentLoaded, automatic initialization) must be tested manually using:
+ * demo/auto-init-demo.html in a real browser environment.
+ */
+import '@testing-library/jest-dom';

package/dist/__tests__/integration/auto-track-integration.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @jest-environment jsdom
+ */
+export {};

package/dist/__tests__/utils/click-tracker.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @jest-environment jsdom
+ */
+export {};

package/dist/__tests__/utils/privacy.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @jest-environment jsdom
+ */
+export {};

package/dist/core/index.d.ts

@@ -1,10 +1,20 @@
 import BaseClass from '../base';
+import { ClickEventMetadata } from '../types';
 declare class LuciaSDK extends BaseClass {
+    private clickTracker;
     authenticate(): void;
     /**
      * Initializes the SDK with the provided configuration
      */
     init(): Promise<void>;
+    /**
+     * Initialize automated click tracking if enabled
+     */
+    private initAutoTracking;
+    /**
+     * Handle automatically tracked click events
+     */
+    private handleAutoTrackedClick;
     /**
      * Sends user information to the server
      * @param userId The user's ID, e.g. email, wallet address, etc.
@@ -25,9 +35,10 @@ declare class LuciaSDK extends BaseClass {
     trackConversion(eventTag: string, amount: number, eventDetails: object): Promise<void>;
     /**
      * Sends button click information to the server
-     * @param button The button that was clicked
+     * @param button The button identifier that was clicked
+     * @param metadata Optional metadata about the click event (elementType, text, href, meta)
      */
-    buttonClick(button: string): Promise<void>;
+    buttonClick(button: string, metadata?: ClickEventMetadata): Promise<void>;
     /**
      * Sends wallet information to the server
      * @param walletAddress The wallet address of the user
@@ -45,5 +56,9 @@ declare class LuciaSDK extends BaseClass {
      * @returns false if MetaMask is not connected, otherwise returns the wallet address
      */
     checkMetaMaskConnection(): any;
+    /**
+     * Clean up SDK resources (mainly for testing)
+     */
+    destroy(): void;
 }
 export default LuciaSDK;

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { SDK } from './types';
 import { getBrowserData, getWalletData, getUtmParams, safeAccess, filterObject, getCanvasFingerprint, isTouchEnabled, getApplePayAvailable, getContrastPreference, getColorGamut } from './utils/data';
+export declare const __resetInstance: () => void;
 declare const LuciaSDK: SDK;
 export default LuciaSDK;
 export { getBrowserData, getWalletData, getUtmParams, safeAccess, filterObject, getCanvasFingerprint, isTouchEnabled, getApplePayAvailable, getContrastPreference, getColorGamut, };