npm package: @shakhearacom/tracktor
Description: A JavaScript library for event tracking with failed events storage and retry mechanism
Author: Shakheara
Latest version: 0.0.47

# @shakhearacom/tracktor

Event and user tracking library with offline retry, IndexedDB storage, and a simple React/Next.js adapter.

## Features
- Anonymous/user-based tracking with encryption-aware controllers
- Custom events, page views, interactions, performance and error tracking
- Offline detection and retry for failed events
- React/Next.js provider and hooks for easy integration

## Installation

```bash
npm install @shakhearacom/tracktor
# or
yarn add @shakhearacom/tracktor
```

If you use React/Next.js:
```bash
# peer deps (if not already present)
npm install react react-dom
```

## Quick Start (Browser)

Using ESM import:
```ts
import Tracktor from '@shakhearacom/tracktor/dist/main.js';

const t = new Tracktor();
await t.ready;

await t.authorizeUser('1234567890', { name: 'John Doe' });
await t.trackEvent('click-button', { foo: 'bar' });
```

Via script tag (UMD):
```html
<script src="/dist/main.umd.js"></script>
<script>
  const t = new window.Tracktor();
  t.ready.then(async () => {
    await t.authorizeUser('1234567890', { name: 'John Doe' });
    await t.trackEvent('click-button', { foo: 'bar' });
  });
</script>
```

## Quick Start (React / Next.js)

Wrap your app with the provider:
```tsx
import { TracktorProvider } from '@shakhearacom/tracktor/react';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return <TracktorProvider>{children}</TracktorProvider>;
}
```

Use hooks to interact with the Tracktor:
```tsx
import { useTrackEvent, useAuthorizeUser, useUser } from '@shakhearacom/tracktor/react';

export function ExampleButton() {
  const trackEvent = useTrackEvent();
  const authorizeUser = useAuthorizeUser();
  const user = useUser();

  return (
    <button
      onClick={async () => {
        await authorizeUser('1234567890', { name: 'John Doe' });
        await trackEvent('click-button', { foo: 'bar' });
      }}
    >
      Track
    </button>
  );
}
```

Available React APIs:
- `TracktorProvider` – initializes the Tracktor in the browser
- `useTracktor()` – returns `{ tracktor, isReady }`
- `useTrackEvent()` – function to send custom events
- `useAuthorizeUser()` – function to authorize/set user
- `useDeauthorizeUser()` – function to clear user
- `useUser()` – gets the decrypted user info (async on mount)

## Core API (non-React)

All methods are available on the `Tracketor` instance:
- `ready: Promise<void>` – resolves when initialization is done
- `authorizeUser(userId, userInfo?)`
- `updateUser(userId, userInfo?)` – replace existing user info
- `deauthorizeUser()`
- `getUser()` – returns `{ is_authorized, user_id, user }`
- `trackEvent(name, data)` – sends a custom event

Initialization side-effects (based on site options):
- Session tracking, page views, interactions, performance, and error tracking may auto-initialize

## TypeScript
- Types are emitted for public entries: `.` and `./react`
- `tsconfig.json` sets `jsx` to `react-jsx` for the React adapter

## Build & Development

Commands:
```bash
npm run dev         # rollup watch for demo
npm run build       # tsup + rollup build
npm run build:secure # build + obfuscate to dist-obf
```

Main outputs:
- ESM/CJS: `dist/index.js`, `dist/index.cjs`
- React subpath: `dist/react/index.js`, `dist/react/index.cjs`
- Browser UMD: `dist/main.umd.js` (+ `.map`, `.gz`)

## Notes for Next.js
- Provider only runs in the browser. Use it in client components/layouts
- Avoid calling hooks on the server
- The Tracktor waits for `ready` before allowing operations

## License
MIT