@qredex/angular 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,156 @@
+<!--
+    ▄▄▄▄
+  ▄█▀▀███▄▄              █▄
+  ██    ██ ▄             ██
+  ██    ██ ████▄▄█▀█▄ ▄████ ▄█▀█▄▀██ ██▀
+  ██  ▄ ██ ██   ██▄█▀ ██ ██ ██▄█▀  ███
+   ▀█████▄▄█▀  ▄▀█▄▄▄▄█▀███▄▀█▄▄▄▄██ ██▄
+        ▀█
+
+  Copyright (C) 2026 — 2026, Qredex, LTD. All Rights Reserved.
+
+  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+
+  This file is part of the Qredex Agent SDK and is licensed under the MIT License. See LICENSE.
+  Redistribution and use are permitted under that license.
+
+  If you need additional information or have any questions, please email: copyright@qredex.com
+-->
+
+# @qredex/angular
+
+Thin Angular bindings for `@qredex/agent`.
+
+[![CI](https://github.com/Qredex/qredex-agent/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Qredex/qredex-agent/actions/workflows/ci.yml)
+[![Release](https://github.com/Qredex/qredex-agent/actions/workflows/release.yml/badge.svg)](https://github.com/Qredex/qredex-agent/actions/workflows/release.yml)
+[![npm version](https://img.shields.io/npm/v/%40qredex%2Fangular.svg)](https://www.npmjs.com/package/@qredex/angular)
+[![license](https://img.shields.io/npm/l/%40qredex%2Fangular)](LICENSE)
+
+## Install
+
+```bash
+npm install @qredex/angular
+```
+
+## Attribution Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Bootstrap as App bootstrap
+    participant Component as Cart component
+    participant Agent as QredexAgent
+
+    Bootstrap->>Agent: provideQredexAgent()
+    User->>Component: Land with ?qdx_intent=iit_xxx
+    Component->>Agent: injectQredexAgent()
+    Note right of Agent: Captures IIT automatically<br/>No function call needed
+
+    User->>Component: Cart item count changes
+    Component->>Agent: agent.handleCartChange({ itemCount, previousCount })
+    Note right of Agent: Locks IIT to PIT internally when lockable
+
+    User->>Component: Checkout
+    Component->>Agent: agent.getPurchaseIntentToken()
+    Note right of Component: Send PIT with the order to your backend
+
+    User->>Component: Cart is cleared
+    Component->>Agent: agent.handleCartEmpty()
+
+    opt No cart-empty step after checkout
+        Component->>Agent: agent.handlePaymentSuccess()
+    end
+```
+
+Call `provideQredexAgent()` once at bootstrap, get the runtime with `injectQredexAgent()`, then forward merchant cart state with `agent.handleCartChange(...)`, read the PIT with `agent.getPurchaseIntentToken()`, and clear attribution with `agent.handleCartEmpty()`. Only call `agent.handlePaymentSuccess()` if your platform has no cart-empty step after checkout.
+
+## Recommended Integration
+
+Register `provideQredexAgent()` once, then call `injectQredexAgent()` inside the existing cart surface you already control.
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { Component, Input, OnChanges } from '@angular/core';
+import { injectQredexAgent, provideQredexAgent } from '@qredex/angular';
+
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideQredexAgent(),
+  ],
+});
+
+@Component({
+  selector: 'qredex-cart-bridge',
+  standalone: true,
+  template: `
+    <span>Qredex status: {{ agent.hasPurchaseIntentToken() ? 'locked' : 'waiting' }}</span>
+    <button (click)="clearCart()">Clear cart</button>
+    <button [disabled]="!agent.hasPurchaseIntentToken()" (click)="submitOrder()">
+      Send PIT to backend
+    </button>
+  `,
+})
+export class QredexCartBridgeComponent implements OnChanges {
+  @Input() itemCount = 0;
+
+  private previousCount = 0;
+  readonly agent = injectQredexAgent();
+
+  ngOnChanges(): void {
+    this.agent.handleCartChange({
+      itemCount: this.itemCount,
+      previousCount: this.previousCount,
+    });
+
+    this.previousCount = this.itemCount;
+  }
+
+  async clearCart(): Promise<void> {
+    await fetch('/api/cart/clear', {
+      method: 'POST',
+    });
+
+    this.agent.handleCartEmpty();
+  }
+
+  async submitOrder(): Promise<void> {
+    const pit = this.agent.getPurchaseIntentToken();
+
+    await fetch('/api/orders', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        orderId: 'order-123',
+        qredex_pit: pit,
+      }),
+    });
+
+    await this.clearCart();
+  }
+}
+```
+
+## What To Call When
+
+| Merchant event | Call | Why |
+|---|---|---|
+| App bootstrap | `provideQredexAgent()` | Makes the agent available to Angular surfaces |
+| Cart becomes non-empty | `agent.handleCartChange({ itemCount, previousCount })` | Gives Qredex the live cart state so IIT can lock to PIT |
+| Cart changes while still non-empty | `agent.handleCartChange(...)` | Safe retry path on the next merchant-reported non-empty cart event if a previous lock failed |
+| Clear cart action | `clearCart() -> agent.handleCartEmpty()` | Clears IIT/PIT from the live session |
+| Need PIT for order submission | `agent.getPurchaseIntentToken()` | Attach PIT to the checkout payload |
+| Checkout completes without a cart-empty step | `agent.handlePaymentSuccess()` | Optional explicit cleanup path |
+
+## API Surface
+
+| Export | Use |
+|---|---|
+| `provideQredexAgent()` | Primary Angular bootstrap helper |
+| `provideQredex()` | Deprecated alias for `provideQredexAgent()` |
+| `injectQredexAgent()` | Primary Angular injection helper |
+| `getQredexAgent()` | Direct access to the singleton runtime |
+| `initQredex()` | Explicit browser init when needed |
+| `QREDEX_AGENT` | Angular injection token |
+| `QredexAgent` | Re-export of the core agent |

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ *    ▄▄▄▄
+ *  ▄█▀▀███▄▄              █▄
+ *  ██    ██ ▄             ██
+ *  ██    ██ ████▄▄█▀█▄ ▄████ ▄█▀█▄▀██ ██▀
+ *  ██  ▄ ██ ██   ██▄█▀ ██ ██ ██▄█▀  ███
+ *   ▀█████▄▄█▀  ▄▀█▄▄▄▄█▀███▄▀█▄▄▄▄██ ██▄
+ *        ▀█
+ *
+ *  Copyright (C) 2026 — 2026, Qredex, LTD. All Rights Reserved.
+ *
+ *  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ *  This file is part of the Qredex Agent SDK and is licensed under the MIT License. See LICENSE.
+ *  Redistribution and use are permitted under that license.
+ *
+ *  If you need additional information or have any questions, please email: copyright@qredex.com
+ */
+import { InjectionToken, type EnvironmentProviders } from '@angular/core';
+import CoreQredexAgent, { type AgentConfig } from '@qredex/agent';
+export declare const QREDEX_AGENT: InjectionToken<{
+    getInfluenceIntentToken: typeof import("@qredex/agent").getInfluenceIntentToken;
+    getPurchaseIntentToken: typeof import("@qredex/agent").getPurchaseIntentToken;
+    hasInfluenceIntentToken: () => boolean;
+    hasPurchaseIntentToken: typeof import("@qredex/agent").hasPurchaseIntentToken;
+    getState: typeof import("@qredex/agent").getState;
+    lockIntent: typeof import("@qredex/agent").lockIntent;
+    clearIntent: () => void;
+    handleCartChange: typeof import("@qredex/agent").handleCartChange;
+    handleCartAdd: typeof import("@qredex/agent").handleCartAdd;
+    handleCartEmpty: typeof import("@qredex/agent").handleCartEmpty;
+    handlePaymentSuccess: typeof import("@qredex/agent").handlePaymentSuccess;
+    onLocked: typeof import("@qredex/agent").onLocked;
+    onCleared: typeof import("@qredex/agent").onCleared;
+    onError: typeof import("@qredex/agent").onError;
+    offLocked: typeof import("@qredex/agent").offLocked;
+    offCleared: typeof import("@qredex/agent").offCleared;
+    offError: typeof import("@qredex/agent").offError;
+    onStateChanged: typeof import("@qredex/agent").onStateChanged;
+    offStateChanged: typeof import("@qredex/agent").offStateChanged;
+    onIntentCaptured: typeof import("@qredex/agent").onIntentCaptured;
+    offIntentCaptured: typeof import("@qredex/agent").offIntentCaptured;
+    init: typeof import("@qredex/agent").init;
+    isInitialized: typeof import("@qredex/agent").isInitialized;
+    destroy: typeof import("@qredex/agent").destroy;
+    stop: typeof import("@qredex/agent").stop;
+}>;
+export declare function getQredexAgent(): typeof CoreQredexAgent;
+export declare function initQredex(config?: AgentConfig): typeof CoreQredexAgent;
+export declare function provideQredexAgent(config?: AgentConfig): EnvironmentProviders;
+/**
+ * @deprecated Use provideQredexAgent() instead.
+ */
+export declare function provideQredex(config?: AgentConfig): EnvironmentProviders;
+export declare function injectQredexAgent(): typeof CoreQredexAgent;
+export { CoreQredexAgent as QredexAgent };
+export * from '@qredex/agent';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAEL,cAAc,EAGd,KAAK,oBAAoB,EAC1B,MAAM,eAAe,CAAC;AACvB,OAAO,eAAe,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAMlE,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;EAEvB,CAAC;AAEH,wBAAgB,cAAc,IAAI,OAAO,eAAe,CAEvD;AAED,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,eAAe,CAMvE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,oBAAoB,CAc7E;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,oBAAoB,CAExE;AAED,wBAAgB,iBAAiB,IAAI,OAAO,eAAe,CAE1D;AAED,OAAO,EAAE,eAAe,IAAI,WAAW,EAAE,CAAC;AAC1C,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,62 @@
+/**
+ *    ▄▄▄▄
+ *  ▄█▀▀███▄▄              █▄
+ *  ██    ██ ▄             ██
+ *  ██    ██ ████▄▄█▀█▄ ▄████ ▄█▀█▄▀██ ██▀
+ *  ██  ▄ ██ ██   ██▄█▀ ██ ██ ██▄█▀  ███
+ *   ▀█████▄▄█▀  ▄▀█▄▄▄▄█▀███▄▀█▄▄▄▄██ ██▄
+ *        ▀█
+ *
+ *  Copyright (C) 2026 — 2026, Qredex, LTD. All Rights Reserved.
+ *
+ *  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ *  This file is part of the Qredex Agent SDK and is licensed under the MIT License. See LICENSE.
+ *  Redistribution and use are permitted under that license.
+ *
+ *  If you need additional information or have any questions, please email: copyright@qredex.com
+ */
+import { ENVIRONMENT_INITIALIZER, InjectionToken, inject, makeEnvironmentProviders, } from '@angular/core';
+import CoreQredexAgent from '@qredex/agent';
+function canUseBrowser() {
+    return typeof window !== 'undefined';
+}
+export const QREDEX_AGENT = new InjectionToken('QREDEX_AGENT', {
+    factory: () => CoreQredexAgent,
+});
+export function getQredexAgent() {
+    return CoreQredexAgent;
+}
+export function initQredex(config) {
+    if (canUseBrowser() && (config !== undefined || !CoreQredexAgent.isInitialized())) {
+        CoreQredexAgent.init(config);
+    }
+    return CoreQredexAgent;
+}
+export function provideQredexAgent(config) {
+    return makeEnvironmentProviders([
+        {
+            provide: QREDEX_AGENT,
+            useValue: CoreQredexAgent,
+        },
+        {
+            provide: ENVIRONMENT_INITIALIZER,
+            multi: true,
+            useValue: () => {
+                initQredex(config);
+            },
+        },
+    ]);
+}
+/**
+ * @deprecated Use provideQredexAgent() instead.
+ */
+export function provideQredex(config) {
+    return provideQredexAgent(config);
+}
+export function injectQredexAgent() {
+    return inject(QREDEX_AGENT);
+}
+export { CoreQredexAgent as QredexAgent };
+export * from '@qredex/agent';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,MAAM,EACN,wBAAwB,GAEzB,MAAM,eAAe,CAAC;AACvB,OAAO,eAAqC,MAAM,eAAe,CAAC;AAElE,SAAS,aAAa;IACpB,OAAO,OAAO,MAAM,KAAK,WAAW,CAAC;AACvC,CAAC;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,cAAc,CAAyB,cAAc,EAAE;IACrF,OAAO,EAAE,GAAG,EAAE,CAAC,eAAe;CAC/B,CAAC,CAAC;AAEH,MAAM,UAAU,cAAc;IAC5B,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAoB;IAC7C,IAAI,aAAa,EAAE,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,eAAe,CAAC,aAAa,EAAE,CAAC,EAAE,CAAC;QAClF,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,MAAoB;IACrD,OAAO,wBAAwB,CAAC;QAC9B;YACE,OAAO,EAAE,YAAY;YACrB,QAAQ,EAAE,eAAe;SAC1B;QACD;YACE,OAAO,EAAE,uBAAuB;YAChC,KAAK,EAAE,IAAI;YACX,QAAQ,EAAE,GAAG,EAAE;gBACb,UAAU,CAAC,MAAM,CAAC,CAAC;YACrB,CAAC;SACF;KACF,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,MAAoB;IAChD,OAAO,kBAAkB,CAAC,MAAM,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,MAAM,CAAC,YAAY,CAAC,CAAC;AAC9B,CAAC;AAED,OAAO,EAAE,eAAe,IAAI,WAAW,EAAE,CAAC;AAC1C,cAAc,eAAe,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@qredex/angular",
+  "version": "1.0.0",
+  "description": "Angular wrapper for Qredex Agent",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@qredex/agent": "^1.0.0"
+  },
+  "devDependencies": {
+    "@qredex/agent": "file:../.."
+  },
+  "peerDependencies": {
+    "@angular/core": ">=17.0.0 <21.0.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Qredex/qredex-agent.git",
+    "directory": "packages/angular"
+  },
+  "homepage": "https://github.com/Qredex/qredex-agent/tree/main/packages/angular#readme",
+  "bugs": {
+    "url": "https://github.com/Qredex/qredex-agent/issues"
+  }
+}