@bambulabs/finedine-fingerprint-react 1.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Finedine
+
+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,182 @@
+# @bambulabs/finedine-fingerprint-react
+
+React hooks and components for Finedine visitor fingerprinting.
+
+## Installation
+
+```bash
+npm install @bambulabs/finedine-fingerprint-react
+```
+
+## Quick Start
+
+### Option 1: Simple Hook
+
+```jsx
+import { useVisitorId } from '@bambulabs/finedine-fingerprint-react';
+
+function App() {
+  const { visitorId, isLoading, error } = useVisitorId();
+
+  if (isLoading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error}</div>;
+
+  return <div>Visitor ID: {visitorId}</div>;
+}
+```
+
+### Option 2: Full Visitor Data
+
+```jsx
+import { useVisitorTracking } from '@bambulabs/finedine-fingerprint-react';
+
+function App() {
+  const { visitor, isLoading } = useVisitorTracking();
+
+  if (isLoading) return <div>Loading...</div>;
+
+  return (
+    <div>
+      <p>ID: {visitor?.id}</p>
+      <p>Visits: {visitor?.visitCount}</p>
+      <p>Browser: {visitor?.device?.browser?.name}</p>
+      <p>Device: {visitor?.device?.device?.type}</p>
+    </div>
+  );
+}
+```
+
+### Option 3: Context Provider (Recommended for Apps)
+
+```jsx
+// App.jsx
+import { FingerprintProvider } from '@bambulabs/finedine-fingerprint-react';
+
+function App() {
+  return (
+    <FingerprintProvider>
+      <YourApp />
+    </FingerprintProvider>
+  );
+}
+
+// Any component
+import { useFingerprint } from '@bambulabs/finedine-fingerprint-react';
+
+function Header() {
+  const { visitor, visitorId } = useFingerprint();
+  return <span>Welcome! Visit #{visitor?.visitCount}</span>;
+}
+```
+
+## API Reference
+
+### Hooks
+
+#### `useVisitorId(options?)`
+
+Simple hook returning just the visitor ID.
+
+```typescript
+const { visitorId, isLoading, error, identify, clear } = useVisitorId({
+  apiUrl: 'https://track.finedinemenu.com/fingerprint', // optional
+  storageKey: 'fp_visitor_id', // optional
+  autoIdentify: true, // optional, default: true
+});
+```
+
+#### `useVisitorTracking(options?)`
+
+Full hook with complete visitor data.
+
+```typescript
+const { visitor, isLoading, error, identify, clear } = useVisitorTracking({
+  apiUrl: 'https://track.finedinemenu.com/fingerprint',
+  storageKey: 'fp_visitor_id',
+  autoIdentify: true,
+});
+```
+
+#### `useFingerprint()`
+
+Context hook (use within `FingerprintProvider`).
+
+```typescript
+const { visitor, visitorId, isLoading, error, identify, clear } = useFingerprint();
+```
+
+### Components
+
+#### `<FingerprintProvider>`
+
+Context provider for app-wide visitor tracking.
+
+```jsx
+<FingerprintProvider
+  apiUrl="https://track.finedinemenu.com/fingerprint"
+  storageKey="fp_visitor_id"
+  autoIdentify={true}
+>
+  {children}
+</FingerprintProvider>
+```
+
+### Standalone Client
+
+For non-React usage:
+
+```javascript
+import { createFingerprintClient } from '@bambulabs/finedine-fingerprint-react';
+
+const client = createFingerprintClient({
+  apiUrl: 'https://track.finedinemenu.com/fingerprint',
+});
+
+// Identify visitor
+const visitor = await client.identify();
+console.log(visitor.id, visitor.visitCount);
+
+// Get stored ID
+const storedId = client.getStoredId();
+
+// Clear stored data
+client.clear();
+```
+
+## Types
+
+```typescript
+interface Visitor {
+  id: string;
+  fingerprint: string;
+  isNew: boolean;
+  firstSeen: Date;
+  visitCount: number;
+  device: {
+    browser: { name: string; version: string };
+    os: { name: string; version: string };
+    device: { type: string; vendor: string; model: string };
+  };
+}
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `apiUrl` | `string` | `https://track.finedinemenu.com/fingerprint` | API endpoint |
+| `storageKey` | `string` | `fp_visitor_id` | localStorage/cookie key |
+| `autoIdentify` | `boolean` | `true` | Auto-identify on mount |
+
+## How It Works
+
+1. **Check localStorage** - Fastest, checked first
+2. **Check cookie** - Fallback (server-set)
+3. **Generate fingerprint** - Ultimate fallback using FingerprintJS
+
+This ensures visitors are always identified, even after clearing storage.
+
+## License
+
+MIT
+

package/dist/FingerprintContext.d.ts

@@ -0,0 +1,18 @@
+import { ReactNode } from 'react';
+import { FingerprintContextValue } from './types';
+interface FingerprintProviderProps {
+    children: ReactNode;
+    apiUrl?: string;
+    storageKey?: string;
+    autoIdentify?: boolean;
+}
+/**
+ * Provider component for app-wide visitor tracking
+ */
+export declare function FingerprintProvider({ children, apiUrl, storageKey, autoIdentify, }: FingerprintProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Hook to access visitor data from context
+ * Must be used within FingerprintProvider
+ */
+export declare function useFingerprint(): FingerprintContextValue;
+export {};

package/dist/client.d.ts

@@ -0,0 +1,10 @@
+import { FingerprintConfig, Visitor } from './types';
+export interface FingerprintClient {
+    identify: () => Promise<Visitor>;
+    getStoredId: () => string | null;
+    clear: () => void;
+}
+/**
+ * Create a fingerprint client for non-React usage
+ */
+export declare function createFingerprintClient(config?: Partial<FingerprintConfig>): FingerprintClient;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { FingerprintProvider, useFingerprint } from './FingerprintContext';
+export { useVisitorId } from './useVisitorId';
+export { useVisitorTracking } from './useVisitorTracking';
+export { createFingerprintClient } from './client';
+export type { Visitor, VisitorDevice, VisitorResponse, FingerprintConfig, FingerprintContextValue, } from './types';