@tracetail/vue/README.md

Vue SDK for TraceTail browser fingerprinting - over 99.5% accuracy

# @tracetail/vue

Official Vue 3 SDK for TraceTail - Enterprise Browser Fingerprinting with over 99.5% accuracy.

## Features

- 🎯 **Over 99.5% Accuracy** - Industry-leading browser fingerprinting
- ⚡ **<25ms Performance** - Lightning-fast fingerprint generation
- 🛡️ **Fraud Detection** - Built-in risk scoring and fraud prevention
- 🔄 **Real-time Updates** - Live visitor tracking and analytics
- 📦 **27KB Bundle** - Lightweight and optimized
- 🎨 **Vue 3 Composition API** - Modern, reactive API design

## Installation

```bash
npm install @tracetail/vue
```

## Quick Start

### 1. Install Plugin

```js
// main.js
import { createApp } from 'vue';
import { TraceTailPlugin } from '@tracetail/vue';
import App from './App.vue';

const app = createApp(App);

app.use(TraceTailPlugin, {
  apiKey: 'your-api-key-here',
  config: {
    enhanced: true
  }
});

app.mount('#app');
```

### 2. Use in Components

```vue
<template>
  <div v-if="loading">Loading...</div>
  <div v-else>
    <p>Visitor: {{ visitorId }}</p>
    <p>Risk: {{ riskScore < 0.3 ? 'Low' : 'High' }}</p>
  </div>
</template>

<script setup>
import { useFingerprint } from '@tracetail/vue';

const { visitorId, riskScore, loading } = useFingerprint();
</script>
```

## Composables

### 🔍 useFingerprint()

Get visitor fingerprint data:

```js
const {
  visitorId,      // Ref<string>
  confidence,     // Ref<number> 0-1
  riskScore,      // Ref<number> 0-1
  fraudulent,     // Ref<boolean>
  signals,        // Ref<SignalData>
  loading,        // Ref<boolean>
  error,          // Ref<Error | null>
  retry,          // () => Promise<void>
  refresh         // () => Promise<void>
} = useFingerprint();
```

### 📊 useTrackEvent()

Track user events:

```js
const trackEvent = useTrackEvent();

const handleLogin = async () => {
  const result = await trackEvent('login', {
    username: 'user@example.com'
  });
  
  if (result.fraudulent) {
    // Handle fraud
  }
};
```

### 🛡️ useFraudDetection()

Advanced fraud detection:

```js
const { checkFraud, fraudSignals, isChecking } = useFraudDetection();

const handleCheckout = async (orderData) => {
  const result = await checkFraud({
    amount: orderData.total,
    items: orderData.items
  });
  
  if (result.block) {
    // Block transaction
  } else if (result.challenge) {
    // Show additional verification
  }
};
```

## Examples

### Authentication Guard

```vue
<template>
  <form @submit.prevent="login">
    <div v-if="riskScore > 0.7" class="warning">
      High risk detected - verification required
    </div>
    
    <input v-model="username" placeholder="Username" />
    <input v-model="password" type="password" />
    
    <button :disabled="isSubmitting">
      {{ isSubmitting ? 'Logging in...' : 'Login' }}
    </button>
  </form>
</template>

<script setup>
import { ref } from 'vue';
import { useFingerprint, useTrackEvent } from '@tracetail/vue';
import { useRouter } from 'vue-router';

const router = useRouter();
const { riskScore } = useFingerprint();
const trackEvent = useTrackEvent();

const username = ref('');
const password = ref('');
const isSubmitting = ref(false);

const login = async () => {
  isSubmitting.value = true;
  
  try {
    const tracking = await trackEvent('login', { username: username.value });
    
    if (tracking.fraudulent || riskScore.value > 0.7) {
      router.push('/verify');
      return;
    }
    
    // Normal login
    await loginAPI({ username: username.value, password: password.value });
    router.push('/dashboard');
  } finally {
    isSubmitting.value = false;
  }
};
</script>
```

### Fraud Detection Directive

```js
// main.js
app.directive('fraud-detection', {
  mounted(el, binding) {
    const { riskScore } = useFingerprint();
    
    watch(riskScore, (score) => {
      if (score > (binding.value || 0.5)) {
        el.classList.add('high-risk');
        el.disabled = true;
      }
    });
  }
});
```

Usage:
```vue
<button v-fraud-detection="0.7">
  Complete Purchase
</button>
```

### Nuxt 3 Module

```js
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@tracetail/nuxt'],
  tracetail: {
    apiKey: process.env.TRACETAIL_API_KEY
  }
});
```

## TypeScript Support

Full TypeScript support with type definitions:

```vue
<script setup lang="ts">
import { useFingerprint, type Fingerprint } from '@tracetail/vue';

const { visitorId } = useFingerprint();

const processFingerprint = (fp: Fingerprint) => {
  console.log(fp.visitorId, fp.confidence);
};
</script>
```

## Options API Support

Also works with Options API:

```vue
<script>
export default {
  mounted() {
    this.$tracetail.getFingerprint().then(fp => {
      console.log('Visitor:', fp.visitorId);
    });
  }
};
</script>
```

## Testing

Mock TraceTail in tests:

```js
import { mount } from '@vue/test-utils';
import { TraceTailPlugin } from '@tracetail/vue';

const wrapper = mount(Component, {
  global: {
    plugins: [[TraceTailPlugin, {
      apiKey: 'test-key',
      config: {
        testMode: true,
        mockData: {
          visitorId: 'test-123',
          riskScore: 0.1
        }
      }
    }]]
  }
});
```

## API Reference

### Plugin Options

```js
{
  apiKey: string;        // Required
  config?: {
    enhanced?: boolean;  // Enhanced accuracy (default: true)
    timeout?: number;    // Request timeout ms (default: 5000)
    endpoint?: string;   // API endpoint
    testMode?: boolean;  // Test mode
    mockData?: object;   // Mock data for testing
  }
}
```

### Types

```typescript
interface Fingerprint {
  visitorId: string;
  confidence: number;      // 0-1
  riskScore: number;      // 0-1
  fraudulent: boolean;
  signals: SignalData;
  timestamp: Date;
}

interface FraudResult {
  block: boolean;
  challenge: boolean;
  allow: boolean;
  riskScore: number;
  reasons: string[];
}
```

## Support

- 📚 [Documentation](https://docs.tracetail.com/vue)
- 💬 [Discord Community](https://discord.gg/tracetail)
- 📧 [Email Support](mailto:support@tracetail.com)
- 🐛 [Issue Tracker](https://github.com/tracetail/tracetail/issues)

## License

MIT - see [LICENSE](LICENSE) for details.