first commit

packages/angular/aptabase-angular/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Sumbit Labs Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/angular/aptabase-angular/README.md

@@ -0,0 +1,93 @@
+![Aptabase](https://aptabase.com/og.png)
+
+# Aptabase SDK for Angular Apps
+
+A tiny SDK to instrument your Angular apps with Aptabase, an Open Source, Privacy-First and Simple Analytics for Mobile, Desktop and Web Apps.
+
+## Setup
+
+1. Install the SDK using npm or your preferred JavaScript package manager
+
+```bash
+npm add @aptabase/angular
+```
+
+2. Get your `App Key` from Aptabase, you can find it in the `Instructions` page.
+
+3. Pass the `App Key` when initializing your app by importing a module or providing a function.
+
+### Setup for Standalone API
+
+Provide `provideAptabaseAnalytics` in the ApplicationConfig when bootstrapping.
+
+```ts
+import { provideAptabaseAnalytics } from '@aptabase/angular';
+
+bootstrapApplication(AppComponent, {
+  providers: [..., provideAptabaseAnalytics('<YOUR_APP_KEY>')],
+}).catch((err) => console.error(err));
+```
+
+[Full example here](../examples/example-standalone/src/app)
+
+### Setup for NgModules
+
+Import `AptabaseAnalyticsModule` in your root AppModule.
+
+```ts
+import { AptabaseAnalyticsModule } from '@aptabase/angular';
+
+@NgModule({
+  declarations: [AppComponent],
+  imports: [..., AptabaseAnalyticsModule.forRoot('<YOUR_APP_KEY>')],
+  providers: [],
+  bootstrap: [AppComponent],
+})
+export class AppModule {}
+
+```
+
+[Full example here](../examples/example-modules/src/app)
+
+## Advanced setup
+
+Both versions support also support an optional second parameter `AptabaseOptions` to pass in additional options.
+
+```ts
+export type AptabaseOptions = {
+  // Custom host for self-hosted Aptabase.
+  host?: string;
+  // Custom path for API endpoint. Useful when using reverse proxy.
+  apiUrl?: string;
+  // Defines the app version.
+  appVersion?: string;
+  // Defines whether the app is running on debug mode.
+  isDebug?: boolean;
+};
+```
+
+## Tracking Events with Aptabase
+
+After the initial setup the `AptabaseAnalyticsService` can be used to start tracking events.
+Simply inject the service in a component to start tracking events:
+
+```ts
+import { AptabaseAnalyticsService } from '@aptabase/angular';
+
+export class AppComponent {
+  constructor(private _analyticsService: AptabaseAnalyticsService) {}
+
+  increment() {
+    this.counter++;
+    this._analyticsService.trackEvent('increment');
+  }
+}
+```
+
+## A few important notes:
+
+1. The SDK will automatically enhance the event with some useful information, like the OS and other properties.
+2. You're in control of what gets sent to Aptabase. This SDK does not automatically track any events, you need to call `trackEvent` manually.
+   - Because of this, it's generally recommended to at least track an event at startup
+3. You do not need to subscribe to `trackEvent` function, it'll run in the background.
+4. Only strings and numeric values are allowed on custom properties.

packages/angular/aptabase-angular/ng-package.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "../node_modules/ng-packagr/ng-package.schema.json",
+  "dest": "dist",
+  "lib": {
+    "entryFile": "src/public-api.ts"
+  }
+}

packages/angular/aptabase-angular/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@aptabase/angular",
+  "version": "0.0.6",
+  "description": "Angular SDK for Aptabase: Open Source, Privacy-First and Simple Analytics for Mobile, Desktop and Web Apps",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aptabase/aptabase-js.git",
+    "directory": "packages/angular/aptabase-angular"
+  },
+  "bugs": {
+    "url": "https://github.com/aptabase/aptabase-js/issues"
+  },
+  "homepage": "https://github.com/aptabase/aptabase-js",
+  "license": "MIT",
+  "scripts": {
+    "pre-build": "cp ../../shared.ts ./src",
+    "build": "npm run pre-build &&  ng build aptabase-angular",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@angular/common": "^17.0.0",
+    "@angular/core": "^17.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false
+}

