path-terminal-init 0.2.0

package/rules/windows-11/path-integration-windows11.mdc

@@ -0,0 +1,230 @@
+---
+description: >
+  Rules for AI agents integrating the Path Terminal SDK into a Windows 11 EPOS
+  application — the modern WinUI 3 / .NET 10 stack. Apply when the user asks to
+  integrate payments, connect to a payment terminal, wire a sale or refund, or
+  set up the Path emulator on a WinUI 3 app. For the legacy WPF / .NET Framework
+  4.8 stack use path-integration-windows10.mdc instead.
+globs:
+  - "**/*.cs"
+  - "**/*.csproj"
+  - "**/*.xaml"
+  - "**/Package.appxmanifest"
+alwaysApply: false
+---
+
+# Path Terminal SDK — Windows 11 (WinUI 3 / .NET 10) Integration Rules
+
+You are integrating the Path Terminal SDK into an existing **WinUI 3 / .NET 10**
+Windows EPOS application. This app is a **developer EPOS system** that replicates a
+production environment.
+
+> **Which recipe am I in?** This is the **Windows 11** recipe — modern WinUI 3,
+> `net10.0-windows`. If the project is WPF / `net48` (a `<UseWPF>true` csproj
+> targeting .NET Framework 4.8), STOP and use `path-integration-windows10.mdc`
+> instead. The two stacks differ in app shell, UI threading, and settings storage.
+
+You have access to the Path MCP server at mcp.path2ai.tech:
+- Tools: `get_code_example` (use platform='windows'), `explain_error`. Always call
+  `get_code_example` before writing SDK code — never guess at SDK patterns.
+
+> **Language override.** Never write "Pico W" in any output or code comment.
+> Always use "Path POS Emulator" when referring to the physical device.
+
+> **Confirm the correct project directory first.** Run `pwd` (or `Get-Location`)
+> before anything. If the path contains `.Trash`, `tmp`, or `worktree`, stop — ask
+> the developer to relaunch from the real project directory.
+
+---
+
+## The purpose of this integration
+
+Wire the SDK so the user can **prove the payment functions against the Path POS
+Emulator, then switch — themselves, in the app — to a real Verifone terminal when
+ready.** So Settings gets a **backend switcher**, not one hardcoded transport.
+
+> **You wire the capability; the user enters the connection details.** You build the
+> switcher, the IP field, and the credential storage, and ship sensible test
+> defaults. You do NOT ask the user for an IP or password during this run — you
+> describe how to use the screen in your end-of-run summary (Step 4).
+
+The Windows 11 **demo app** (`Path-epos-demo-sdk-Windows11`) already implements this
+exact pattern — its `SdkTerminalManager.BuildTerminal()` is the reference. Mirror it.
+
+---
+
+## Step 0 — Reference the SDK (sibling-folder ProjectReference)
+
+The SDK is consumed by relative `ProjectReference`, and the SDK repo must be cloned as
+a **sibling** of this app (e.g. `..\..\..\Path-terminal-sdk-windows11`). Call
+`get_code_example` with operation='install' and platform='windows'. Add these six
+references to the app's `.csproj` (adjust the `..\` depth to your project's location):
+
+```xml
+<ItemGroup>
+  <ProjectReference Include="..\..\..\Path-terminal-sdk-windows11\Path.Terminal.CoreModels\Path.Terminal.CoreModels.csproj" />
+  <ProjectReference Include="..\..\..\Path-terminal-sdk-windows11\Path.Terminal.Sdk\Path.Terminal.Sdk.csproj" />
+  <ProjectReference Include="..\..\..\Path-terminal-sdk-windows11\Path.Terminal.EmulatorAdapter\Path.Terminal.EmulatorAdapter.csproj" />
+  <ProjectReference Include="..\..\..\Path-terminal-sdk-windows11\Path.Terminal.MockAdapter\Path.Terminal.MockAdapter.csproj" />
+  <ProjectReference Include="..\..\..\Path-terminal-sdk-windows11\Path.Terminal.Diagnostics\Path.Terminal.Diagnostics.csproj" />
+  <!-- Verifone backend (Step 2c) — bundles the Verifone .NET binding. -->
+  <ProjectReference Include="..\..\..\Path-terminal-sdk-windows11\Path.Terminal.PsdkAdapter\Path.Terminal.PsdkAdapter.csproj" />
+</ItemGroup>
+```
+
+> **Bluetooth needs no manifest entry here.** The harness is an *unpackaged* WinUI 3
+> app (`WindowsPackageType=None`), so BLE comes through the WinRT projections the
+> EmulatorAdapter already uses — there is no `Package.appxmanifest` capability to add.
+
+---
+
+## Your job — four steps, in this order
+
+---
+
+### Step 1 — Disconnect the existing loopback wiring
+
+The harness ships with a **loopback** adapter, `OCPayTerminalAdapter`, composed at the
+app root (look in `App.xaml.cs` / `Services/AppServices.cs` for where the terminal
+manager is built). **Read the actual code** — a comment is not proof.
+
+Create a Path-backed terminal manager that builds `PathTerminal` from the selected
+backend (mirror the demo's `SdkTerminalManager.BuildTerminal()`), and swap the app
+composition to use it instead of the OCPay manager.
+
+> Keep `OCPayTerminalAdapter` in the codebase (it is the shipped loopback default) —
+> just stop composing it as the live adapter. Do not delete it.
+
+**Also disable any auto-connect on launch** — the Path backends connect manually from
+Settings, never automatically on start.
+
+---
+
+### Step 2 — Add a backend switcher to Settings
+
+The harness already has a Settings page (look for `SettingsPage` / `SettingsViewModel`).
+Add a **Path POS Adapter** section with a backend picker offering **three** backends.
+**Call `get_code_example` with operation='backend-switch' and platform='windows' first**
+and reproduce its `BuildTerminal` shape exactly:
+
+| Backend | Transport | Adapter | Needs |
+|---|---|---|---|
+| **Emulator (Wi-Fi)** — *default* | TCP/IP | `new TcpPathTerminalAdapter(host, …)` | emulator IP |
+| **Emulator (Bluetooth)** | BLE | `new BlePathTerminalAdapter(…)` | scan + connect |
+| **Verifone** | TCP/IP (PSDK) | `new VerifonePsdkAdapter(config, …)` | terminal IP + stored login |
+
+```csharp
+public enum TerminalBackend { EmulatorWifi, EmulatorBle, Verifone }   // EmulatorWifi = default
+```
+
+**Persist the selection and connection details** in the harness's settings store (the
+demo uses a small `AppSettings` class writing JSON to
+`%LOCALAPPDATA%\<App>\app.json`). Store: `Backend`, `EmulatorHost`, `VerifoneHost`,
+`LoginUsername`, `LoginPassword`, `LoginShift`, `RefundPassword` — with test defaults
+(`VerifoneHost` "192.168.1.88", username "user", password "password123", shift
+"shift123") so a fresh clone connects without typing.
+
+#### Step 2a — Emulator (Wi-Fi, the default) and Verifone — IP entry
+
+For the two IP-addressed backends show a **host/IP text box** (label "Emulator IP" or
+"Verifone terminal IP" by selection) and an **Apply & Connect** button. On connect,
+build the matching adapter from the stored host, dispose the previous `PathTerminal`,
+and build a new one (only **one** client per terminal / per emulator Wi-Fi session).
+TCP and Verifone need no scan — `DiscoverDevicesAsync()` returns one synthetic device
+for the host, so Apply & Connect connects directly.
+
+#### Step 2b — Emulator (Bluetooth) — scan and connect
+
+For the BLE backend keep a scan/connect flow: a **Scan** button → `DiscoverDevicesAsync()`
+→ list devices → **Connect** → live connection state from the `Events` stream.
+Marshal UI updates onto the WinUI UI thread (`DispatcherQueue.TryEnqueue`).
+
+#### Step 2c — Verifone backend and stored credentials
+
+Call `get_code_example` with operation='verifone-init' and platform='windows'.
+Construct it from a `VerifoneTerminalConfig` built from the **stored** login — never
+hardcode credentials inline:
+```csharp
+using Path.Terminal.PsdkAdapter;
+var adapter = new VerifonePsdkAdapter(
+    new VerifoneTerminalConfig {
+        Host = settings.VerifoneHost,
+        Username = settings.LoginUsername,
+        Password = settings.LoginPassword,
+        Shift = settings.LoginShift,
+        RefundPassword = settings.RefundPassword,
+    },
+    log: Log);
+```
+Keep the Verifone login fields **separate** (their own stored keys + editable fields).
+All terminals are treated as **generic Verifone** (same AGPA app, same PSDK
+connect/login) — no per-terminal config beyond IP + login.
+
+---
+
+### Step 3 — Wire sale, refund and void through the Path SDK
+
+Once Step 1 is done, the harness's existing payment flow calls the Path-backed manager.
+Confirm the transaction methods map correctly:
+- Call `get_code_example` operation='sale' (platform='windows') — handle `TransactionState.Approved`, `Declined`, `TimedOut`, `Failed`, default.
+- Call `get_code_example` operation='refund' — pass `originalTransactionId` from the sale result.
+- Call `get_code_example` operation='void' — full reversal; success state is `Reversed`.
+- Amounts are **minor units** (`420` = £4.20). Never pass decimals.
+- Catch `PathException` and check whether it is recoverable before retrying.
+
+---
+
+### Step 4 — Verify it works end to end
+
+1. Confirm the app root composes the Path-backed manager, not `OCPayTerminalAdapter`.
+2. **Prove on the emulator first (the default — Wi-Fi/IP):**
+   - Put the Path POS Emulator in Wi-Fi mode (Config → Connection); note the `IP:port`
+     on its welcome screen.
+   - Run the app → Settings → Path POS Adapter → **Emulator (Wi-Fi)** → type that IP →
+     **Apply & Connect**. Connection state should reach Connected.
+   - (Optionally prove **Emulator (Bluetooth)**: select it, **Scan**, **Connect**.)
+3. Run a sale (amountMinor `100` = £1.00), present a card / tap the emulator's NFC tag,
+   verify `result.State == Approved`, `TransactionId` is non-null, and receipt data is
+   populated (`get_code_example` operation='receipt'). Run a refund and a void.
+4. **Then prove the switch to Verifone:** select **Verifone**, enter the terminal IP and
+   confirm the stored login, **Apply & Connect** — the SDK runs the PSDK init + login and
+   the same flow runs against the real terminal, unchanged. One client per terminal —
+   disconnect any other POS first.
+
+---
+
+## SDK rules — always follow these
+
+**ALWAYS:**
+- Call `get_code_example` (platform='windows') before writing SDK code
+- Use `TransactionRequest.Sale(...)` / `.Refund(...)` / `.Void(...)` factory methods
+- Use `RequestEnvelope.Create(...)` — never build envelopes by hand
+- For **refunds** the success state is the refunded/approved state, and for **voids** it is `Reversed` — not the sale's `Approved`
+- Dispose the old `PathTerminal` before building a new one on a backend change
+- Marshal UI updates from `Events` onto the WinUI UI thread (`DispatcherQueue.TryEnqueue`)
+
+**NEVER:**
+- Use a raw `TransactionRequest` constructor — use the factory methods
+- Store or log card data (masked PAN only)
+- Retry a financial operation without a fresh `RequestEnvelope` (new idempotency key)
+- Leave `OCPayTerminalAdapter` composed as the live adapter — Path must be the live one
+- Leave auto-connect-on-launch running
+- Set `OnCardRead` / `OnAck` on an adapter — `PathTerminal` owns those
+- Write "Pico W" anywhere
+
+---
+
+## After making changes
+
+Summarise each file changed and confirm Step 1 (the live adapter is now Path-backed).
+
+Then give **tailored connect instructions** — the user enters the connection details, so
+tell them exactly where you wired things in:
+- The Settings section you added the backend switcher to
+- How to connect to the emulator over **Wi-Fi/IP** (the default): which backend, where to
+  type the emulator's IP, which button connects
+- How to connect over **Bluetooth** instead (Scan → Connect)
+- How to **switch to Verifone** when ready: pick Verifone, enter the terminal IP, confirm
+  the stored login, connect
+
+Keep it brief and concrete — the user should follow it without reading code.