@tracetail/angular/README.md

Angular SDK for TraceTail browser fingerprinting - over 99.5% accuracy

# @tracetail/angular

Official Angular 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
- 🏗️ **Angular 14+** - Full support for modern Angular versions

## Installation

```bash
npm install @tracetail/angular
```

## Quick Start

### 1. Import TraceTailModule

```typescript
import { TraceTailModule } from '@tracetail/angular';

@NgModule({
  imports: [
    TraceTailModule.forRoot({
      apiKey: 'your-api-key-here',
      config: {
        enhanced: true
      }
    })
  ]
})
export class AppModule { }
```

### 2. Use in Components

```typescript
import { TraceTailService } from '@tracetail/angular';

@Component({
  template: `
    <div *ngIf="fingerprint$ | async as fp">
      Visitor: {{ fp.visitorId }}
      Risk: {{ fp.riskScore }}
    </div>
  `
})
export class MyComponent {
  fingerprint$ = this.traceTail.fingerprint$;
  
  constructor(private traceTail: TraceTailService) {}
}
```

## Features

### 🔐 Fraud Detection Guard

Protect routes from high-risk visitors:

```typescript
const routes: Routes = [
  {
    path: 'checkout',
    component: CheckoutComponent,
    canActivate: [FraudProtectionGuard],
    data: { maxRiskScore: 0.5 }
  }
];
```

### 🎨 Fraud Detection Directive

Apply fraud detection to any element:

```html
<button 
  appFraudDetection="high" 
  [disableOnRisk]="true"
  class="purchase-btn"
>
  Complete Purchase
</button>
```

### 🔄 HTTP Interceptor

Automatically add visitor ID to all API requests:

```typescript
// Automatically included when using forRoot()
// Adds X-TraceTail-Visitor-ID header to requests
```

### 📊 Event Tracking

Track user actions with fraud detection:

```typescript
async onLogin(credentials: any) {
  const result = await this.traceTail.trackEvent('login', {
    username: credentials.username
  });
  
  if (result.fraudulent) {
    // Handle fraud
  }
}
```

## API Reference

### TraceTailService

- `fingerprint$: Observable<Fingerprint>` - Current fingerprint data
- `loading$: Observable<boolean>` - Loading state
- `error$: Observable<Error>` - Error state
- `getFingerprint(): Promise<Fingerprint>` - Get fingerprint as promise
- `trackEvent(event, data?): Promise<TrackingResult>` - Track events
- `checkFraud(data): Promise<FraudResult>` - Check fraud risk
- `retry(): void` - Retry fingerprinting
- `refresh(): Promise<void>` - Force refresh

### Types

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

## Examples

### Authentication Protection

```typescript
@Component({
  template: `
    <form (ngSubmit)="login()">
      <div *ngIf="(riskScore$ | async) > 0.7" class="warning">
        High risk detected - additional verification required
      </div>
      <!-- form fields -->
    </form>
  `
})
export class LoginComponent {
  riskScore$ = this.traceTail.fingerprint$.pipe(
    map(fp => fp?.riskScore || 0)
  );
  
  constructor(private traceTail: TraceTailService) {}
  
  async login() {
    const fp = await this.traceTail.getFingerprint();
    if (fp.riskScore > 0.7) {
      // Require 2FA
    }
  }
}
```

### Personalization

```typescript
@Injectable()
export class PersonalizationService {
  preferences$ = this.traceTail.fingerprint$.pipe(
    switchMap(fp => fp ? 
      this.http.get(`/api/preferences/${fp.visitorId}`) :
      of(null)
    )
  );
  
  constructor(
    private traceTail: TraceTailService,
    private http: HttpClient
  ) {}
}
```

## Support

- 📚 [Documentation](https://docs.tracetail.com/angular)
- 💬 [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.