@kitbase/analytics-angular 0.1.6

package/README.md

@@ -0,0 +1,332 @@
+# @kitbase/analytics-angular
+
+Angular integration for the Kitbase Analytics SDK.
+
+## Installation
+
+```bash
+npm install @kitbase/analytics-angular
+# or
+pnpm add @kitbase/analytics-angular
+# or
+yarn add @kitbase/analytics-angular
+```
+
+## Usage
+
+### Option 1: Direct — just call `init()`
+
+No Angular DI needed. Call `init()` anywhere (e.g. `main.ts`, a component, a service):
+
+```typescript
+import { init } from '@kitbase/analytics-angular';
+
+const kitbase = init({ sdkKey: 'your-api-key' });
+
+// Track events
+kitbase.track({ channel: 'ui', event: 'Button Clicked' });
+
+// Identify users
+kitbase.identify({ userId: 'user-123', traits: { email: 'user@example.com' } });
+```
+
+You can retrieve the instance later with `getInstance()`:
+
+```typescript
+import { getInstance } from '@kitbase/analytics-angular';
+
+const kitbase = getInstance();
+kitbase?.track({ channel: 'ui', event: 'Page Loaded' });
+```
+
+### Option 2: Angular DI — `provideKitbaseAnalytics()` + `inject()`
+
+Register the provider in your app config, then inject it in any component or service:
+
+```typescript
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideKitbaseAnalytics } from '@kitbase/analytics-angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideKitbaseAnalytics({
+      sdkKey: 'your-sdk-key',
+      debug: true,
+    }),
+  ],
+};
+```
+
+```typescript
+// component.ts
+import { Component, inject } from '@angular/core';
+import { KitbaseAnalyticsService } from '@kitbase/analytics-angular';
+
+@Component({
+  selector: 'app-button',
+  template: '<button (click)="onClick()">Click me</button>',
+})
+export class ButtonComponent {
+  private kitbase = inject(KitbaseAnalyticsService);
+
+  onClick() {
+    this.kitbase.track({
+      channel: 'ui',
+      event: 'Button Clicked',
+      tags: { button_id: 'cta' },
+    });
+  }
+}
+```
+
+## Configuration
+
+```typescript
+init({
+  // Required
+  sdkKey: 'your-api-key',
+
+  // Optional
+  debug: true,
+  baseUrl: 'https://api.kitbase.dev',
+
+  analytics: {
+    autoTrackPageViews: true,     // track route changes automatically
+    autoTrackOutboundLinks: true, // track external link clicks
+    autoTrackClicks: true,        // track button/link/input clicks + data-kb-track-click
+    autoTrackScrollDepth: true,   // track max scroll depth per page
+    autoTrackVisibility: true,    // track visibility duration via data attributes
+    autoTrackWebVitals: false,    // track Core Web Vitals (LCP, CLS, INP, FCP, TTFB)
+    autoDetectFrustration: true,  // detect rage clicks and dead clicks
+  },
+
+  offline: {
+    enabled: true,                // queue events when offline
+    maxQueueSize: 1000,
+    flushInterval: 30000,
+    flushBatchSize: 50,
+    maxRetries: 3,
+  },
+});
+```
+
+Page views, clicks, outbound links, scroll depth, and visibility duration are tracked automatically by default. The core SDK intercepts `history.pushState`/`popstate`, so no Angular Router integration is needed.
+
+## Data Attribute Events
+
+Track events from HTML using data attributes — no JavaScript needed. Works in Angular, React, or vanilla HTML.
+
+### Click Tracking
+
+Fire a named event when a user clicks an element:
+
+```html
+<!-- Basic -->
+<button data-kb-track-click="CTA Clicked">Sign Up Now</button>
+
+<!-- With custom channel -->
+<button data-kb-track-click="Add to Cart" data-kb-click-channel="ecommerce">
+  Add to Cart
+</button>
+```
+
+| Attribute | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `data-kb-track-click` | Yes | — | Event name to fire |
+| `data-kb-click-channel` | No | `'engagement'` | Channel for the event |
+
+Elements with `data-kb-track-click` skip the generic auto-click tracking to avoid double-counting. Disable with `autoTrackClicks: false`.
+
+### Visibility Duration
+
+Track how long elements are visible in the viewport:
+
+```html
+<!-- Basic -->
+<section data-kb-track-visibility="Pricing Section Viewed">...</section>
+
+<!-- With optional channel and threshold -->
+<div
+  data-kb-track-visibility="Hero Banner Viewed"
+  data-kb-visibility-channel="marketing"
+  data-kb-visibility-threshold="0.5"
+>...</div>
+```
+
+| Attribute | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `data-kb-track-visibility` | Yes | — | Event name to fire |
+| `data-kb-visibility-channel` | No | `'engagement'` | Channel for the event |
+| `data-kb-visibility-threshold` | No | `0.5` | IntersectionObserver threshold (0–1) |
+
+When the element leaves the viewport, navigates away, or is removed from the DOM, the SDK fires an event with `duration_seconds` and `duration_ms` tags.
+
+Dynamically added elements (e.g. from Angular `@if` or `*ngIf`) are picked up automatically via MutationObserver. Disable with `autoTrackVisibility: false`.
+
+## Web Vitals
+
+Track [Core Web Vitals](https://web.dev/vitals/) by enabling `autoTrackWebVitals`:
+
+```typescript
+init({
+  sdkKey: 'your-api-key',
+  analytics: {
+    autoTrackWebVitals: true,
+  },
+});
+```
+
+The SDK collects all 5 metrics (LCP, CLS, INP, FCP, TTFB) and sends them as a single `web_vitals` event. Metrics are sent once per page load with a 30-second timeout. Only collected metrics are included. See the [core SDK README](../core/README.md#web-vitals) for full details.
+
+## API Reference
+
+### Event Tracking
+
+| Method | Description |
+|--------|-------------|
+| `track(options)` | Track a custom event |
+| `trackPageView(options?)` | Track a page view |
+| `trackRevenue(options)` | Track a revenue event |
+| `trackOutboundLink(options)` | Track an outbound link click |
+| `trackClick(tags)` | Track a click event |
+
+### User Identification
+
+| Method | Description |
+|--------|-------------|
+| `identify(options)` | Identify a user with traits |
+| `getUserId()` | Get the identified user ID |
+| `reset()` | Reset user identity |
+
+### Super Properties
+
+| Method | Description |
+|--------|-------------|
+| `register(properties)` | Set super properties (included in all events) |
+| `registerOnce(properties)` | Set super properties only if not already set |
+| `unregister(key)` | Remove a super property |
+| `getSuperProperties()` | Get all super properties |
+| `clearSuperProperties()` | Clear all super properties |
+
+### Time Events
+
+| Method | Description |
+|--------|-------------|
+| `timeEvent(eventName)` | Start timing an event |
+| `cancelTimeEvent(eventName)` | Cancel timing an event |
+| `getTimedEvents()` | List all active timed events |
+| `getEventDuration(eventName)` | Get elapsed time in ms |
+
+### Plugin System
+
+| Method | Description |
+|--------|-------------|
+| `use(plugin)` | Register a plugin |
+| `getPlugins()` | Get names of all registered plugins |
+
+### Debug
+
+| Method | Description |
+|--------|-------------|
+| `setDebugMode(enabled)` | Toggle debug logging |
+| `isDebugMode()` | Check if debug mode is on |
+| `shutdown()` | Shutdown the SDK and cleanup |
+| `getInstance()` | Get the underlying KitbaseAnalytics instance |
+
+## Examples
+
+### Track Events
+
+```typescript
+kitbase.track({
+  channel: 'ecommerce',
+  event: 'Add to Cart',
+  tags: { product_id: 'sku-123', price: 29.99 },
+});
+```
+
+### Identify Users
+
+```typescript
+await kitbase.identify({
+  userId: user.id,
+  traits: { email: user.email, plan: user.plan },
+});
+
+// On logout
+kitbase.reset();
+```
+
+### Track Duration
+
+```typescript
+// Start timer
+kitbase.timeEvent('Video Watched');
+
+// ... user watches video ...
+
+// Track event — $duration tag is automatically included
+kitbase.track({
+  channel: 'engagement',
+  event: 'Video Watched',
+  tags: { video_id: 'abc' },
+});
+```
+
+### Track Revenue
+
+```typescript
+kitbase.trackRevenue({
+  amount: 19.99,
+  currency: 'USD',
+  tags: { plan: 'pro', cycle: 'monthly' },
+});
+```
+
+### Plugins
+
+```typescript
+import { KitbaseAnalyticsService, WebVitalsPlugin } from '@kitbase/analytics-angular';
+
+@Component({
+  selector: 'app-root',
+  template: '<router-outlet />',
+})
+export class AppComponent {
+  private kitbase = inject(KitbaseAnalyticsService);
+
+  constructor() {
+    this.kitbase.use(new WebVitalsPlugin());
+    console.log('Active plugins:', this.kitbase.getPlugins());
+  }
+}
+```
+
+### Re-exported Types
+
+All types, errors, and utilities from `@kitbase/analytics` are re-exported:
+
+```typescript
+import {
+  type KitbaseConfig,
+  type TrackOptions,
+  type KitbasePlugin,
+  KitbaseError,
+  ValidationError,
+} from '@kitbase/analytics-angular';
+```
+
+## Running the Example App
+
+```bash
+cd examples
+pnpm install
+pnpm start
+```
+
+Opens at `http://localhost:4200` with an interactive dashboard to test all SDK features.
+
+## License
+
+MIT

package/dist/README.md

@@ -0,0 +1,332 @@
+# @kitbase/analytics-angular
+
+Angular integration for the Kitbase Analytics SDK.
+
+## Installation
+
+```bash
+npm install @kitbase/analytics-angular
+# or
+pnpm add @kitbase/analytics-angular
+# or
+yarn add @kitbase/analytics-angular
+```
+
+## Usage
+
+### Option 1: Direct — just call `init()`
+
+No Angular DI needed. Call `init()` anywhere (e.g. `main.ts`, a component, a service):
+
+```typescript
+import { init } from '@kitbase/analytics-angular';
+
+const kitbase = init({ sdkKey: 'your-api-key' });
+
+// Track events
+kitbase.track({ channel: 'ui', event: 'Button Clicked' });
+
+// Identify users
+kitbase.identify({ userId: 'user-123', traits: { email: 'user@example.com' } });
+```
+
+You can retrieve the instance later with `getInstance()`:
+
+```typescript
+import { getInstance } from '@kitbase/analytics-angular';
+
+const kitbase = getInstance();
+kitbase?.track({ channel: 'ui', event: 'Page Loaded' });
+```
+
+### Option 2: Angular DI — `provideKitbaseAnalytics()` + `inject()`
+
+Register the provider in your app config, then inject it in any component or service:
+
+```typescript
+// app.config.ts
+import { ApplicationConfig } from '@angular/core';
+import { provideKitbaseAnalytics } from '@kitbase/analytics-angular';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideKitbaseAnalytics({
+      sdkKey: 'your-sdk-key',
+      debug: true,
+    }),
+  ],
+};
+```
+
+```typescript
+// component.ts
+import { Component, inject } from '@angular/core';
+import { KitbaseAnalyticsService } from '@kitbase/analytics-angular';
+
+@Component({
+  selector: 'app-button',
+  template: '<button (click)="onClick()">Click me</button>',
+})
+export class ButtonComponent {
+  private kitbase = inject(KitbaseAnalyticsService);
+
+  onClick() {
+    this.kitbase.track({
+      channel: 'ui',
+      event: 'Button Clicked',
+      tags: { button_id: 'cta' },
+    });
+  }
+}
+```
+
+## Configuration
+
+```typescript
+init({
+  // Required
+  sdkKey: 'your-api-key',
+
+  // Optional
+  debug: true,
+  baseUrl: 'https://api.kitbase.dev',
+
+  analytics: {
+    autoTrackPageViews: true,     // track route changes automatically
+    autoTrackOutboundLinks: true, // track external link clicks
+    autoTrackClicks: true,        // track button/link/input clicks + data-kb-track-click
+    autoTrackScrollDepth: true,   // track max scroll depth per page
+    autoTrackVisibility: true,    // track visibility duration via data attributes
+    autoTrackWebVitals: false,    // track Core Web Vitals (LCP, CLS, INP, FCP, TTFB)
+    autoDetectFrustration: true,  // detect rage clicks and dead clicks
+  },
+
+  offline: {
+    enabled: true,                // queue events when offline
+    maxQueueSize: 1000,
+    flushInterval: 30000,
+    flushBatchSize: 50,
+    maxRetries: 3,
+  },
+});
+```
+
+Page views, clicks, outbound links, scroll depth, and visibility duration are tracked automatically by default. The core SDK intercepts `history.pushState`/`popstate`, so no Angular Router integration is needed.
+
+## Data Attribute Events
+
+Track events from HTML using data attributes — no JavaScript needed. Works in Angular, React, or vanilla HTML.
+
+### Click Tracking
+
+Fire a named event when a user clicks an element:
+
+```html
+<!-- Basic -->
+<button data-kb-track-click="CTA Clicked">Sign Up Now</button>
+
+<!-- With custom channel -->
+<button data-kb-track-click="Add to Cart" data-kb-click-channel="ecommerce">
+  Add to Cart
+</button>
+```
+
+| Attribute | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `data-kb-track-click` | Yes | — | Event name to fire |
+| `data-kb-click-channel` | No | `'engagement'` | Channel for the event |
+
+Elements with `data-kb-track-click` skip the generic auto-click tracking to avoid double-counting. Disable with `autoTrackClicks: false`.
+
+### Visibility Duration
+
+Track how long elements are visible in the viewport:
+
+```html
+<!-- Basic -->
+<section data-kb-track-visibility="Pricing Section Viewed">...</section>
+
+<!-- With optional channel and threshold -->
+<div
+  data-kb-track-visibility="Hero Banner Viewed"
+  data-kb-visibility-channel="marketing"
+  data-kb-visibility-threshold="0.5"
+>...</div>
+```
+
+| Attribute | Required | Default | Description |
+|-----------|----------|---------|-------------|
+| `data-kb-track-visibility` | Yes | — | Event name to fire |
+| `data-kb-visibility-channel` | No | `'engagement'` | Channel for the event |
+| `data-kb-visibility-threshold` | No | `0.5` | IntersectionObserver threshold (0–1) |
+
+When the element leaves the viewport, navigates away, or is removed from the DOM, the SDK fires an event with `duration_seconds` and `duration_ms` tags.
+
+Dynamically added elements (e.g. from Angular `@if` or `*ngIf`) are picked up automatically via MutationObserver. Disable with `autoTrackVisibility: false`.
+
+## Web Vitals
+
+Track [Core Web Vitals](https://web.dev/vitals/) by enabling `autoTrackWebVitals`:
+
+```typescript
+init({
+  sdkKey: 'your-api-key',
+  analytics: {
+    autoTrackWebVitals: true,
+  },
+});
+```
+
+The SDK collects all 5 metrics (LCP, CLS, INP, FCP, TTFB) and sends them as a single `web_vitals` event. Metrics are sent once per page load with a 30-second timeout. Only collected metrics are included. See the [core SDK README](../core/README.md#web-vitals) for full details.
+
+## API Reference
+
+### Event Tracking
+
+| Method | Description |
+|--------|-------------|
+| `track(options)` | Track a custom event |
+| `trackPageView(options?)` | Track a page view |
+| `trackRevenue(options)` | Track a revenue event |
+| `trackOutboundLink(options)` | Track an outbound link click |
+| `trackClick(tags)` | Track a click event |
+
+### User Identification
+
+| Method | Description |
+|--------|-------------|
+| `identify(options)` | Identify a user with traits |
+| `getUserId()` | Get the identified user ID |
+| `reset()` | Reset user identity |
+
+### Super Properties
+
+| Method | Description |
+|--------|-------------|
+| `register(properties)` | Set super properties (included in all events) |
+| `registerOnce(properties)` | Set super properties only if not already set |
+| `unregister(key)` | Remove a super property |
+| `getSuperProperties()` | Get all super properties |
+| `clearSuperProperties()` | Clear all super properties |
+
+### Time Events
+
+| Method | Description |
+|--------|-------------|
+| `timeEvent(eventName)` | Start timing an event |
+| `cancelTimeEvent(eventName)` | Cancel timing an event |
+| `getTimedEvents()` | List all active timed events |
+| `getEventDuration(eventName)` | Get elapsed time in ms |
+
+### Plugin System
+
+| Method | Description |
+|--------|-------------|
+| `use(plugin)` | Register a plugin |
+| `getPlugins()` | Get names of all registered plugins |
+
+### Debug
+
+| Method | Description |
+|--------|-------------|
+| `setDebugMode(enabled)` | Toggle debug logging |
+| `isDebugMode()` | Check if debug mode is on |
+| `shutdown()` | Shutdown the SDK and cleanup |
+| `getInstance()` | Get the underlying KitbaseAnalytics instance |
+
+## Examples
+
+### Track Events
+
+```typescript
+kitbase.track({
+  channel: 'ecommerce',
+  event: 'Add to Cart',
+  tags: { product_id: 'sku-123', price: 29.99 },
+});
+```
+
+### Identify Users
+
+```typescript
+await kitbase.identify({
+  userId: user.id,
+  traits: { email: user.email, plan: user.plan },
+});
+
+// On logout
+kitbase.reset();
+```
+
+### Track Duration
+
+```typescript
+// Start timer
+kitbase.timeEvent('Video Watched');
+
+// ... user watches video ...
+
+// Track event — $duration tag is automatically included
+kitbase.track({
+  channel: 'engagement',
+  event: 'Video Watched',
+  tags: { video_id: 'abc' },
+});
+```
+
+### Track Revenue
+
+```typescript
+kitbase.trackRevenue({
+  amount: 19.99,
+  currency: 'USD',
+  tags: { plan: 'pro', cycle: 'monthly' },
+});
+```
+
+### Plugins
+
+```typescript
+import { KitbaseAnalyticsService, WebVitalsPlugin } from '@kitbase/analytics-angular';
+
+@Component({
+  selector: 'app-root',
+  template: '<router-outlet />',
+})
+export class AppComponent {
+  private kitbase = inject(KitbaseAnalyticsService);
+
+  constructor() {
+    this.kitbase.use(new WebVitalsPlugin());
+    console.log('Active plugins:', this.kitbase.getPlugins());
+  }
+}
+```
+
+### Re-exported Types
+
+All types, errors, and utilities from `@kitbase/analytics` are re-exported:
+
+```typescript
+import {
+  type KitbaseConfig,
+  type TrackOptions,
+  type KitbasePlugin,
+  KitbaseError,
+  ValidationError,
+} from '@kitbase/analytics-angular';
+```
+
+## Running the Example App
+
+```bash
+cd examples
+pnpm install
+pnpm start
+```
+
+Opens at `http://localhost:4200` with an interactive dashboard to test all SDK features.
+
+## License
+
+MIT

package/dist/fesm2022/kitbase-analytics-angular.mjs

@@ -0,0 +1,215 @@
+import { makeEnvironmentProviders } from '@angular/core';
+import { init } from '@kitbase/analytics';
+export * from '@kitbase/analytics';
+
+/**
+ * Angular integration for Kitbase Analytics SDK
+ *
+ * Two ways to use:
+ *
+ * **1. Direct usage — just call `init()`:**
+ * ```typescript
+ * import { init } from '@kitbase/analytics-angular';
+ *
+ * const kitbase = init({ sdkKey: 'your-api-key' });
+ * kitbase.track({ channel: 'ui', event: 'Button Clicked' });
+ * ```
+ *
+ * **2. Angular DI — use `provideKitbaseAnalytics()` + `inject()`:**
+ * ```typescript
+ * // app.config.ts
+ * import { provideKitbaseAnalytics } from '@kitbase/analytics-angular';
+ *
+ * export const appConfig = {
+ *   providers: [
+ *     provideKitbaseAnalytics({ sdkKey: 'your-api-key' }),
+ *   ],
+ * };
+ *
+ * // component.ts
+ * import { KitbaseAnalyticsService } from '@kitbase/analytics-angular';
+ *
+ * export class MyComponent {
+ *   private kitbase = inject(KitbaseAnalyticsService);
+ *
+ *   onClick() {
+ *     this.kitbase.track({ channel: 'ui', event: 'Button Clicked' });
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * KitbaseAnalytics service for Angular applications.
+ *
+ * This abstract class serves as both the DI token and the type definition.
+ * Use `inject(KitbaseAnalyticsService)` in your components.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'app-button',
+ *   template: '<button (click)="onClick()">Click me</button>',
+ * })
+ * export class ButtonComponent {
+ *   private kitbase = inject(KitbaseAnalyticsService);
+ *
+ *   onClick() {
+ *     this.kitbase.track({
+ *       channel: 'ui',
+ *       event: 'Button Clicked',
+ *       tags: { button_id: 'cta' },
+ *     });
+ *   }
+ * }
+ * ```
+ */
+class KitbaseAnalyticsService {
+}
+class KitbaseAnalyticsServiceImpl extends KitbaseAnalyticsService {
+    kitbase;
+    constructor(config) {
+        super();
+        this.kitbase = init(config);
+    }
+    getInstance() {
+        return this.kitbase;
+    }
+    shutdown() {
+        this.kitbase.shutdown();
+    }
+    // Event Tracking
+    track(options) {
+        return this.kitbase.track(options);
+    }
+    trackPageView(options) {
+        return this.kitbase.trackPageView(options);
+    }
+    trackRevenue(options) {
+        return this.kitbase.trackRevenue(options);
+    }
+    trackOutboundLink(options) {
+        return this.kitbase.trackOutboundLink(options);
+    }
+    trackClick(tags) {
+        return this.kitbase.trackClick(tags);
+    }
+    // User Identification
+    identify(options) {
+        return this.kitbase.identify(options);
+    }
+    getUserId() {
+        return this.kitbase.getUserId();
+    }
+    reset() {
+        this.kitbase.reset();
+    }
+    // Super Properties
+    register(properties) {
+        this.kitbase.register(properties);
+    }
+    registerOnce(properties) {
+        this.kitbase.registerOnce(properties);
+    }
+    unregister(key) {
+        this.kitbase.unregister(key);
+    }
+    getSuperProperties() {
+        return this.kitbase.getSuperProperties();
+    }
+    clearSuperProperties() {
+        this.kitbase.clearSuperProperties();
+    }
+    // Time Events
+    timeEvent(eventName) {
+        this.kitbase.timeEvent(eventName);
+    }
+    cancelTimeEvent(eventName) {
+        this.kitbase.cancelTimeEvent(eventName);
+    }
+    getTimedEvents() {
+        return this.kitbase.getTimedEvents();
+    }
+    getEventDuration(eventName) {
+        return this.kitbase.getEventDuration(eventName);
+    }
+    // Debug & Utilities
+    setDebugMode(enabled) {
+        this.kitbase.setDebugMode(enabled);
+    }
+    isDebugMode() {
+        return this.kitbase.isDebugMode();
+    }
+    // Plugin System
+    use(plugin) {
+        this.kitbase.use(plugin);
+    }
+    getPlugins() {
+        return this.kitbase.getPlugins();
+    }
+}
+// ============================================================
+// Provider Function (Standalone API)
+// ============================================================
+/**
+ * Provide KitbaseAnalytics analytics for standalone Angular applications.
+ *
+ * Page views, clicks, outbound links, and scroll depth are tracked automatically
+ * by the core SDK (it intercepts history.pushState/popstate), so no additional
+ * Angular Router integration is needed.
+ *
+ * @example
+ * ```typescript
+ * // main.ts
+ * import { provideKitbaseAnalytics } from '@kitbase/analytics-angular';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideKitbaseAnalytics({
+ *       sdkKey: 'your-api-key',
+ *       debug: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With offline mode — events are queued locally in IndexedDB
+ * // and automatically sent when back online.
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideKitbaseAnalytics({
+ *       sdkKey: 'your-api-key',
+ *       offline: {
+ *         enabled: true,
+ *         maxQueueSize: 1000,    // max events to store (default: 1000)
+ *         flushInterval: 30000,  // flush every 30s (default: 30000)
+ *         flushBatchSize: 50,    // events per batch (default: 50)
+ *         maxRetries: 3,         // retry attempts (default: 3)
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+function provideKitbaseAnalytics(config) {
+    // Create the instance eagerly so auto-tracking (clicks, page views,
+    // scroll depth, outbound links) is set up at bootstrap time.
+    const instance = new KitbaseAnalyticsServiceImpl(config);
+    const providers = [
+        {
+            provide: KitbaseAnalyticsService,
+            useValue: instance,
+        },
+    ];
+    return makeEnvironmentProviders(providers);
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { KitbaseAnalyticsService, provideKitbaseAnalytics };
+//# sourceMappingURL=kitbase-analytics-angular.mjs.map

package/dist/fesm2022/kitbase-analytics-angular.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"kitbase-analytics-angular.mjs","sources":["../../src/index.ts","../../src/kitbase-analytics-angular.ts"],"sourcesContent":["/**\n * Angular integration for Kitbase Analytics SDK\n *\n * Two ways to use:\n *\n * **1. Direct usage — just call `init()`:**\n * ```typescript\n * import { init } from '@kitbase/analytics-angular';\n *\n * const kitbase = init({ sdkKey: 'your-api-key' });\n * kitbase.track({ channel: 'ui', event: 'Button Clicked' });\n * ```\n *\n * **2. Angular DI — use `provideKitbaseAnalytics()` + `inject()`:**\n * ```typescript\n * // app.config.ts\n * import { provideKitbaseAnalytics } from '@kitbase/analytics-angular';\n *\n * export const appConfig = {\n *   providers: [\n *     provideKitbaseAnalytics({ sdkKey: 'your-api-key' }),\n *   ],\n * };\n *\n * // component.ts\n * import { KitbaseAnalyticsService } from '@kitbase/analytics-angular';\n *\n * export class MyComponent {\n *   private kitbase = inject(KitbaseAnalyticsService);\n *\n *   onClick() {\n *     this.kitbase.track({ channel: 'ui', event: 'Button Clicked' });\n *   }\n * }\n * ```\n *\n * @packageDocumentation\n */\n\nimport {\n  Provider,\n  makeEnvironmentProviders,\n  EnvironmentProviders,\n} from '@angular/core';\nimport {\n  init,\n  getInstance,\n  type KitbaseAnalytics,\n  type KitbaseConfig,\n  type TrackOptions,\n  type TrackResponse,\n  type PageViewOptions,\n  type RevenueOptions,\n  type IdentifyOptions,\n  type Tags,\n  type TagValue,\n  type AnalyticsConfig,\n  type KitbasePlugin,\n} from '@kitbase/analytics';\n\n// Re-export everything from core\nexport * from '@kitbase/analytics';\n\n/**\n * KitbaseAnalytics service for Angular applications.\n *\n * This abstract class serves as both the DI token and the type definition.\n * Use `inject(KitbaseAnalyticsService)` in your components.\n *\n * @example\n * ```typescript\n * @Component({\n *   selector: 'app-button',\n *   template: '<button (click)=\"onClick()\">Click me</button>',\n * })\n * export class ButtonComponent {\n *   private kitbase = inject(KitbaseAnalyticsService);\n *\n *   onClick() {\n *     this.kitbase.track({\n *       channel: 'ui',\n *       event: 'Button Clicked',\n *       tags: { button_id: 'cta' },\n *     });\n *   }\n * }\n * ```\n */\nexport abstract class KitbaseAnalyticsService {\n  /** Get the underlying KitbaseAnalytics instance for advanced usage */\n  abstract getInstance(): KitbaseAnalytics;\n\n  /** Shutdown the client and cleanup resources */\n  abstract shutdown(): void;\n\n  // Event Tracking\n  abstract track(options: TrackOptions): Promise<TrackResponse | void>;\n  abstract trackPageView(options?: PageViewOptions): Promise<TrackResponse | void>;\n  abstract trackRevenue(options: RevenueOptions): Promise<TrackResponse | void>;\n  abstract trackOutboundLink(options: { url: string; text?: string }): Promise<TrackResponse | void>;\n  abstract trackClick(tags: Tags): Promise<TrackResponse | void>;\n\n  // User Identification\n  abstract identify(options: IdentifyOptions): Promise<void>;\n  abstract getUserId(): string | null;\n  abstract reset(): void;\n\n  // Super Properties\n  abstract register(properties: Tags): void;\n  abstract registerOnce(properties: Tags): void;\n  abstract unregister(key: string): void;\n  abstract getSuperProperties(): Tags;\n  abstract clearSuperProperties(): void;\n\n  // Time Events\n  abstract timeEvent(eventName: string): void;\n  abstract cancelTimeEvent(eventName: string): void;\n  abstract getTimedEvents(): string[];\n  abstract getEventDuration(eventName: string): number | null;\n\n  // Debug & Utilities\n  abstract setDebugMode(enabled: boolean): void;\n  abstract isDebugMode(): boolean;\n\n  // Plugin System\n  abstract use(plugin: KitbasePlugin): void;\n  abstract getPlugins(): string[];\n}\n\nclass KitbaseAnalyticsServiceImpl extends KitbaseAnalyticsService {\n  private kitbase: KitbaseAnalytics;\n\n  constructor(config: KitbaseConfig) {\n    super();\n    this.kitbase = init(config);\n  }\n\n  getInstance(): KitbaseAnalytics {\n    return this.kitbase;\n  }\n\n  shutdown(): void {\n    this.kitbase.shutdown();\n  }\n\n  // Event Tracking\n  track(options: TrackOptions): Promise<TrackResponse | void> {\n    return this.kitbase.track(options);\n  }\n\n  trackPageView(options?: PageViewOptions): Promise<TrackResponse | void> {\n    return this.kitbase.trackPageView(options);\n  }\n\n  trackRevenue(options: RevenueOptions): Promise<TrackResponse | void> {\n    return this.kitbase.trackRevenue(options);\n  }\n\n  trackOutboundLink(options: { url: string; text?: string }): Promise<TrackResponse | void> {\n    return this.kitbase.trackOutboundLink(options);\n  }\n\n  trackClick(tags: Tags): Promise<TrackResponse | void> {\n    return this.kitbase.trackClick(tags);\n  }\n\n  // User Identification\n  identify(options: IdentifyOptions): Promise<void> {\n    return this.kitbase.identify(options);\n  }\n\n  getUserId(): string | null {\n    return this.kitbase.getUserId();\n  }\n\n  reset(): void {\n    this.kitbase.reset();\n  }\n\n  // Super Properties\n  register(properties: Tags): void {\n    this.kitbase.register(properties);\n  }\n\n  registerOnce(properties: Tags): void {\n    this.kitbase.registerOnce(properties);\n  }\n\n  unregister(key: string): void {\n    this.kitbase.unregister(key);\n  }\n\n  getSuperProperties(): Tags {\n    return this.kitbase.getSuperProperties();\n  }\n\n  clearSuperProperties(): void {\n    this.kitbase.clearSuperProperties();\n  }\n\n  // Time Events\n  timeEvent(eventName: string): void {\n    this.kitbase.timeEvent(eventName);\n  }\n\n  cancelTimeEvent(eventName: string): void {\n    this.kitbase.cancelTimeEvent(eventName);\n  }\n\n  getTimedEvents(): string[] {\n    return this.kitbase.getTimedEvents();\n  }\n\n  getEventDuration(eventName: string): number | null {\n    return this.kitbase.getEventDuration(eventName);\n  }\n\n  // Debug & Utilities\n  setDebugMode(enabled: boolean): void {\n    this.kitbase.setDebugMode(enabled);\n  }\n\n  isDebugMode(): boolean {\n    return this.kitbase.isDebugMode();\n  }\n\n  // Plugin System\n  use(plugin: KitbasePlugin): void {\n    this.kitbase.use(plugin);\n  }\n\n  getPlugins(): string[] {\n    return this.kitbase.getPlugins();\n  }\n}\n\n// ============================================================\n// Provider Function (Standalone API)\n// ============================================================\n\n/**\n * Provide KitbaseAnalytics analytics for standalone Angular applications.\n *\n * Page views, clicks, outbound links, and scroll depth are tracked automatically\n * by the core SDK (it intercepts history.pushState/popstate), so no additional\n * Angular Router integration is needed.\n *\n * @example\n * ```typescript\n * // main.ts\n * import { provideKitbaseAnalytics } from '@kitbase/analytics-angular';\n *\n * bootstrapApplication(AppComponent, {\n *   providers: [\n *     provideKitbaseAnalytics({\n *       sdkKey: 'your-api-key',\n *       debug: true,\n *     }),\n *   ],\n * });\n * ```\n *\n * @example\n * ```typescript\n * // With offline mode — events are queued locally in IndexedDB\n * // and automatically sent when back online.\n * bootstrapApplication(AppComponent, {\n *   providers: [\n *     provideKitbaseAnalytics({\n *       sdkKey: 'your-api-key',\n *       offline: {\n *         enabled: true,\n *         maxQueueSize: 1000,    // max events to store (default: 1000)\n *         flushInterval: 30000,  // flush every 30s (default: 30000)\n *         flushBatchSize: 50,    // events per batch (default: 50)\n *         maxRetries: 3,         // retry attempts (default: 3)\n *       },\n *     }),\n *   ],\n * });\n * ```\n */\nexport function provideKitbaseAnalytics(config: KitbaseConfig): EnvironmentProviders {\n  // Create the instance eagerly so auto-tracking (clicks, page views,\n  // scroll depth, outbound links) is set up at bootstrap time.\n  const instance = new KitbaseAnalyticsServiceImpl(config);\n\n  const providers: Provider[] = [\n    {\n      provide: KitbaseAnalyticsService,\n      useValue: instance,\n    },\n  ];\n\n  return makeEnvironmentProviders(providers);\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,143 @@
+import { EnvironmentProviders } from '@angular/core';
+import { KitbaseAnalytics, TrackOptions, TrackResponse, PageViewOptions, RevenueOptions, Tags, IdentifyOptions, KitbasePlugin, KitbaseConfig } from '@kitbase/analytics';
+export * from '@kitbase/analytics';
+
+/**
+ * Angular integration for Kitbase Analytics SDK
+ *
+ * Two ways to use:
+ *
+ * **1. Direct usage — just call `init()`:**
+ * ```typescript
+ * import { init } from '@kitbase/analytics-angular';
+ *
+ * const kitbase = init({ sdkKey: 'your-api-key' });
+ * kitbase.track({ channel: 'ui', event: 'Button Clicked' });
+ * ```
+ *
+ * **2. Angular DI — use `provideKitbaseAnalytics()` + `inject()`:**
+ * ```typescript
+ * // app.config.ts
+ * import { provideKitbaseAnalytics } from '@kitbase/analytics-angular';
+ *
+ * export const appConfig = {
+ *   providers: [
+ *     provideKitbaseAnalytics({ sdkKey: 'your-api-key' }),
+ *   ],
+ * };
+ *
+ * // component.ts
+ * import { KitbaseAnalyticsService } from '@kitbase/analytics-angular';
+ *
+ * export class MyComponent {
+ *   private kitbase = inject(KitbaseAnalyticsService);
+ *
+ *   onClick() {
+ *     this.kitbase.track({ channel: 'ui', event: 'Button Clicked' });
+ *   }
+ * }
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * KitbaseAnalytics service for Angular applications.
+ *
+ * This abstract class serves as both the DI token and the type definition.
+ * Use `inject(KitbaseAnalyticsService)` in your components.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'app-button',
+ *   template: '<button (click)="onClick()">Click me</button>',
+ * })
+ * export class ButtonComponent {
+ *   private kitbase = inject(KitbaseAnalyticsService);
+ *
+ *   onClick() {
+ *     this.kitbase.track({
+ *       channel: 'ui',
+ *       event: 'Button Clicked',
+ *       tags: { button_id: 'cta' },
+ *     });
+ *   }
+ * }
+ * ```
+ */
+declare abstract class KitbaseAnalyticsService {
+    /** Get the underlying KitbaseAnalytics instance for advanced usage */
+    abstract getInstance(): KitbaseAnalytics;
+    /** Shutdown the client and cleanup resources */
+    abstract shutdown(): void;
+    abstract track(options: TrackOptions): Promise<TrackResponse | void>;
+    abstract trackPageView(options?: PageViewOptions): Promise<TrackResponse | void>;
+    abstract trackRevenue(options: RevenueOptions): Promise<TrackResponse | void>;
+    abstract trackOutboundLink(options: {
+        url: string;
+        text?: string;
+    }): Promise<TrackResponse | void>;
+    abstract trackClick(tags: Tags): Promise<TrackResponse | void>;
+    abstract identify(options: IdentifyOptions): Promise<void>;
+    abstract getUserId(): string | null;
+    abstract reset(): void;
+    abstract register(properties: Tags): void;
+    abstract registerOnce(properties: Tags): void;
+    abstract unregister(key: string): void;
+    abstract getSuperProperties(): Tags;
+    abstract clearSuperProperties(): void;
+    abstract timeEvent(eventName: string): void;
+    abstract cancelTimeEvent(eventName: string): void;
+    abstract getTimedEvents(): string[];
+    abstract getEventDuration(eventName: string): number | null;
+    abstract setDebugMode(enabled: boolean): void;
+    abstract isDebugMode(): boolean;
+    abstract use(plugin: KitbasePlugin): void;
+    abstract getPlugins(): string[];
+}
+/**
+ * Provide KitbaseAnalytics analytics for standalone Angular applications.
+ *
+ * Page views, clicks, outbound links, and scroll depth are tracked automatically
+ * by the core SDK (it intercepts history.pushState/popstate), so no additional
+ * Angular Router integration is needed.
+ *
+ * @example
+ * ```typescript
+ * // main.ts
+ * import { provideKitbaseAnalytics } from '@kitbase/analytics-angular';
+ *
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideKitbaseAnalytics({
+ *       sdkKey: 'your-api-key',
+ *       debug: true,
+ *     }),
+ *   ],
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With offline mode — events are queued locally in IndexedDB
+ * // and automatically sent when back online.
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideKitbaseAnalytics({
+ *       sdkKey: 'your-api-key',
+ *       offline: {
+ *         enabled: true,
+ *         maxQueueSize: 1000,    // max events to store (default: 1000)
+ *         flushInterval: 30000,  // flush every 30s (default: 30000)
+ *         flushBatchSize: 50,    // events per batch (default: 50)
+ *         maxRetries: 3,         // retry attempts (default: 3)
+ *       },
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+declare function provideKitbaseAnalytics(config: KitbaseConfig): EnvironmentProviders;
+
+export { KitbaseAnalyticsService, provideKitbaseAnalytics };

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@kitbase/analytics-angular",
+  "version": "0.1.6",
+  "description": "Angular integration for Kitbase Analytics SDK",
+  "type": "module",
+  "module": "./dist/fesm2022/kitbase-analytics-angular.mjs",
+  "typings": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/fesm2022/kitbase-analytics-angular.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "kitbase",
+    "analytics",
+    "tracking",
+    "angular",
+    "service"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/scr2em/kitbase-sdk.git",
+    "directory": "customEvents/typescript/packages/angular"
+  },
+  "peerDependencies": {
+    "@angular/common": ">=17.0.0",
+    "@angular/core": ">=17.0.0"
+  },
+  "dependencies": {
+    "@kitbase/analytics": "0.1.6"
+  },
+  "devDependencies": {
+    "@angular/common": "^20.0.0",
+    "@angular/compiler": "^20.0.0",
+    "@angular/compiler-cli": "^20.0.0",
+    "@angular/core": "^20.0.0",
+    "ng-packagr": "^20.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^1.2.0"
+  },
+  "scripts": {
+    "build": "ng-packagr -p ng-package.json",
+    "test": "vitest run",
+    "lint": "eslint src",
+    "clean": "rm -rf dist"
+  }
+}