@qredex/svelte 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,142 @@
+<!--
+    ▄▄▄▄
+  ▄█▀▀███▄▄              █▄
+  ██    ██ ▄             ██
+  ██    ██ ████▄▄█▀█▄ ▄████ ▄█▀█▄▀██ ██▀
+  ██  ▄ ██ ██   ██▄█▀ ██ ██ ██▄█▀  ███
+   ▀█████▄▄█▀  ▄▀█▄▄▄▄█▀███▄▀█▄▄▄▄██ ██▄
+        ▀█
+
+  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/svelte
+
+Thin Svelte 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%2Fsvelte.svg)](https://www.npmjs.com/package/@qredex/svelte)
+[![license](https://img.shields.io/npm/l/%40qredex%2Fsvelte)](LICENSE)
+
+## Install
+
+```bash
+npm install @qredex/svelte
+```
+
+## 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
+
+Use `useQredexAgent()` inside the existing cart surface you already own. The wrapper stays headless.
+
+```svelte
+<script lang="ts">
+  import { useQredexAgent } from '@qredex/svelte';
+
+  export let itemCount = 0;
+
+  const { agent, state } = useQredexAgent();
+  let previousCount = itemCount;
+
+  $: if (itemCount !== previousCount) {
+    agent.handleCartChange({
+      itemCount,
+      previousCount,
+    });
+
+    previousCount = itemCount;
+  }
+
+  async function clearCart() {
+    await fetch('/api/cart/clear', {
+      method: 'POST',
+    });
+
+    agent.handleCartEmpty();
+  }
+
+  async function submitOrder() {
+    const pit = $state.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>
+
+<div>
+  <span>Qredex status: {$state.locked ? 'locked' : 'waiting'}</span>
+  <button on:click={clearCart}>Clear cart</button>
+  <button disabled={!$state.hasPIT} on:click={submitOrder}>
+    Send PIT to backend
+  </button>
+</div>
+```
+
+## 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.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 |
+|---|---|
+| `useQredexAgent()` | Primary Svelte composable. Returns `{ agent, state }` |
+| `useQredex()` | Deprecated alias for `useQredexAgent()` |
+| `createQredexStateStore()` | State store only, without the convenience composable |
+| `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,36 @@
+/**
+ *    ▄▄▄▄
+ *  ▄█▀▀███▄▄              █▄
+ *  ██    ██ ▄             ██
+ *  ██    ██ ████▄▄█▀█▄ ▄████ ▄█▀█▄▀██ ██▀
+ *  ██  ▄ ██ ██   ██▄█▀ ██ ██ ██▄█▀  ███
+ *   ▀█████▄▄█▀  ▄▀█▄▄▄▄█▀███▄▀█▄▄▄▄██ ██▄
+ *        ▀█
+ *
+ *  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 Readable } from 'svelte/store';
+import CoreQredexAgent, { type AgentConfig } from '@qredex/agent';
+export type QredexState = ReturnType<typeof CoreQredexAgent.getState>;
+export interface QredexComposable {
+    agent: typeof CoreQredexAgent;
+    state: Readable<QredexState>;
+}
+export declare function getQredexAgent(): typeof CoreQredexAgent;
+export declare function initQredex(config?: AgentConfig): typeof CoreQredexAgent;
+export declare function useQredexAgent(config?: AgentConfig): QredexComposable;
+export declare function createQredexStateStore(config?: AgentConfig): Readable<QredexState>;
+/**
+ * @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;AAGH,OAAO,EAAY,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AACvD,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,WAAW,CAAC,CAAC;CAC9B;AAgBD,wBAAgB,cAAc,IAAI,OAAO,eAAe,CAEvD;AAED,wBAAgB,UAAU,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,eAAe,CAMvE;AAED,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,gBAAgB,CASrE;AAED,wBAAgB,sBAAsB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAC,CAmBlF;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,76 @@
+/**
+ *    ▄▄▄▄
+ *  ▄█▀▀███▄▄              █▄
+ *  ██    ██ ▄             ██
+ *  ██    ██ ████▄▄█▀█▄ ▄████ ▄█▀█▄▀██ ██▀
+ *  ██  ▄ ██ ██   ██▄█▀ ██ ██ ██▄█▀  ███
+ *   ▀█████▄▄█▀  ▄▀█▄▄▄▄█▀███▄▀█▄▄▄▄██ ██▄
+ *        ▀█
+ *
+ *  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 { onMount } from 'svelte';
+import { readable } from 'svelte/store';
+import CoreQredexAgent from '@qredex/agent';
+const SERVER_STATE = {
+    hasIIT: false,
+    hasPIT: false,
+    iit: null,
+    pit: null,
+    cartState: 'unknown',
+    locked: false,
+    timestamp: 0,
+};
+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 useQredexAgent(config) {
+    onMount(() => {
+        initQredex(config);
+    });
+    return {
+        agent: CoreQredexAgent,
+        state: createQredexStateStore(config),
+    };
+}
+export function createQredexStateStore(config) {
+    return readable(SERVER_STATE, (set) => {
+        if (!canUseBrowser()) {
+            return () => undefined;
+        }
+        initQredex(config);
+        set(CoreQredexAgent.getState());
+        const handler = () => {
+            set(CoreQredexAgent.getState());
+        };
+        CoreQredexAgent.onStateChanged(handler);
+        return () => {
+            CoreQredexAgent.offStateChanged(handler);
+        };
+    });
+}
+/**
+ * @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,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AACjC,OAAO,EAAE,QAAQ,EAAiB,MAAM,cAAc,CAAC;AACvD,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,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,cAAc,CAAC,MAAoB;IACjD,OAAO,CAAC,GAAG,EAAE;QACX,UAAU,CAAC,MAAM,CAAC,CAAC;IACrB,CAAC,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,EAAE,eAAe;QACtB,KAAK,EAAE,sBAAsB,CAAC,MAAM,CAAC;KACtC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sBAAsB,CAAC,MAAoB;IACzD,OAAO,QAAQ,CAAc,YAAY,EAAE,CAAC,GAAG,EAAE,EAAE;QACjD,IAAI,CAAC,aAAa,EAAE,EAAE,CAAC;YACrB,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC;QACzB,CAAC;QAED,UAAU,CAAC,MAAM,CAAC,CAAC;QACnB,GAAG,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC,CAAC;QAEhC,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,GAAG,CAAC,eAAe,CAAC,QAAQ,EAAE,CAAC,CAAC;QAClC,CAAC,CAAC;QAEF,eAAe,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QAExC,OAAO,GAAG,EAAE;YACV,eAAe,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC;QAC3C,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,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/svelte",
+  "version": "1.0.0",
+  "description": "Svelte 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": {
+    "svelte": "^4.0.0 || ^5.0.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Qredex/qredex-agent.git",
+    "directory": "packages/svelte"
+  },
+  "homepage": "https://github.com/Qredex/qredex-agent/tree/main/packages/svelte#readme",
+  "bugs": {
+    "url": "https://github.com/Qredex/qredex-agent/issues"
+  }
+}