@achyutlabsau/vue-payment-gateway 1.0.0-alpha.2 → 1.0.0-alpha.4

package/README.md

@@ -1,193 +1,193 @@
-# Vue Payment Gateway
-
-**@achyutlabsau/vue-payment-gateway** is a Vue 3 library that provides unified integration with multiple payment
-terminal providers — in-store EFTPOS terminals and cloud-based payment APIs — behind a small, consistent Vue
-composable API per provider.
-
-Full documentation, including a step-by-step guide, install options reference, and per-gateway details, lives in the
-[docs site](https://achyut-labs.github.io/al-pay-npm-pkg/) (or run `npm run docs:dev` locally). This README is a
-quick-reference summary.
-
-## Supported Providers
-
-| Provider            | Type                     | Composable / Entry                 |
-| ------------------- | ------------------------ | ---------------------------------- |
-| **Tyro**            | In-store EFTPOS (iframe) | `useTyro` (`/tyro`)                |
-| **Linkly**          | In-store (Linkly Cloud)  | `useLinkly` (`/linkly`)            |
-| **SmartPay**        | In-store (cloud polling) | `useSmartPay` (`/smartpay`)        |
-| **Till Payments**   | In-store (REST intents)  | `useTillPayment` (`/till-payment`) |
-| **MX51 SPI**        | In-store (SPI, events)   | `useMX51` (`/mx51`)                |
-| **ANZ (Worldline)** | In-store (TimAPI / WASM) | `useAnz` (`/anz`)                  |
-| **Valpay (Adyen)**  | Cloud Terminal API       | `useValpay` (`/valpay`)            |
-
-## Installation
-
-```bash
-npm install @achyutlabsau/vue-payment-gateway
-```
-
-Peer dependencies your app must also install: `@vueuse/core`, `@vueuse/rxjs`, `axios`, `dayjs`, `dexie`, `quasar`,
-`uuid`, `vue`. See [Installation](docs/installation.md) for versions and full setup.
-
-## Plugin Initialization
-
-```ts
-import { createApp } from "vue";
-import VuePaymentGateway from "@achyutlabsau/vue-payment-gateway";
-
-const app = createApp(App);
-
-app.use(VuePaymentGateway, {
-  currencyCode: "AUD",
-  productName: "Pratham Respos", // Name of your product
-  productVersion: "3.3.0", // Version of your product
-  productVendorName: "Achyutlabs", // Name of the product vendor
-  posId: "unique-pos-id", // Unique identifier for the POS system
-  posRegisterId: "pos-register-id", // Unique identifier for the POS register
-  posRegisterName: "register-name", // Name of the POS register
-  posBusinessName: "business name", // Name of the business using the POS system
-  tyroApiKey: "tyro-api-key", // API key for Tyro integration
-  environment: "development", // "development" | "production"
-  onReceiptPrint: (receipt, type) => {
-    // MX51 SPI only; other providers return receipts on the result — see docs/features/receipts.md
-  },
-});
-
-app.mount("#app");
-```
-
-> Only set the credentials for the providers you actually use — see the [Install Options Reference](docs/installation.md#install-options-reference).
-
-## Using the Payment Gateway
-
-Provider composables are **not** identical — method names mirror each vendor's own terminology rather than being
-forced into one generic shape, because the underlying protocols differ (event-driven SPI vs. cloud polling vs. an
-iframe SDK). SmartPay, Till Payments, Valpay and ANZ have converged on a shared `PaymentTerminal`
-contract (`pair` / `unpair` / `isPaired` / `purchase` / `refund`); Tyro, Linkly and MX51 still expose their own
-surface. See [Transaction Processing](docs/features/transactions.md) for the full per-provider reference, and
-[migration-v1.md](docs/migration-v1.md) if you're upgrading from a pre-1.0 release.
-
-### SmartPay, Till Payments, Valpay (shared contract)
-
-```ts
-import { useSmartPay } from "@achyutlabsau/vue-payment-gateway/smartpay";
-
-const smartpay = useSmartPay();
-
-await smartpay.pair({ pairingCode: "123456" });
-smartpay.isPaired(); // boolean
-
-const res = await smartpay.purchase(1000); // $10.00, amounts are in cents
-// res.success, res.status, res.amount, res.tipAmount, res.maskedCard, res.cardScheme, res.receipts
-
-await smartpay.refund(1000);
-smartpay.unpair();
-```
-
-`useTillPayment()` and `useValpay()` follow the same `pair`/`unpair`/`isPaired`/`purchase`/`refund` shape and both
-resolve with the same `PaymentResult`. Till and Valpay additionally support **referenced (linked) refunds** via
-`refund(cents, { originalTransactionId })`.
-
-### Tyro
-
-```ts
-import { useTyro } from "@achyutlabsau/vue-payment-gateway/tyro";
-
-const tyro = useTyro();
-
-await tyro.pairTyro(merchantId, terminalId);
-
-const res = await tyro.initiateTyroPurchase({ integratedReceipt: true, amount: "1000" }, receiptCallback);
-// res.result is a TyroTransactionStatus, e.g. "APPROVED"
-
-await tyro.initiateTyroRefund({ integratedReceipt: true, amount: "1000" }, receiptCallback);
-```
-
-### Linkly
-
-```ts
-import { useLinkly, ReceiptAutoPrint } from "@achyutlabsau/vue-payment-gateway/linkly";
-
-const linkly = useLinkly();
-
-await linkly.pairPinpad({ username, password, pairCode: "123456" });
-
-const res = await linkly.initiatePurchase({
-  AmtPurchase: 1000,
-  ReceiptAutoPrint: ReceiptAutoPrint.ReturnToPOS,
-});
-
-// Referenced (linked) refund — pass the original purchase's RFN:
-await linkly.initiateRefund({
-  AmtPurchase: 1000,
-  ReceiptAutoPrint: ReceiptAutoPrint.ReturnToPOS,
-  referenceNumber: rfn,
-});
-```
-
-### MX51 SPI
-
-MX51 is event-driven: `initiatePurchase`/`initiateRefund` start the flow but resolve with `void`. Subscribe to the
-`TxFlowStateChanged` document event (or use the bundled `TransactionDialog`) to observe the outcome. See
-[Transaction Processing](docs/features/transactions.md#mx51-spi).
-
-### ANZ (Worldline)
-
-ANZ implements the shared contract plus `settle()` for the daily closing. Worldline's TimAPI SDK ships with the
-package — pass it through the `anz` install option (see [ANZ](docs/gateways/anz.md#setup)):
-
-```ts
-import { useAnz } from "@achyutlabsau/vue-payment-gateway/anz";
-
-const anz = useAnz();
-const res = await anz.purchase(1000); // cents → PaymentResult
-await anz.refund(1000); // unreferenced (standalone) refund
-await anz.refund(0, { originalTransactionId: res.transactionId! }); // referenced (linked) refund
-await anz.settle(); // daily closing
-```
-
-## Checking Pairing Status
-
-```ts
-import { isPaymentGatewayConnected, PaymentGateways } from "@achyutlabsau/vue-payment-gateway";
-
-isPaymentGatewayConnected(PaymentGateways.Linkly); // reads linkly.pairConfig from localStorage
-```
-
-## Logging
-
-Every provider logs through one shared, IndexedDB-backed logger (`./logger` subpath) — persistent across reloads,
-attributable to a gateway, correlated by transaction, and with secrets/PANs redacted centrally. See
-[Logging](docs/features/logging.md) for configuration, the `LogViewer` component, and how to query/export logs.
-
-## Shared Utilities
-
-```ts
-import {
-  toCents,
-  toMajorUnits,
-  formatCents,
-  maskPan,
-  normalizeCardScheme,
-  CardScheme,
-} from "@achyutlabsau/vue-payment-gateway/utils";
-```
-
-Available from the root entry too, alongside `generateTransactionId()`, `setState()`, and `setCurrencyCode()`.
-
-## Troubleshooting
-
-- **"Plugin not initialized" errors** — provider composables throw if called before `app.use(VuePaymentGateway, …)`
-  has run. Call `use*` inside components/handlers, not at module load time.
-- **Environment issues** — make sure `environment` is set correctly (`"development"` or `"production"`); it selects
-  each provider's SDK/endpoint URLs.
-- **Invalid API key** — confirm the provider's API key/merchant credentials are set in the plugin options.
-- **Diagnosing a failed transaction** — check the [Logging](docs/features/logging.md) guide; every gateway's request,
-  response and retry history is queryable through `logger.query()` or the `LogViewer` component.
-
-## Additional Resources
-
-- [Full documentation](docs/index.md)
-- [Changelog](CHANGELOG.md)
-- [Migration guide (pre-1.0 → v1)](docs/migration-v1.md)
-- [Achyutlabs](https://achyutlabs.com/)
+# Vue Payment Gateway
+
+**@achyutlabsau/vue-payment-gateway** is a Vue 3 library that provides unified integration with multiple payment
+terminal providers — in-store EFTPOS terminals and cloud-based payment APIs — behind a small, consistent Vue
+composable API per provider.
+
+Full documentation, including a step-by-step guide, install options reference, and per-gateway details, lives in the
+[docs site](https://achyut-labs.github.io/al-pay-npm-pkg/) (or run `npm run docs:dev` locally). This README is a
+quick-reference summary.
+
+## Supported Providers
+
+| Provider            | Type                     | Composable / Entry                 |
+| ------------------- | ------------------------ | ---------------------------------- |
+| **Tyro**            | In-store EFTPOS (iframe) | `useTyro` (`/tyro`)                |
+| **Linkly**          | In-store (Linkly Cloud)  | `useLinkly` (`/linkly`)            |
+| **SmartPay**        | In-store (cloud polling) | `useSmartPay` (`/smartpay`)        |
+| **Till Payments**   | In-store (REST intents)  | `useTillPayment` (`/till-payment`) |
+| **MX51 SPI**        | In-store (SPI, events)   | `useMX51` (`/mx51`)                |
+| **ANZ (Worldline)** | In-store (TimAPI / WASM) | `useAnz` (`/anz`)                  |
+| **Valpay (Adyen)**  | Cloud Terminal API       | `useValpay` (`/valpay`)            |
+
+## Installation
+
+```bash
+npm install @achyutlabsau/vue-payment-gateway
+```
+
+Peer dependencies your app must also install: `@vueuse/core`, `axios`, `dayjs`, `dexie`, `quasar`,
+`uuid`, `vue`. See [Installation](docs/installation.md) for versions and full setup.
+
+## Plugin Initialization
+
+```ts
+import { createApp } from "vue";
+import VuePaymentGateway from "@achyutlabsau/vue-payment-gateway";
+
+const app = createApp(App);
+
+app.use(VuePaymentGateway, {
+  currencyCode: "AUD",
+  productName: "Pratham Respos", // Name of your product
+  productVersion: "3.3.0", // Version of your product
+  productVendorName: "Achyutlabs", // Name of the product vendor
+  posId: "unique-pos-id", // Unique identifier for the POS system
+  posRegisterId: "pos-register-id", // Unique identifier for the POS register
+  posRegisterName: "register-name", // Name of the POS register
+  posBusinessName: "business name", // Name of the business using the POS system
+  tyroApiKey: "tyro-api-key", // API key for Tyro integration
+  environment: "development", // "development" | "production"
+  onReceiptPrint: (receipt, type) => {
+    // MX51 SPI only; other providers return receipts on the result — see docs/features/receipts.md
+  },
+});
+
+app.mount("#app");
+```
+
+> Only set the credentials for the providers you actually use — see the [Install Options Reference](docs/installation.md#install-options-reference).
+
+## Using the Payment Gateway
+
+Provider composables are **not** identical — method names mirror each vendor's own terminology rather than being
+forced into one generic shape, because the underlying protocols differ (event-driven SPI vs. cloud polling vs. an
+iframe SDK). SmartPay, Till Payments, Valpay and ANZ have converged on a shared `PaymentTerminal`
+contract (`pair` / `unpair` / `isPaired` / `purchase` / `refund`); Tyro, Linkly and MX51 still expose their own
+surface. See [Transaction Processing](docs/features/transactions.md) for the full per-provider reference, and
+[migration-v1.md](docs/migration-v1.md) if you're upgrading from a pre-1.0 release.
+
+### SmartPay, Till Payments, Valpay (shared contract)
+
+```ts
+import { useSmartPay } from "@achyutlabsau/vue-payment-gateway/smartpay";
+
+const smartpay = useSmartPay();
+
+await smartpay.pair({ pairingCode: "123456" });
+smartpay.isPaired(); // boolean
+
+const res = await smartpay.purchase(1000); // $10.00, amounts are in cents
+// res.success, res.status, res.amount, res.tipAmount, res.maskedCard, res.cardScheme, res.receipts
+
+await smartpay.refund(1000);
+smartpay.unpair();
+```
+
+`useTillPayment()` and `useValpay()` follow the same `pair`/`unpair`/`isPaired`/`purchase`/`refund` shape and both
+resolve with the same `PaymentResult`. Till and Valpay additionally support **referenced (linked) refunds** via
+`refund(cents, { originalTransactionId })`.
+
+### Tyro
+
+```ts
+import { useTyro } from "@achyutlabsau/vue-payment-gateway/tyro";
+
+const tyro = useTyro();
+
+await tyro.pairTyro(merchantId, terminalId);
+
+const res = await tyro.initiateTyroPurchase({ integratedReceipt: true, amount: "1000" }, receiptCallback);
+// res.result is a TyroTransactionStatus, e.g. "APPROVED"
+
+await tyro.initiateTyroRefund({ integratedReceipt: true, amount: "1000" }, receiptCallback);
+```
+
+### Linkly
+
+```ts
+import { useLinkly, ReceiptAutoPrint } from "@achyutlabsau/vue-payment-gateway/linkly";
+
+const linkly = useLinkly();
+
+await linkly.pairPinpad({ username, password, pairCode: "123456" });
+
+const res = await linkly.initiatePurchase({
+  AmtPurchase: 1000,
+  ReceiptAutoPrint: ReceiptAutoPrint.ReturnToPOS,
+});
+
+// Referenced (linked) refund — pass the original purchase's RFN:
+await linkly.initiateRefund({
+  AmtPurchase: 1000,
+  ReceiptAutoPrint: ReceiptAutoPrint.ReturnToPOS,
+  referenceNumber: rfn,
+});
+```
+
+### MX51 SPI
+
+MX51 is event-driven: `initiatePurchase`/`initiateRefund` start the flow but resolve with `void`. Subscribe to the
+`TxFlowStateChanged` document event (or use the bundled `TransactionDialog`) to observe the outcome. See
+[Transaction Processing](docs/features/transactions.md#mx51-spi).
+
+### ANZ (Worldline)
+
+ANZ implements the shared contract plus `settle()` for the daily closing. Worldline's TimAPI SDK ships with the
+package — pass it through the `anz` install option (see [ANZ](docs/gateways/anz.md#setup)):
+
+```ts
+import { useAnz } from "@achyutlabsau/vue-payment-gateway/anz";
+
+const anz = useAnz();
+const res = await anz.purchase(1000); // cents → PaymentResult
+await anz.refund(1000); // unreferenced (standalone) refund
+await anz.refund(0, { originalTransactionId: res.transactionId! }); // referenced (linked) refund
+await anz.settle(); // daily closing
+```
+
+## Checking Pairing Status
+
+```ts
+import { isPaymentGatewayConnected, PaymentGateways } from "@achyutlabsau/vue-payment-gateway";
+
+isPaymentGatewayConnected(PaymentGateways.Linkly); // reads linkly.pairConfig from localStorage
+```
+
+## Logging
+
+Every provider logs through one shared, IndexedDB-backed logger (`./logger` subpath) — persistent across reloads,
+attributable to a gateway, correlated by transaction, and with secrets/PANs redacted centrally. See
+[Logging](docs/features/logging.md) for configuration, the `LogViewer` component, and how to query/export logs.
+
+## Shared Utilities
+
+```ts
+import {
+  toCents,
+  toMajorUnits,
+  formatCents,
+  maskPan,
+  normalizeCardScheme,
+  CardScheme,
+} from "@achyutlabsau/vue-payment-gateway/utils";
+```
+
+Available from the root entry too, alongside `generateTransactionId()`, `setState()`, and `setCurrencyCode()`.
+
+## Troubleshooting
+
+- **"Plugin not initialized" errors** — provider composables throw if called before `app.use(VuePaymentGateway, …)`
+  has run. Call `use*` inside components/handlers, not at module load time.
+- **Environment issues** — make sure `environment` is set correctly (`"development"` or `"production"`); it selects
+  each provider's SDK/endpoint URLs.
+- **Invalid API key** — confirm the provider's API key/merchant credentials are set in the plugin options.
+- **Diagnosing a failed transaction** — check the [Logging](docs/features/logging.md) guide; every gateway's request,
+  response and retry history is queryable through `logger.query()` or the `LogViewer` component.
+
+## Additional Resources
+
+- [Full documentation](docs/index.md)
+- [Changelog](CHANGELOG.md)
+- [Migration guide (pre-1.0 → v1)](docs/migration-v1.md)
+- [Achyutlabs](https://achyutlabs.com/)

package/dist/{PairInstructions-CDzvPsSD.js → PairInstructions-Cfz0eDzz.js}

@@ -1,4 +1,4 @@
-import { _ as e, d as t, g as n, l as r, p as i, r as a, u as o } from "./logger-C4IV3krr.js";
+import { _ as e, d as t, f as n, m as r, r as i, u as a, v as o } from "./logger-4FM6sy9j.js";
 import { createBlock as s, createElementVNode as c, createTextVNode as l, createVNode as u, defineComponent as d, openBlock as f, unref as p, withCtx as m } from "vue";
 //#region src/components/PairInstructions.vue?vue&type=script&setup=true&lang.ts
 var h = { class: "gap-4 flex flex-nowrap items-start" }, g = {
@@ -9,22 +9,22 @@ var h = { class: "gap-4 flex flex-nowrap items-start" }, g = {
 	props: { steps: {} },
 	emits: ["next"],
 	setup(d) {
-		return (_, v) => (f(), s(p(r), null, {
-			footer: m(() => [u(p(t), {
+		return (_, v) => (f(), s(p(a), null, {
+			footer: m(() => [u(p(n), {
 				label: "Continue",
-				"icon-right": p(n),
+				"icon-right": p(e),
 				onClick: v[0] ||= (e) => _.$emit("next")
 			}, null, 8, ["icon-right"])]),
 			default: m(() => [
-				c("div", h, [c("span", g, [u(p(i), {
-					name: p(e),
+				c("div", h, [c("span", g, [u(p(r), {
+					name: p(o),
 					size: 26
 				}, null, 8, ["name"])]), v[1] ||= c("div", { class: "min-w-0" }, [c("h2", { class: "text-lg font-semibold text-gray-900 dark:text-white" }, "Terminal setup"), c("p", { class: "mt-0.5 text-sm text-gray-500 dark:text-gray-400" }, " Follow these steps on the terminal, then continue to enter its details. ")], -1)]),
-				u(p(a), {
+				u(p(i), {
 					steps: d.steps,
 					class: "mt-5"
 				}, null, 8, ["steps"]),
-				u(p(o), {
+				u(p(t), {
 					tone: "warning",
 					title: "Before you start",
 					class: "mt-5"

package/dist/{PairedTerminal-Bbbce0Z-.js → PairedTerminal-CqM7haJt.js}

@@ -1,4 +1,4 @@
-import { f as e, i as t, l as n } from "./logger-C4IV3krr.js";
+import { i as e, p as t, u as n } from "./logger-4FM6sy9j.js";
 import { Fragment as r, computed as i, createBlock as a, createCommentVNode as o, createElementBlock as s, createElementVNode as c, createVNode as l, defineComponent as u, openBlock as d, renderList as f, renderSlot as p, toDisplayString as m, unref as h, withCtx as g } from "vue";
 //#region src/components/PairedTerminal.vue?vue&type=script&setup=true&lang.ts
 var _ = { class: "gap-4 flex flex-nowrap items-start" }, v = { class: "min-w-0 flex-1" }, y = { class: "gap-2 flex flex-wrap items-center" }, b = { class: "text-lg font-semibold text-gray-900 dark:text-white" }, x = {
@@ -33,11 +33,11 @@ var _ = { class: "gap-4 flex flex-nowrap items-start" }, v = { class: "min-w-0 f
 			}), e;
 		});
 		return (i, E) => (d(), a(h(n), null, {
-			default: g(() => [c("div", _, [l(h(t), {
+			default: g(() => [c("div", _, [l(h(e), {
 				status: "success",
 				size: "lg"
 			}), c("div", v, [
-				c("div", y, [c("h2", b, m(u.title), 1), l(h(e), {
+				c("div", y, [c("h2", b, m(u.title), 1), l(h(t), {
 					tone: "success",
 					dot: "",
 					label: "Paired"