firstusers 1.0.1

package/LICENSE

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

package/README.md

@@ -0,0 +1,185 @@
+# First Users SDK
+
+**Automatic tester tracking with heartbeat monitoring, offline retry, device fingerprinting, and guest user auto-tracking.**
+
+## Features
+
+✅ **GU Auto-Tracking** — Automatically generates Guest ID and starts tracking immediately  
+🔗 **FU-GU Binding** — Links past GU activity when user enters FU ID  
+💓 **Global Heartbeat** — Persists across route changes, sends every 30 seconds  
+📶 **Offline Queue** — Failed requests queued and retried on startup  
+⏱️ **Session Duration** — Real-time tracking sent with every request  
+📱 **Device Info** — Brand (Samsung, Xiaomi…) and API level auto-detected  
+📦 **Dynamic Package Name** — Passed via props for reuse  
+
+## Installation
+
+```bash
+npm install firstusers
+```
+
+## Quick Start
+
+### 1. Import the component
+
+```javascript
+import FirstUsersIntegration from 'firstusers';
+```
+
+### 2. Add to your app
+
+```jsx
+function App() {
+  return (
+    <div>
+      <h1>My App</h1>
+      
+      {/* Add First Users integration */}
+      <FirstUsersIntegration appPackageName="com.yourcompany.app" />
+      
+      {/* Your app content */}
+    </div>
+  );
+}
+```
+
+### 3. Track feature usage (optional)
+
+After the component is mounted, you can track specific features:
+
+```javascript
+// Track button clicks
+window.trackFUFeature('button_click');
+
+// Track video plays
+window.trackFUFeature('video_play');
+
+// Track any custom event
+window.trackFUFeature('premium_upgrade');
+```
+
+## How It Works
+
+### Automatic Guest User (GU) Tracking
+
+When users first visit your app:
+1. **Auto-generates GU ID** — System creates a unique `gu-XXXXXXX` ID
+2. **Starts tracking immediately** — All activity is recorded with the GU ID
+3. **Shows yellow banner** — User sees "Anonymous Tracking Active" status
+
+### FU ID Binding
+
+When users enter their First Users ID:
+1. **User enters FU ID** — Format: `fu-XXXXX` (8 characters)
+2. **Binds past activity** — All previous GU data is linked to their FU account
+3. **Shows green banner** — User sees "First Users Tester Active" status
+4. **Data preserved** — Full 14-day tracking history is maintained
+
+## API Reference
+
+### Component Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `appPackageName` | string | Yes | - | Your app's package name (e.g., "com.yourcompany.app") |
+| `apiEndpoint` | string | No | First Users API | Custom API endpoint if you're self-hosting |
+
+### Global Functions
+
+#### `window.trackFUFeature(featureName: string)`
+
+Track custom feature usage. Available after component mounts.
+
+```javascript
+window.trackFUFeature('search_product');
+window.trackFUFeature('checkout_completed');
+```
+
+### Exported Utilities
+
+#### `FUHeartbeat`
+
+Global heartbeat manager singleton.
+
+```javascript
+import { FUHeartbeat } from 'firstusers';
+
+// Start heartbeat manually (usually handled by component)
+FUHeartbeat.start('fu-12345', trackFunction);
+
+// Get current session duration in seconds
+const duration = FUHeartbeat.getDuration();
+
+// Stop heartbeat
+FUHeartbeat.stop();
+```
+
+#### `generateGuestId()`
+
+Generate a unique Guest User ID.
+
+```javascript
+import { generateGuestId } from 'firstusers';
+
+const guestId = generateGuestId(); // Returns: "gu-abc123xyz"
+```
+
+#### `getOrCreateUserId()`
+
+Get existing user ID from localStorage or create new GU ID.
+
+```javascript
+import { getOrCreateUserId } from 'firstusers';
+
+const userId = getOrCreateUserId(); // Returns: "fu-12345" or "gu-abc123"
+```
+
+#### `getDeviceInfo()`
+
+Extract device information from user agent.
+
+```javascript
+import { getDeviceInfo } from 'firstusers';
+
+const device = getDeviceInfo();
+// Returns: {
+//   device_brand: "Samsung",
+//   device_api_level: "Android 13",
+//   user_agent: "Mozilla/5.0..."
+// }
+```
+
+## UI States
+
+### 1. Initial State (Rare)
+Gray banner asking user to enter FU ID (only shown if GU auto-generation fails).
+
+### 2. Anonymous Tracking (GU Active)
+Yellow banner showing:
+- Current Guest ID
+- Session duration
+- Input field to enter FU ID
+- "Link FU ID" button
+
+### 3. Active Tracking (FU Active)
+Green banner showing:
+- FU ID is active
+- Session duration
+
+## Data Privacy
+
+- All data is stored in First Users' secure database
+- User IDs are anonymized (GU or FU format)
+- Device info helps identify unique testers
+- Session data used for 14-day activity tracking
+
+## Support
+
+For issues or questions:
+- Email: support@firstusers.com
+- Documentation: https://docs.firstusers.com
+- GitHub: https://github.com/firstusers/firstusers-sdk
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,304 @@
+import React, { useState, useEffect, useRef } from 'react';
+
+// ---- Global Heartbeat Manager (persists across route changes) ----
+const FUHeartbeat = {
+  _interval: null,
+  _startTime: null,
+  _fuId: null,
+  _trackFn: null,
+  start(fuId, trackFn) {
+    if (this._interval) return; // already running
+    this._fuId = fuId;
+    this._trackFn = trackFn;
+    this._startTime = Date.now();
+    this._interval = setInterval(() => {
+      const dur = Math.floor((Date.now() - this._startTime) / 1000);
+      this._trackFn(this._fuId, 'heartbeat', { session_duration: dur });
+    }, 30000);
+    if (typeof window !== 'undefined') {
+      window.addEventListener('beforeunload', this._onUnload);
+    }
+  },
+  _onUnload() {
+    FUHeartbeat.stop(true);
+  },
+  stop(sendEnd = false) {
+    if (!this._interval) return;
+    clearInterval(this._interval);
+    if (sendEnd && this._trackFn && this._fuId) {
+      const dur = Math.floor((Date.now() - this._startTime) / 1000);
+      this._trackFn(this._fuId, 'session_end', { session_duration: dur });
+    }
+    if (typeof window !== 'undefined') {
+      window.removeEventListener('beforeunload', this._onUnload);
+    }
+    this._interval = null;
+  },
+  getDuration() {
+    if (!this._startTime) return 0;
+    return Math.floor((Date.now() - this._startTime) / 1000);
+  }
+};
+
+// ---- GU (Guest User) Auto-Generation ----
+function generateGuestId() {
+  const randomStr = Math.random().toString(36).substr(2, 9);
+  return 'gu-' + randomStr;
+}
+
+function getOrCreateUserId() {
+  if (typeof localStorage === 'undefined') return null;
+  let userId = localStorage.getItem('fu_tester_id');
+  if (!userId) {
+    // Auto-generate GU ID for anonymous tracking
+    userId = generateGuestId();
+    localStorage.setItem('fu_tester_id', userId);
+    console.log('Auto-generated Guest User ID:', userId);
+  }
+  return userId;
+}
+
+// ---- Device Info Helper ----
+function getDeviceInfo() {
+  const ua = (typeof navigator !== 'undefined' ? navigator.userAgent : '') || '';
+  let device_brand = 'unknown';
+  let device_api_level = 'unknown';
+  // Detect brand from common UA patterns
+  const brands = ['Samsung','Xiaomi','Huawei','OnePlus','Oppo','Vivo','Realme',
+    'Motorola','LG','Sony','Google','Pixel','Nokia','Asus','ZTE','Lenovo'];
+  for (const b of brands) {
+    if (ua.toLowerCase().includes(b.toLowerCase())) { device_brand = b; break; }
+  }
+  // Detect Android API level
+  const androidMatch = ua.match(/Android\s([\d.]+)/);
+  if (androidMatch) device_api_level = 'Android ' + androidMatch[1];
+  const iosMatch = ua.match(/OS\s([\d_]+)\slike/);
+  if (iosMatch) device_api_level = 'iOS ' + iosMatch[1].replace(/_/g, '.');
+  return { device_brand, device_api_level, user_agent: ua };
+}
+
+// ---- Offline Queue ----
+function queueFailedRequest(data) {
+  if (typeof localStorage === 'undefined') return;
+  try {
+    const q = JSON.parse(localStorage.getItem('fu_failed_requests') || '[]');
+    q.push({ ...data, queued_at: new Date().toISOString() });
+    localStorage.setItem('fu_failed_requests', JSON.stringify(q));
+  } catch (e) { console.error('Queue error:', e); }
+}
+
+async function processFailedRequests(trackFn) {
+  if (typeof localStorage === 'undefined') return;
+  try {
+    const q = JSON.parse(localStorage.getItem('fu_failed_requests') || '[]');
+    if (!q.length) return;
+    const remaining = [];
+    for (const req of q) {
+      const ok = await trackFn(req.fu_id, req.action, req, false);
+      if (!ok) remaining.push(req);
+    }
+    localStorage.setItem('fu_failed_requests', JSON.stringify(remaining));
+  } catch (e) { console.error('Retry error:', e); }
+}
+
+/**
+ * First Users Integration Component
+ * @param {Object} props
+ * @param {string} props.appPackageName - Your app's package name (e.g., "com.yourcompany.app")
+ * @param {string} [props.apiEndpoint] - Custom API endpoint (default: First Users API)
+ */
+function FirstUsersIntegration({ appPackageName = 'your.package.name', apiEndpoint = 'https://cotester-api.01hunterwl.workers.dev' }) {
+  const [fuId, setFuId] = useState('');
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [isTracked, setIsTracked] = useState(false);
+  const [sessionDuration, setSessionDuration] = useState(0);
+  const timerRef = useRef(null);
+  const sessionId = React.useMemo(() =>
+    'session_' + Math.random().toString(36).substr(2, 9), []
+  );
+
+  const trackActivity = async (fuIdToTrack, action = 'app_usage', extraData = {}, shouldQueue = true) => {
+    try {
+      const device = getDeviceInfo();
+      const requestData = {
+        fu_id: fuIdToTrack,
+        app_package: appPackageName,
+        timestamp: new Date().toISOString(),
+        action,
+        page_url: typeof window !== 'undefined' ? (window.location?.pathname + window.location?.search) : '',
+        user_agent: device.user_agent,
+        device_brand: device.device_brand,
+        device_api_level: device.device_api_level,
+        session_id: sessionId,
+        session_duration: FUHeartbeat.getDuration(),
+        ...extraData
+      };
+      const resp = await fetch(`${apiEndpoint}/api/fu/track`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(requestData),
+      });
+      const result = await resp.json();
+      if (result.success) { console.log('FU tracked:', result); return true; }
+      if (shouldQueue) queueFailedRequest(requestData);
+      return false;
+    } catch (e) {
+      console.error('FU error:', e);
+      if (shouldQueue) queueFailedRequest({ fu_id: fuIdToTrack, app_package: appPackageName, action, ...extraData });
+      return false;
+    }
+  };
+
+  // On mount: restore tracked state, process offline queue, start heartbeat
+  useEffect(() => {
+    const userId = getOrCreateUserId(); // Auto-generate GU if needed
+    if (!userId) return; // Skip if localStorage unavailable
+    
+    setFuId(userId);
+    
+    // Determine if this is a real FU or auto-generated GU
+    const isRealFU = userId.startsWith('fu-');
+    setIsTracked(isRealFU);
+    
+    // Start tracking immediately with either FU or GU
+    trackActivity(userId, 'page_visit');
+    FUHeartbeat.start(userId, trackActivity);
+    
+    // Process any queued offline requests on startup
+    processFailedRequests(trackActivity);
+    // Update duration display every second
+    timerRef.current = setInterval(() => setSessionDuration(FUHeartbeat.getDuration()), 1000);
+    return () => { 
+      if (timerRef.current) clearInterval(timerRef.current); 
+    };
+  }, []);
+
+  // Bind GU to FU when user submits their FU ID
+  const bindGuestToFU = async (guId, fuId) => {
+    try {
+      const resp = await fetch(`${apiEndpoint}/api/fu/bind`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ gu_id: guId, fu_id: fuId }),
+      });
+      const result = await resp.json();
+      return result.success;
+    } catch (e) {
+      console.error('Bind error:', e);
+      return false;
+    }
+  };
+
+  const handleSubmitFuId = async () => {
+    if (!fuId.startsWith('fu-') || fuId.length !== 8) {
+      alert('Please enter a valid FU ID (format: fu-XXXXX)');
+      return;
+    }
+    setIsSubmitting(true);
+    
+    // Get current ID (might be GU)
+    const currentId = typeof localStorage !== 'undefined' ? localStorage.getItem('fu_tester_id') : null;
+    const isGU = currentId && currentId.startsWith('gu-');
+    
+    // If upgrading from GU to FU, bind them first
+    if (isGU) {
+      const bindSuccess = await bindGuestToFU(currentId, fuId);
+      if (!bindSuccess) {
+        alert('Failed to link your previous activity. Please try again.');
+        setIsSubmitting(false);
+        return;
+      }
+      console.log(`Successfully bound ${currentId} to ${fuId}`);
+    }
+    
+    // Register the FU ID
+    const ok = await trackActivity(fuId, 'tester_registration');
+    if (ok) {
+      alert('Your testing activity is now being tracked with your FU ID.');
+      if (typeof localStorage !== 'undefined') {
+        localStorage.setItem('fu_tester_id', fuId);
+      }
+      setIsTracked(true);
+      // Restart heartbeat with new FU ID
+      FUHeartbeat.stop();
+      FUHeartbeat.start(fuId, trackActivity);
+    } else {
+      alert('Failed to register. Will retry automatically.');
+    }
+    setIsSubmitting(false);
+  };
+
+  // Expose global feature tracker
+  useEffect(() => {
+    if (typeof window !== 'undefined') {
+      window.trackFUFeature = (name) => {
+        const id = localStorage.getItem('fu_tester_id');
+        if (id) trackActivity(id, `feature_${name}`);
+      };
+    }
+  }, []);
+
+  const currentId = typeof localStorage !== 'undefined' ? localStorage.getItem('fu_tester_id') : '';
+  const isGU = currentId && currentId.startsWith('gu-');
+
+  if (isTracked) {
+    return (
+      <div style={{ padding:'15px', backgroundColor:'#dcfce7', borderRadius:'8px',
+        margin:'20px 0', border:'1px solid #bbf7d0' }}>
+        <h4 style={{ color:'#16a34a', margin:'0 0 5px' }}>First Users Tester Active</h4>
+        <p style={{ margin:0, fontSize:'14px', color:'#15803d' }}>
+          Tracking active with FU ID. Session: {Math.floor(sessionDuration/60)}m {sessionDuration%60}s
+        </p>
+      </div>
+    );
+  }
+
+  if (isGU) {
+    return (
+      <div style={{ padding:'20px', backgroundColor:'#fff3cd', borderRadius:'8px',
+        margin:'20px 0', border:'1px solid #ffc107' }}>
+        <h3 style={{ color:'#856404', marginTop:0 }}>Anonymous Tracking Active</h3>
+        <p style={{ fontSize:'14px', color:'#856404', margin:'10px 0' }}>
+          Currently tracking with Guest ID: <code>{currentId}</code>
+        </p>
+        <p style={{ fontSize:'14px', color:'#856404', margin:'10px 0' }}>
+          Session: {Math.floor(sessionDuration/60)}m {sessionDuration%60}s
+        </p>
+        <p style={{ fontSize:'14px', color:'#856404', fontWeight:'bold', margin:'10px 0' }}>
+          Enter your FU ID to link your activity:
+        </p>
+        <input type="text" placeholder="fu-12345" value={fuId}
+          onChange={(e) => setFuId(e.target.value)}
+          style={{ padding:'10px', marginRight:'10px', border:'1px solid #ddd',
+            borderRadius:'4px', minWidth:'120px' }} />
+        <button onClick={handleSubmitFuId} disabled={isSubmitting}
+          style={{ padding:'10px 20px', backgroundColor: isSubmitting?'#9ca3af':'#3b82f6',
+            color:'white', border:'none', borderRadius:'4px',
+            cursor: isSubmitting?'not-allowed':'pointer' }}>
+          {isSubmitting ? 'Linking...' : 'Link FU ID'}
+        </button>
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ padding:'20px', backgroundColor:'#f5f5f5', borderRadius:'8px',
+      margin:'20px 0', border:'1px solid #d1d5db' }}>
+      <h3>First Users Tester</h3>
+      <p>Enter your FU ID to start tracking:</p>
+      <input type="text" placeholder="fu-12345" value={fuId}
+        onChange={(e) => setFuId(e.target.value)}
+        style={{ padding:'10px', marginRight:'10px', border:'1px solid #ddd',
+          borderRadius:'4px', minWidth:'120px' }} />
+      <button onClick={handleSubmitFuId} disabled={isSubmitting}
+        style={{ padding:'10px 20px', backgroundColor: isSubmitting?'#9ca3af':'#3b82f6',
+          color:'white', border:'none', borderRadius:'4px',
+          cursor: isSubmitting?'not-allowed':'pointer' }}>
+        {isSubmitting ? 'Registering...' : 'Start Tracking'}
+      </button>
+    </div>
+  );
+}
+
+export default FirstUsersIntegration;
+export { FUHeartbeat, generateGuestId, getOrCreateUserId, getDeviceInfo };

