visitory/README.md

Visitory Session Tracking SDK

# Insightful Button

A React button component that tracks user actions and sends them to your Convex backend.

## Installation

```bash
npm install visitory
```

## Usage

First, get your API key from the Visitory dashboard. Then initialize the tracking with your API key:

```typescript
import { InsightfulButton, initInsightful } from 'visitory'

// Initialize with your API key
initInsightful({
  apiKey: 'your-api-key-from-dashboard',
  // Optional: Override the default Convex URL
  convexUrl: 'https://your-custom-convex-backend.convex.cloud',
})

// Use the button component
function App() {
  return <InsightfulButton text="Click Me" variant="primary" size="medium" />
}
```

## Features

- Tracks user actions (clicks, form submissions, page views, etc.)
- Sends tracked actions to your Convex backend
- Customizable button appearance
- TypeScript support
- API key authentication
- Pre-configured with a default Convex backend

## Props

The `InsightfulButton` component accepts the following props:

| Prop           | Type                                 | Default    | Description                        |
| -------------- | ------------------------------------ | ---------- | ---------------------------------- |
| text           | string                               | "Click Me" | Text to display on the button      |
| id             | string                               | undefined  | Optional ID for the button element |
| className      | string                               | ""         | Optional CSS class name            |
| onClick        | function                             | undefined  | Optional click handler             |
| variant        | 'primary' \| 'secondary' \| 'danger' | "primary"  | Button style variant               |
| size           | 'small' \| 'medium' \| 'large'       | "medium"   | Button size                        |
| disabled       | boolean                              | false      | Disabled state                     |
| enableTracking | boolean                              | true       | Enable/disable action tracking     |

## Tracked Actions

The component tracks various user actions and sends them to your Convex backend:

- Button clicks
- Page views
- Form submissions
- Page exits
- General clicks on the page

Each tracked action includes:

- Action type
- Timestamp
- Page path
- Element information (when applicable)
- Mouse coordinates (for clicks)
- Additional context-specific details

## API

### `initInsightful(config: InsightfulConfig)`

Initialize the Insightful tracking with your configuration.

```typescript
interface InsightfulConfig {
  apiKey: string // Your API key from the Visitory dashboard
  convexUrl?: string // Optional: Your Convex backend URL
}
```

### `trackAction(type: string, details?: Record<string, any>)`

Manually track a custom action.

### `getTrackedActions(): TrackedAction[]`

Get all currently tracked actions.

### `clearTrackedActions(): void`

Clear all tracked actions.

## License

MIT