@qredex/vue 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/vue
+
+Thin Vue 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%2Fvue.svg)](https://www.npmjs.com/package/@qredex/vue)
+[![license](https://img.shields.io/npm/l/%40qredex%2Fvue)](LICENSE)
+
+## Install
+
+```bash
+npm install @qredex/vue
+```
+
+## Attribution Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Storefront as Your cart UI
+    participant Wrapper as useQredexAgent()
+    participant Agent as QredexAgent
+
+    User->>Storefront: Land with ?qdx_intent=iit_xxx
+    Storefront->>Wrapper: useQredexAgent()
+    Note right of Agent: Captures IIT automatically<br/>No function call needed
+
+    User->>Storefront: Cart item count changes
+    Storefront->>Agent: agent.handleCartChange({ itemCount, previousCount })
+    Note right of Agent: Locks IIT to PIT internally when lockable
+
+    User->>Storefront: Checkout
+    Storefront->>Agent: agent.getPurchaseIntentToken()
+    Note right of Storefront: Send PIT with the order to your backend
+
+    User->>Storefront: Cart is cleared
+    Storefront->>Agent: agent.handleCartEmpty()
+
+    opt No cart-empty step after checkout
+        Storefront->>Agent: agent.handlePaymentSuccess()
+    end
+```
+
+Call `useQredexAgent()`, 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 the plugin once, then use `useQredexAgent()` inside the cart surface you already control.
+
+```ts
+// main.ts
+import { createApp } from 'vue';
+import App from './App.vue';
+import { createQredexPlugin } from '@qredex/vue';
+
+const app = createApp(App);
+app.use(createQredexPlugin());
+app.mount('#app');
+```
+
+```vue
+<script setup lang="ts">
+import { ref, watch } from 'vue';
+import { useQredexAgent } from '@qredex/vue';
+
+const { agent, state } = useQredexAgent();
+const itemCount = ref(0);
+const previousCount = ref(0);
+
+watch(itemCount, (nextCount) => {
+  agent.handleCartChange({
+    itemCount: nextCount,
+    previousCount: previousCount.value,
+  });
+
+  previousCount.value = nextCount;
+}, { immediate: true });
+
+async function clearCart() {
+  await fetch('/api/cart/clear', {
+    method: 'POST',
+  });
+
+  agent.handleCartEmpty();
+}
+
+async function submitOrder() {
+  const pit = state.value.pit ?? agent.getPurchaseIntentToken();
+
+  await fetch('/api/orders', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      orderId: 'order-123',
+      qredex_pit: pit,
+    }),
+  });
+
+  await clearCart();
+}
+</script>
+
+<template>
+  <div>
+    <span>Qredex status: {{ state.locked ? 'locked' : 'waiting' }}</span>
+    <button @click="clearCart">Clear cart</button>
+    <button :disabled="!state.hasPIT" @click="submitOrder">
+      Send PIT to backend
+    </button>
+  </div>
+</template>
+```
+
+## What To Call When
+
+| Merchant event | Call | Why |
+|---|---|---|
+| 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 | `state.value.pit` or `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 |
+|---|---|
+| `createQredexPlugin()` | Registers the core agent in the Vue app |
+| `useQredexAgent()` | Primary Vue composable. Returns `{ agent, state }` |
+| `useQredex()` | Deprecated alias for `useQredexAgent()` |
+| `useInjectedQredexAgent()` | Direct access to the injected agent |
+| `getQredexAgent()` | Direct access to the singleton runtime |
+| `initQredex()` | Explicit browser init when needed |
+| `QredexAgent` | Re-export of the core agent |

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+/**
+ *    ▄▄▄▄
+ *  ▄█▀▀███▄▄              █▄
+ *  ██    ██ ▄             ██
+ *  ██    ██ ████▄▄█▀█▄ ▄████ ▄█▀█▄▀██ ██▀
+ *  ██  ▄ ██ ██   ██▄█▀ ██ ██ ██▄█▀  ███
+ *   ▀█████▄▄█▀  ▄▀█▄▄▄▄█▀███▄▀█▄▄▄▄██ ██▄
+ *        ▀█
+ *
+ *  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 { type App, type InjectionKey, type ShallowRef } from 'vue';
+import CoreQredexAgent, { type AgentConfig } from '@qredex/agent';
+export type QredexState = ReturnType<typeof CoreQredexAgent.getState>;
+export interface QredexComposable {
+    agent: typeof CoreQredexAgent;
+    state: Readonly<ShallowRef<QredexState>>;
+}
+export declare const QredexAgentKey: InjectionKey<typeof CoreQredexAgent>;
+export declare function getQredexAgent(): typeof CoreQredexAgent;
+export declare function initQredex(config?: AgentConfig): typeof CoreQredexAgent;
+export declare function createQredexPlugin(config?: AgentConfig): {
+    install(app: App): void;
+};
+export declare function useInjectedQredexAgent(): typeof CoreQredexAgent;
+export declare function useQredexAgent(config?: AgentConfig): QredexComposable;
+/**
+ * @deprecated Use useQredexAgent() instead.
+ */
+export declare function useQredex(config?: AgentConfig): QredexComposable;
+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,EAML,KAAK,GAAG,EACR,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,KAAK,CAAC;AACb,OAAO,eAAe,EAAE,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAElE,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,eAAe,CAAC,QAAQ,CAAC,CAAC;AACtE,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,eAAe,CAAC;IAC9B,KAAK,EAAE,QAAQ,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC;CAC1C;AAYD,eAAO,MAAM,cAAc,EAAE,YAAY,CAAC,OAAO,eAAe,CAAyB,CAAC;AAM1F,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;IAAE,OAAO,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAA;CAAE,CAOpF;AAED,wBAAgB,sBAAsB,IAAI,OAAO,eAAe,CAE/D;AAED,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,gBAAgB,CA0BrE;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,gBAAgB,CAEhE;AAED,OAAO,EAAE,eAAe,IAAI,WAAW,EAAE,CAAC;AAC1C,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,84 @@
+/**
+ *    ▄▄▄▄
+ *  ▄█▀▀███▄▄              █▄
+ *  ██    ██ ▄             ██
+ *  ██    ██ ████▄▄█▀█▄ ▄████ ▄█▀█▄▀██ ██▀
+ *  ██  ▄ ██ ██   ██▄█▀ ██ ██ ██▄█▀  ███
+ *   ▀█████▄▄█▀  ▄▀█▄▄▄▄█▀███▄▀█▄▄▄▄██ ██▄
+ *        ▀█
+ *
+ *  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 { inject, onMounted, onUnmounted, readonly, shallowRef, } from 'vue';
+import CoreQredexAgent from '@qredex/agent';
+const SERVER_STATE = {
+    hasIIT: false,
+    hasPIT: false,
+    iit: null,
+    pit: null,
+    cartState: 'unknown',
+    locked: false,
+    timestamp: 0,
+};
+export const QredexAgentKey = Symbol('QredexAgent');
+function canUseBrowser() {
+    return typeof window !== 'undefined';
+}
+export function getQredexAgent() {
+    return CoreQredexAgent;
+}
+export function initQredex(config) {
+    if (canUseBrowser() && (config !== undefined || !CoreQredexAgent.isInitialized())) {
+        CoreQredexAgent.init(config);
+    }
+    return CoreQredexAgent;
+}
+export function createQredexPlugin(config) {
+    return {
+        install(app) {
+            initQredex(config);
+            app.provide(QredexAgentKey, CoreQredexAgent);
+        },
+    };
+}
+export function useInjectedQredexAgent() {
+    return inject(QredexAgentKey, CoreQredexAgent);
+}
+export function useQredexAgent(config) {
+    const state = shallowRef(SERVER_STATE);
+    let unsubscribe = () => undefined;
+    onMounted(() => {
+        initQredex(config);
+        state.value = CoreQredexAgent.getState();
+        const handler = () => {
+            state.value = CoreQredexAgent.getState();
+        };
+        CoreQredexAgent.onStateChanged(handler);
+        unsubscribe = () => {
+            CoreQredexAgent.offStateChanged(handler);
+        };
+    });
+    onUnmounted(() => {
+        unsubscribe();
+    });
+    return {
+        agent: CoreQredexAgent,
+        state: readonly(state),
+    };
+}
+/**
+ * @deprecated Use useQredexAgent() instead.
+ */
+export function useQredex(config) {
+    return useQredexAgent(config);
+}
+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,MAAM,EACN,SAAS,EACT,WAAW,EACX,QAAQ,EACR,UAAU,GAIX,MAAM,KAAK,CAAC;AACb,OAAO,eAAqC,MAAM,eAAe,CAAC;AAQlE,MAAM,YAAY,GAAgB;IAChC,MAAM,EAAE,KAAK;IACb,MAAM,EAAE,KAAK;IACb,GAAG,EAAE,IAAI;IACT,GAAG,EAAE,IAAI;IACT,SAAS,EAAE,SAAS;IACpB,MAAM,EAAE,KAAK;IACb,SAAS,EAAE,CAAC;CACb,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAyC,MAAM,CAAC,aAAa,CAAC,CAAC;AAE1F,SAAS,aAAa;IACpB,OAAO,OAAO,MAAM,KAAK,WAAW,CAAC;AACvC,CAAC;AAED,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;QACL,OAAO,CAAC,GAAQ;YACd,UAAU,CAAC,MAAM,CAAC,CAAC;YACnB,GAAG,CAAC,OAAO,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;QAC/C,CAAC;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB;IACpC,OAAO,MAAM,CAAC,cAAc,EAAE,eAAe,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAoB;IACjD,MAAM,KAAK,GAAG,UAAU,CAAc,YAAY,CAAC,CAAC;IACpD,IAAI,WAAW,GAAG,GAAG,EAAE,CAAC,SAAS,CAAC;IAElC,SAAS,CAAC,GAAG,EAAE;QACb,UAAU,CAAC,MAAM,CAAC,CAAC;QACnB,KAAK,CAAC,KAAK,GAAG,eAAe,CAAC,QAAQ,EAAE,CAAC;QAEzC,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,KAAK,CAAC,KAAK,GAAG,eAAe,CAAC,QAAQ,EAAE,CAAC;QAC3C,CAAC,CAAC;QAEF,eAAe,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QACxC,WAAW,GAAG,GAAG,EAAE;YACjB,eAAe,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,WAAW,CAAC,GAAG,EAAE;QACf,WAAW,EAAE,CAAC;IAChB,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,EAAE,eAAe;QACtB,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC;KACvB,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,MAAoB;IAC5C,OAAO,cAAc,CAAC,MAAM,CAAC,CAAC;AAChC,CAAC;AAED,OAAO,EAAE,eAAe,IAAI,WAAW,EAAE,CAAC;AAC1C,cAAc,eAAe,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@qredex/vue",
+  "version": "1.0.0",
+  "description": "Vue 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": {
+    "vue": "^3.4.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Qredex/qredex-agent.git",
+    "directory": "packages/vue"
+  },
+  "homepage": "https://github.com/Qredex/qredex-agent/tree/main/packages/vue#readme",
+  "bugs": {
+    "url": "https://github.com/Qredex/qredex-agent/issues"
+  }
+}