npm package: @jakobinn/aj-client-sdk
Description: Client SDK for internal services. Updated to use Authorization headers for API key authentication.
Latest version: 4.0.0

## @jakobinn/aj-client-sdk

A lightweight client for sending analytics events with batching and graceful flushing. Works in browsers, Node.js, and React Native. Types included.

> **⚠️ Breaking Change in v2.0.0**: API key authentication has been updated to use Authorization headers instead of query parameters for improved security. See [CHANGELOG.md](./CHANGELOG.md) for migration details.

### Install

```bash
npm install @jakobinn/aj-client-sdk
# or
pnpm add @jakobinn/aj-client-sdk
# or
yarn add @jakobinn/aj-client-sdk
```

### Quick start

```ts
import { AnalyticsJJClient } from '@jakobinn/aj-client-sdk';

const analytics = new AnalyticsJJClient({
  apiKey: 'YOUR_SERVER_API_KEY',
  host: 'YOUR_ANALYTICS_HOST_URL',
  refer: true,   // optional (browser-only): auto track ?trc11 and external referrers
  debug: false,  // optional: log request diagnostics
});

analytics.track('SCREEN_VIEW', 'HOME_SCREEN_OPENED', { userId: 'user_123' });
analytics.feedback('FEATURE_RATING', 'FEATURE_MODAL', { rating: 5, text: 'Great!' });

// Flush immediately if needed
await analytics.flush();
```

### Configuration

- apiKey (string, required): Your server-issued API key.
- host (string, optional): Base URL of your analytics API (e.g., `https://your-analytics-domain.com`). If omitted in the browser, requests go to the current origin.
- flushInterval (number, optional): Milliseconds to wait after the last event before auto-flush. Default 5000.
- batchSize (number, optional): Number of queued events triggering an immediate flush. Default 20.
- refer (boolean, optional): Enables automatic browser tracking of campaign parameter `trc11` and external referrers.
- runtime (string, optional): Constant runtime identifier injected into each event. One of `'server' | 'app' | 'client' | 'browser' | 'react_native' | string`.
- setUserTimestamp (boolean, optional): If true, includes ISO timestamp in `user_timestamp` on every event.
- debug (boolean, optional): If true, logs request/response diagnostics.

Environment auto-detection:
- If you do not pass `environment`, the client uses `process.env.ENVIRONMENT` when available (`production` | `development` | `test`).

### Automatic campaign & referrer tracking (browser)

Runs once at client initialization only when `refer: true`.
- Tracks `CLICKTHROUGH` → `CAMPAIGN_CLICK` if the URL contains `?trc11=...` (once per session) and removes the param from the URL.
- Otherwise tracks `CLICKTHROUGH` → `REFERRAL_VISIT` if there is an external `document.referrer` (once per session).

### Feedback events

```ts
// Simple thumbs up/down
analytics.feedback('POSTER_LIKED', 'POSTER_WIDGET', { vote: 'GOOD' });

// Rating with text
analytics.feedback('FEATURE_RATING', 'FEATURE_MODAL', { rating: 4, text: 'Easy to use' });

// Bug report
analytics.feedback('BUG_REPORTED', 'ERROR_SCREEN', {
  kind: 'BUG', severity: 'HIGH', text: 'Crash when uploading large files', contactOk: true, email: 'user@example.com'
});
```

Feedback payload is attached to `jsonData` with schema `feedback.v1` and includes fields like `kind`, `vote`, `rating`, `text`, `tags`, `severity`, `context`, etc.

### API

```ts
new AnalyticsJJClient(config: {
  apiKey: string;
  host?: string;
  flushInterval?: number;
  batchSize?: number;
  refer?: boolean;
  runtime?: 'server' | 'app' | 'client' | 'browser' | 'react_native' | string;
  setUserTimestamp?: boolean;
  debug?: boolean;
});

track(eventType: AnalyticsEventType, eventName: string, properties?: TrackProperties): void;
feedback(eventName: string, source: string, data?: Partial<FeedbackDataV1>, properties?: TrackProperties): void;
flush(): Promise<void>;
```

Key types:
- AnalyticsEventType: `CLICKTHROUGH | INTERACTION | SUBMIT | SEARCH | SCREEN_VIEW | SYSTEM | ERROR | SESSION | AUTH | CONVERSION | FEEDBACK | CUSTOM`
- TrackProperties highlights: `userId`, `email`, `groupId`, `subscriptionStatus`, `isSubscribed`, `data`, `jsonData`, `environment`, `event_name_detailed`, `runtime`, `user_timestamp`.

### Auth and transport

- **API Key Authentication**: Uses `Authorization: Bearer <apiKey>` header for all requests
- **Transport**: `POST /api/v1/track` with JSON body `{ events: [...] }`
- **Security**: API keys are never exposed in URLs or server logs
- **Standards**: Follows HTTP authentication conventions

### Troubleshooting

- 400 from server: enable `debug: true` to log status and body preview; verify `host`, `apiKey`, and that your server accepts the auth and payload formats above.
- React Native networking:
  - Android emulator → host machine: use `http://10.0.2.2:<port>` instead of `http://localhost:<port>`
  - iOS simulator: `http://localhost:<port>` works. Physical devices should use your machine's LAN IP.