@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

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

If you use React/Next.js:

# peer deps (if not already present)
npm install react react-dom

Quick Start (Browser)

Using ESM import:

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):

<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:

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:

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:

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