@simplr-ai/angular 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simplr
+
+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.

package/README.md

@@ -0,0 +1,257 @@
+# @simplr-ai/angular
+
+Idiomatic **Angular adapter** for the [Simplr](https://simplr.so) platform.
+
+This package is a **thin wrapper** over the browser core SDK
+[`@simplr-ai/js`](../simplr-js-sdk). It does **not** reimplement any
+feature — it exposes the core's full surface through Angular primitives:
+**injectable DI services**, **RxJS observables**, and **directives + a component**.
+
+Everything the core can do — device fingerprinting, behavioral biometrics,
+fraud/identity checks, order scoring, feature flags (local eval), Real User
+Monitoring (RUM), anonymous profiles, and AI delegation — has an idiomatic
+Angular binding here.
+
+> Docs: https://docs.simplr.so/docs/sdks/angular
+
+## Install
+
+```bash
+npm i @simplr-ai/angular @simplr-ai/js @angular/core rxjs
+```
+
+`@angular/core` (`^17 || ^18`), `@angular/common`, `rxjs` (`^7`) and
+`@simplr-ai/js` are **peer dependencies**.
+
+## Setup
+
+### Standalone (recommended) — `provideSimplr()`
+
+```ts
+import { bootstrapApplication } from "@angular/platform-browser";
+import { provideSimplr } from "@simplr-ai/angular";
+import { AppComponent } from "./app/app.component";
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideSimplr({
+      apiKey: "pk_live_…", // your public key
+      flags: { environment: "live", refreshIntervalMs: 60_000 },
+      rum: { applicationId: "my-app", environment: "production" },
+    }),
+  ],
+});
+```
+
+Pipe uncaught errors into RUM by enabling the optional error handler:
+
+```ts
+provideSimplr({ apiKey: "pk_live_…" }, { errorHandler: true });
+```
+
+### NgModule — `SimplrModule.forRoot()`
+
+```ts
+import { NgModule } from "@angular/core";
+import { SimplrModule } from "@simplr-ai/angular";
+
+@NgModule({
+  imports: [SimplrModule.forRoot({ apiKey: "pk_live_…" })],
+})
+export class AppModule {}
+```
+
+The directives and component (`simplrProtect`, `simplrRumView`,
+`simplr-protected-form`) are standalone and re-exported by `SimplrModule`. In
+standalone components import them directly (or use the `SIMPLR_DIRECTIVES`
+array).
+
+---
+
+## Features
+
+Each feature is bound through an injectable service. All async methods are
+available as a Promise and an `*$` Observable variant (via RxJS `from`).
+
+### Device fingerprint + behavioral biometrics + fraud check — `SimplrService`
+
+```ts
+import { Component, inject } from "@angular/core";
+import { SimplrService } from "@simplr-ai/angular";
+
+@Component({ /* … */ })
+export class CheckoutComponent {
+  private simplr = inject(SimplrService);
+
+  async pay() {
+    const signals = await this.simplr.collect();        // device + behavior
+    const device = await this.simplr.getDeviceSignals(); // fingerprint only
+    const result = await this.simplr.check({ email: "a@b.com" }); // POST /v1/check
+  }
+
+  // Observable variants
+  signals$ = this.simplr.collect$();
+}
+```
+
+#### `[simplrProtect]` directive — protect a form on submit
+
+Collects fresh device + behavior signals on submit and emits them. Prevents the
+native submit by default (set `[simplrPreventDefault]="false"` to opt out).
+
+```html
+<form simplrProtect (simplrSignals)="onSignals($event)" (simplrError)="onErr($event)">
+  <input name="email" />
+  <button type="submit">Pay</button>
+</form>
+```
+
+#### `<simplr-protected-form>` component
+
+```html
+<simplr-protected-form (submitWithSignals)="submit($event.signals)">
+  <input name="email" />
+  <button type="submit">Pay</button>
+</simplr-protected-form>
+```
+
+### Feature flags (local eval) — `SimplrFlagsService`
+
+Deterministic per-user rollout + targeting, evaluated locally. `flags$` emits
+the full flag map on every refresh; `observeFlag` emits a boolean stream.
+
+```ts
+import { Component, inject, OnInit } from "@angular/core";
+import { SimplrFlagsService } from "@simplr-ai/angular";
+
+@Component({ /* … */ })
+export class FeatureComponent implements OnInit {
+  private flags = inject(SimplrFlagsService);
+
+  newCheckout$ = this.flags.observeFlag("new-checkout"); // Observable<boolean>
+
+  async ngOnInit() {
+    await this.flags.initialize();      // loads flags + starts refresh loop
+    this.flags.setUser("user_123");
+    if (this.flags.isEnabled("beta")) { /* … */ }
+  }
+}
+```
+
+```html
+<app-new-checkout *ngIf="newCheckout$ | async"></app-new-checkout>
+```
+
+### Profiles / identify + order scoring — `SimplrProfilesService`
+
+Anonymous profile management and real-time order fraud scoring. Device
+fingerprints are auto-collected.
+
+```ts
+const profiles = inject(SimplrProfilesService);
+
+await profiles.identify("user_123");                  // POST /v1/profiles
+const order = await profiles.submitOrder({            // POST /v1/orders
+  external_order_id: "ord_1",
+  amount_cents: 4999,
+  currency: "USD",
+});
+const risk = await profiles.getProfileRisk("user_123"); // GET /v1/profiles/{id}
+await profiles.reportOutcome("user_123", "fraud");
+
+// Observable variants: identify$, submitOrder$, getProfileRisk$, reportOutcome$
+```
+
+### Real User Monitoring (RUM) — `SimplrRumService`
+
+Full RUM surface. Auto-collects sessions, views, clicks, network, errors and
+performance; batches + flushes.
+
+```ts
+const rum = inject(SimplrRumService);
+
+rum.initialize({ applicationId: "my-app" });
+rum.setUser("user_123", { plan: "pro" });
+rum.addAttribute("tenant", "acme");
+rum.trackView("Checkout", { step: 2 });
+rum.trackAction("Add to cart", "click");
+rum.trackError(new Error("boom"));
+rum.log("info", "checkout started");
+await rum.flush();
+const sessionId = rum.getSessionId();
+```
+
+#### `[simplrRumView]` directive — declarative view tracking
+
+```html
+<section [simplrRumView]="'Checkout'" [simplrRumViewAttributes]="{ step: 2 }"></section>
+```
+
+#### `SimplrErrorHandler` — pipe uncaught errors into RUM
+
+Enable via `provideSimplr(config, { errorHandler: true })`, or register
+manually:
+
+```ts
+import { ErrorHandler } from "@angular/core";
+import { SimplrErrorHandler } from "@simplr-ai/angular";
+
+providers: [{ provide: ErrorHandler, useClass: SimplrErrorHandler }];
+```
+
+### AI delegation — `SimplrAIService`
+
+OAuth-like AI authentication. Full surface
+(connect/createDelegation/validate/revoke/list/get/stats/revokeAllForUser).
+
+```ts
+const ai = inject(SimplrAIService);
+
+const conn = await ai.connect({ userId: "user_123" });       // popup/redirect
+const del = await ai.createDelegation({ userId: "user_123" });
+const check = await ai.validate(token);
+const list = await ai.list("user_123");
+const stats = await ai.stats();
+await ai.revoke(del.delegationId, "logout");
+await ai.revokeAllForUser("user_123");
+
+// Every method also has an Observable `*$` variant.
+```
+
+---
+
+## Feature checklist coverage
+
+| Contract feature              | Angular binding                                              |
+| ----------------------------- | ----------------------------------------------------------- |
+| Device fingerprint            | `SimplrService.getDeviceSignals()/$`                        |
+| Behavioral biometrics         | `SimplrService` (`collect`, `trackInput`, `[simplrProtect]`) |
+| Fraud / identity `/v1/check`  | `SimplrService.check()/$`                                   |
+| Order scoring `/v1/orders`    | `SimplrProfilesService.submitOrder()/$`                     |
+| Feature flags (local eval)    | `SimplrFlagsService` (`flags$`, `observeFlag`, `isEnabled`) |
+| RUM (full)                    | `SimplrRumService`, `[simplrRumView]`, `SimplrErrorHandler` |
+| Profiles / identify           | `SimplrProfilesService` (`identify`, `getProfileRisk`, …)   |
+| AI delegation                 | `SimplrAIService` (full surface)                           |
+| Input validation helpers      | re-exported from `@simplr-ai/js` core               |
+
+## Re-exported core types & helpers
+
+For convenience the package re-exports the core SDK's classes
+(`SimplrFraud`, `SimplrFlags`, `SimplrProfiles`, `SimplrRUM`, `SimplrAI`),
+helpers (`getDeviceId`, `murmurHash3`, `sha256`, …) and all public types — so
+you can import everything from `@simplr-ai/angular` without reaching into the
+core package.
+
+## Build note (tsup vs ng-packagr)
+
+This library is built with **tsup** (esm + cjs + `.d.ts`), not ng-packagr. It
+ships as plain TypeScript with emitted decorator metadata (`@swc/core`), and is
+**Ivy-partial-free** — i.e. no `*.partial.js` Ivy compilation artifacts. This
+keeps the build fast and fully verifiable headlessly without the Angular CLI
+toolchain. Angular consumers can use it directly: the standalone directives and
+component are decorated and the services use explicit `@Inject` tokens, so JIT
+and AOT apps both resolve them correctly.
+
+## License
+
+MIT