packages/angular/aptabase-angular/src/lib/analytics.service.ts

@@ -0,0 +1,37 @@
+import { AptabaseOptions, getApiUrl, inMemorySessionId, sendEvent, validateAppKey } from '../shared';
+
+// Session expires after 1 hour of inactivity
+// TODO move this to shared?
+const SESSION_TIMEOUT = 1 * 60 * 60;
+const pkgVersion = '0.0.0'; // bog: TODO fix this version
+const sdkVersion = `aptabase-angular@${pkgVersion}`;
+
+export class AptabaseAnalyticsService {
+  private _apiUrl: string | undefined;
+
+  constructor(
+    private _appKey: string,
+    private _options: AptabaseOptions,
+  ) {
+    if (!validateAppKey(this._appKey)) return;
+
+    this._apiUrl = this._options.apiUrl ?? getApiUrl(this._appKey, this._options);
+  }
+
+  async trackEvent(eventName: string, props?: Record<string, string | number | boolean>): Promise<void> {
+    if (!this._apiUrl) return;
+
+    const sessionId = inMemorySessionId(SESSION_TIMEOUT);
+
+    await sendEvent({
+      apiUrl: this._apiUrl,
+      sessionId,
+      appKey: this._appKey,
+      isDebug: this._options?.isDebug,
+      appVersion: this._options?.appVersion,
+      sdkVersion,
+      eventName,
+      props,
+    });
+  }
+}

packages/angular/aptabase-angular/src/lib/index.ts

@@ -0,0 +1,28 @@
+import { EnvironmentProviders, NgModule, makeEnvironmentProviders } from '@angular/core';
+
+import { AptabaseOptions } from '../shared';
+import { AptabaseAnalyticsService } from './analytics.service';
+
+export function provideAptabaseAnalytics(appKey: string, options: AptabaseOptions = {}): EnvironmentProviders {
+  return makeEnvironmentProviders([
+    {
+      provide: AptabaseAnalyticsService,
+      useValue: new AptabaseAnalyticsService(appKey, options),
+    },
+  ]);
+}
+
+@NgModule()
+export class AptabaseAnalyticsModule {
+  static forRoot(appKey: string, options: AptabaseOptions = {}) {
+    return {
+      ngModule: AptabaseAnalyticsModule,
+      providers: [
+        {
+          provide: AptabaseAnalyticsService,
+          useValue: new AptabaseAnalyticsService(appKey, options),
+        },
+      ],
+    };
+  }
+}

packages/angular/aptabase-angular/src/public-api.ts

@@ -0,0 +1,6 @@
+/*
+ * Public API Surface of aptabase-angular
+ */
+
+export * from './lib/analytics.service';
+export * from './lib/index';

packages/angular/aptabase-angular/tsconfig.lib.json

@@ -0,0 +1,11 @@
+/* To learn more about this file see: https://angular.io/config/tsconfig. */
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../out-tsc/lib",
+    "declaration": true,
+    "declarationMap": true,
+    "inlineSources": true
+  },
+  "exclude": ["**/*.spec.ts"]
+}

packages/angular/aptabase-angular/tsconfig.lib.prod.json

@@ -0,0 +1,10 @@
+/* To learn more about this file see: https://angular.io/config/tsconfig. */
+{
+  "extends": "./tsconfig.lib.json",
+  "compilerOptions": {
+    "declarationMap": false
+  },
+  "angularCompilerOptions": {
+    "compilationMode": "partial"
+  }
+}

packages/angular/aptabase-angular/tsconfig.spec.json

@@ -0,0 +1,14 @@
+/* To learn more about this file see: https://angular.io/config/tsconfig. */
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../out-tsc/spec",
+    "types": [
+      "jasmine"
+    ]
+  },
+  "include": [
+    "**/*.spec.ts",
+    "**/*.d.ts"
+  ]
+}