package/index.d.ts

@@ -0,0 +1,59 @@
+import React from 'react';
+
+export interface FirstUsersIntegrationProps {
+  /**
+   * Your application's package name (e.g., "com.yourcompany.app")
+   */
+  appPackageName: string;
+  
+  /**
+   * Custom API endpoint (optional, defaults to First Users API)
+   */
+  apiEndpoint?: string;
+}
+
+/**
+ * First Users Integration Component
+ * Provides automatic tester tracking with heartbeat monitoring, offline retry,
+ * device fingerprinting, and guest user auto-tracking.
+ */
+declare const FirstUsersIntegration: React.FC<FirstUsersIntegrationProps>;
+
+export default FirstUsersIntegration;
+
+/**
+ * Global heartbeat manager singleton
+ */
+export const FUHeartbeat: {
+  start(fuId: string, trackFn: (id: string, action: string, data?: any) => Promise<boolean>): void;
+  stop(sendEnd?: boolean): void;
+  getDuration(): number;
+};
+
+/**
+ * Generate a unique Guest User ID
+ */
+export function generateGuestId(): string;
+
+/**
+ * Get existing user ID or create new Guest User ID
+ */
+export function getOrCreateUserId(): string | null;
+
+/**
+ * Extract device information from user agent
+ */
+export function getDeviceInfo(): {
+  device_brand: string;
+  device_api_level: string;
+  user_agent: string;
+};
+
+/**
+ * Global feature tracking function (available after component mount)
+ */
+declare global {
+  interface Window {
+    trackFUFeature?: (featureName: string) => void;
+  }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "firstusers",
+  "version": "1.0.1",
+  "description": "First Users - Automatic tester tracking with heartbeat monitoring, offline retry, device fingerprinting, and guest user auto-tracking",
+  "main": "dist/index.js",
+  "types": "index.d.ts",
+  "files": [
+    "dist",
+    "index.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "prepublishOnly": "echo 'Publishing firstusers package...' && ls -la dist/"
+  },
+  "keywords": [
+    "firstusers",
+    "tracking",
+    "analytics",
+    "tester",
+    "heartbeat",
+    "offline",
+    "react",
+    "guest-user"
+  ],
+  "author": "First Users Team",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/01hunterwl-commits/fucallback.git"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "devDependencies": {
+    "npm-packlist": "^10.0.3"
+  }
+}