path-terminal-init 0.2.0

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "path-terminal-init",
+  "version": "0.2.0",
+  "description": "One-line setup for the Path Terminal SDK integration assistant — connects the user's AI agent to the Path MCP server and installs the per-OS integration recipe (iOS, Android, Windows). The single source of truth for the bootstrap CLI and the recipes.",
+  "bin": {
+    "path-terminal-init": "dist/cli.js"
+  },
+  "main": "dist/cli.js",
+  "scripts": {
+    "build": "node build.mjs",
+    "typecheck": "tsc --noEmit",
+    "dev": "ts-node src/cli.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "dist",
+    "rules"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/keyman12/Path-terminal-init.git"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "ora": "^8.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.5",
+    "esbuild": "^0.28.0",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "path",
+    "terminal",
+    "sdk",
+    "payment",
+    "mcp",
+    "cursor",
+    "claude",
+    "ios",
+    "android",
+    "windows",
+    "epos"
+  ]
+}

package/rules/android/path-integration-android.mdc

@@ -0,0 +1,325 @@
+---
+description: >
+  Rules for AI agents integrating the Path Terminal SDK into an Android EPOS
+  application. Apply when the user asks to integrate payments, connect to
+  a payment terminal, wire a sale or refund, or set up the Path emulator.
+globs:
+  - "**/*.kt"
+  - "**/AndroidManifest.xml"
+  - "**/settings.gradle.kts"
+  - "**/build.gradle.kts"
+alwaysApply: false
+---
+
+# Path Terminal SDK — Android Integration Rules
+
+You are integrating the Path Terminal SDK into an existing Android EPOS application.
+This app is a **developer EPOS system** that replicates a production environment.
+
+You have access to the Path MCP server at mcp.path2ai.tech:
+- Tools: `get_code_example` (use platform='android'), `validate_integration` (platform='android'),
+  `get_integration_checklist` (platform='android'), `explain_error`, `get_manifest_requirements`
+- Always call MCP tools before writing code. Never guess at SDK patterns.
+
+> **Check whether the SDK is already wired before doing anything else.**
+> Run:
+> ```
+> grep -r "path-terminal-sdk\|PathTerminal\|BLEPathTerminalAdapter" settings.gradle.kts app/build.gradle.kts 2>/dev/null | wc -l
+> ```
+> - **Count > 0** — SDK already present. Proceed directly to Step 1.
+> - **Count = 0** — SDK not yet added. Add the Gradle composite build first (Step 0).
+
+> **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` before doing
+> anything. If the path contains `.Trash`, `tmp`, or `worktree`, stop immediately.
+> Ask the developer to relaunch Claude Code from the correct project directory.
+
+---
+
+## Step 0 — Gradle setup (if SDK not yet installed)
+
+Call `get_code_example` with operation='install' and platform='android'.
+
+1. **settings.gradle.kts** — add below `include(":app")`:
+```kotlin
+includeBuild("../path-terminal-sdk-android") {
+    dependencySubstitution {
+        substitute(module("tech.path2ai.sdk:path-core-models")).using(project(":path-core-models"))
+        substitute(module("tech.path2ai.sdk:path-terminal-sdk")).using(project(":path-terminal-sdk"))
+        substitute(module("tech.path2ai.sdk:path-emulator-adapter")).using(project(":path-emulator-adapter"))
+        substitute(module("tech.path2ai.sdk:path-psdk-adapter")).using(project(":path-psdk-adapter"))
+        substitute(module("tech.path2ai.sdk:path-mock-adapter")).using(project(":path-mock-adapter"))
+        substitute(module("tech.path2ai.sdk:path-diagnostics")).using(project(":path-diagnostics"))
+    }
+}
+```
+
+2. **app/build.gradle.kts** — add to `dependencies {}`:
+```kotlin
+implementation("tech.path2ai.sdk:path-terminal-sdk:0.1.0")
+implementation("tech.path2ai.sdk:path-emulator-adapter:0.1.0")
+implementation("tech.path2ai.sdk:path-psdk-adapter:0.1.0")   // Verifone backend (Step 2c)
+```
+The Verifone (`path-psdk-adapter`) backend bundles the Verifone aar, which requires
+two extra build settings in the consuming app — call `get_code_example` with
+operation='verifone-init' and platform='android' for the exact lines:
+- register the SDK repo's `third-party/verifone/m2` maven repo **and** `https://jitpack.io`
+- enable `buildFeatures { dataBinding = true }`
+
+3. **AndroidManifest.xml** — call `get_manifest_requirements` for exact XML.
+
+The path-terminal-sdk-android repo must exist as a sibling directory:
+```
+android/
+├── path-terminal-sdk-android/   ← SDK (sibling)
+└── YourApp/                     ← this project
+```
+
+---
+
+## Your job — four steps, in this order
+
+---
+
+### Step 1 — Disconnect the existing terminal wiring
+
+Find the app entry point (Application class, MainActivity, or DI root) and **read the actual code**.
+
+Check what adapter is currently injected into the terminal manager. A comment saying
+*"replace with Path adapter"* does not mean it has been done — read the code.
+
+**You are looking for this pattern:**
+```kotlin
+// THIS is wired to Path — correct:
+terminalManager = TerminalManager(PathTerminalAdapter(this))
+
+// THIS is NOT wired to Path — fix it:
+terminalManager = TerminalManager(OCPayTerminalAdapter())
+terminalManager = TerminalManager() // default adapter
+```
+
+If the call does not use `PathTerminalAdapter` (or equivalent Path SDK adapter), change it.
+
+> **The adapter class must implement the existing `PaymentTerminalAdapter` interface.**
+> Do not rename or remove the interface — it is the integration contract.
+
+**Also disable any auto-connect on launch** — find calls to `.connect()` in
+`onCreate`, `init`, or `onResume` that fire automatically. Remove them.
+Path connects manually via Settings, not on launch.
+
+---
+
+### Step 2 — Add a backend switcher to Settings
+
+The purpose of this integration is: **prove the payment functions against the Path
+POS Emulator, then let the user switch — themselves, in the app — to a real Verifone
+terminal when ready.** Settings must let the user pick *which* terminal to connect to.
+Do NOT hardcode one transport.
+
+> **Connection details are entered by the user in the app, not by you.** You wire the
+> switcher, the IP field, and the credential storage, ship sensible test defaults, and
+> describe how to use it in your end-of-run summary (Step 4). You do NOT ask the user
+> for an IP or password during this run.
+
+Find the Settings screen (a Composable or Activity named Settings, Preferences, or
+similar). Add a **Path POS Adapter** section with a backend picker offering **three**:
+
+| Backend | Transport | Adapter | Needs |
+|---|---|---|---|
+| **Emulator (Wi-Fi)** — *default selection* | TCP/IP | `TcpPathTerminalAdapter(host = …)` | emulator IP |
+| **Emulator (Bluetooth)** | BLE | `BLEPathTerminalAdapter(context = …)` | scan + pick device |
+| **Verifone** | TCP/IP (PSDK) | `VerifonePSDKAdapter(context, config)` | terminal IP + stored login |
+
+Mirror the demo app's proven pattern — **call `get_code_example` with operation
+='backend-switch' and platform='android' first** and reproduce its `buildAdapter(backend)`
+shape. All sale / refund / void / receipt code is backend-agnostic; only adapter
+construction differs.
+
+**Persist the user's selection and connection details** in `SharedPreferences` behind a
+small settings type, with test defaults so a fresh clone connects without typing anything:
+```kotlin
+enum class TerminalBackend { EMULATOR_WIFI, EMULATOR_BLE, VERIFONE }   // default EMULATOR_WIFI
+// Stored keys: backend, emulator_host, verifone_host,
+//              login_username, login_password, login_shift, refund_password
+// Test defaults: verifone_host "192.168.1.88", username "user",
+//                password "password123", shift "shift123"
+```
+
+#### Step 2a — Emulator over Wi-Fi (the default) and Verifone — IP entry
+
+For the two IP-addressed backends, show a **host/IP text field** (label it "Emulator IP"
+or "Verifone terminal IP" depending on the selection) plus an **Apply & Connect** button.
+On connect, build the matching adapter from the stored host and rebuild `PathTerminal`
+(disconnect the previous adapter first — real terminals and the emulator's Wi-Fi mode
+allow only **one** client at a time). TCP and Verifone need no scan — `discoverDevices()`
+returns one synthetic device for the configured host, so "Apply & Connect" connects directly.
+
+#### Step 2b — Emulator over Bluetooth — scan and connect
+
+For the BLE backend keep the scan/connect flow:
+1. **Scan for Path Terminals** — triggers BLE discovery
+2. Discovered devices list — each with a **Connect** button
+3. Live connection state (Scanning / Connected / Disconnected)
+4. **Disconnect** when connected
+
+**Add to `PaymentTerminalAdapter` interface** (with no-op default implementations):
+```kotlin
+suspend fun scanForDevices(): List<TerminalDeviceInfo>
+suspend fun connectToDevice(id: String)
+```
+
+**Implement `PathTerminalAdapter`** — call `get_code_example` with operation='discover'
+and platform='android' first. The SDK exposes `DiscoveredDevice` with `.id` and `.name`
+properties — use them directly.
+
+**Expose on the ViewModel:**
+```kotlin
+private val _discoveredDevices = MutableStateFlow<List<TerminalDeviceInfo>>(emptyList())
+val discoveredDevices: StateFlow<List<TerminalDeviceInfo>> = _discoveredDevices.asStateFlow()
+
+private val _isScanning = MutableStateFlow(false)
+val isScanning: StateFlow<Boolean> = _isScanning.asStateFlow()
+
+fun scanForDevices() {
+    viewModelScope.launch {
+        _isScanning.value = true
+        _discoveredDevices.value = adapter.scanForDevices()
+        _isScanning.value = false
+    }
+}
+```
+
+#### Step 2c — Verifone backend and stored credentials
+
+The Verifone backend connects to a real terminal over the PSDK. Call `get_code_example`
+with operation='verifone-init' and platform='android' first. Construct it from a
+`VerifoneTerminalConfig` built from the **stored** login fields — never hardcode
+credentials inline:
+```kotlin
+import tech.path2ai.sdk.psdk.VerifonePSDKAdapter
+import tech.path2ai.sdk.psdk.VerifoneTerminalConfig
+
+val adapter = VerifonePSDKAdapter(
+    context = context,
+    config = VerifoneTerminalConfig(
+        host = settings.verifoneHost,
+        username = settings.loginUsername,
+        password = settings.loginPassword,
+        shift = settings.loginShift,
+        refundPassword = settings.refundPassword
+    )
+)
+```
+Keep the Verifone login fields **separate from the emulator settings** (their own stored
+keys, their own editable fields) — cleaner than reusing the emulator's. All terminals are
+treated as **generic Verifone** (same AGPA app, same PSDK connect/login), so no
+per-terminal configuration is needed beyond IP + login.
+
+---
+
+### Step 3 — Wire sale and refund through the Path SDK
+
+Call `get_code_example` with operation='sale' and platform='android'.
+Call `get_code_example` with operation='refund' and platform='android'.
+
+**Implement `PathTerminalAdapter.submitSale()`:**
+```kotlin
+override suspend fun submitSale(request: TerminalSaleRequest): TerminalSaleResponse {
+    val envelope = RequestEnvelope.create(sdkVersion = "0.1.0", adapterVersion = "0.1.0")
+    val sdkRequest = TransactionRequest.sale(
+        amountMinor = request.amountPence,
+        currency = request.currencyCode,
+        envelope = envelope
+    )
+    val result = terminal.sale(sdkRequest)
+    return when (result.state) {
+        TransactionState.APPROVED -> TerminalSaleResponse(
+            authorised = true,
+            authorisationCode = result.cardLastFour, // map fields as needed
+            terminalReference = result.transactionId
+        )
+        else -> TerminalSaleResponse(
+            authorised = false,
+            failureReason = result.error?.message ?: result.state.name
+        )
+    }
+}
+```
+
+**For refunds**, the success state is `TransactionState.REFUNDED` — **not** `APPROVED`.
+Using `APPROVED` in a refund check will never match.
+
+Call `validate_integration` with platform='android' on your code before finalising.
+
+---
+
+### Step 4 — Verify it works end to end
+
+1. Confirm the Application/MainActivity injects `PathTerminalAdapter` (not the old adapter).
+2. Confirm AndroidManifest.xml has BLUETOOTH_SCAN and BLUETOOTH_CONNECT permissions
+   (needed for the Bluetooth backend).
+3. **Prove on the emulator first (the default path — Wi-Fi/IP):**
+   - Put the Path POS Emulator in Wi-Fi mode (Config → Connection on the device);
+     it shows its `IP:port` on the welcome screen.
+   - Run the app → Settings → Payment Terminal → backend **Emulator (Wi-Fi)** → type
+     that IP → **Apply & Connect**. connectionState should reach Connected.
+   - (Optionally also prove **Emulator (Bluetooth)**: select it, **Scan**, **Connect**.)
+4. Add items to cart → Card payment → present a card / tap NFC tag on emulator when prompted.
+5. Verify:
+   - result.state == TransactionState.APPROVED (or result.isApproved == true)
+   - result.transactionId is non-null
+   - Receipt data populated via terminal.getReceiptData(transactionId)
+6. **Then prove the switch to Verifone:** select backend **Verifone**, enter the terminal's
+   IP and confirm the stored login, **Apply & Connect** — the SDK runs the PSDK init + login
+   and the same sale/refund/void flow runs against the real terminal, unchanged. (Only one
+   client may connect to a Verifone terminal at a time — disconnect any other POS first.)
+
+---
+
+## SDK rules — always follow these
+
+**ALWAYS:**
+- Call `get_code_example` with platform='android' before writing any SDK code
+- Use `TransactionRequest.sale(...)` and `TransactionRequest.refund(...)` factory methods
+- Use `RequestEnvelope.create(sdkVersion, adapterVersion)` — never build manually
+- Handle TransactionState: APPROVED, DECLINED, TIMED_OUT, FAILED, CANCELLED
+- For **refunds**, success state is `REFUNDED` — not `APPROVED`
+- Catch `PathError` and check `.recoverable`
+- Call `validate_integration` with platform='android' before presenting code
+- Call from coroutines — `terminal.sale()` and `terminal.refund()` are `suspend` functions
+
+**NEVER:**
+- Use the raw `TransactionRequest(...)` constructor — always use factory methods
+- Store or log card data (cardLastFour is acceptable, nothing else)
+- Retry a financial operation without a new `RequestEnvelope` (new idempotencyKey)
+- Leave the existing default adapter in place — Path must be injected
+- Leave auto-connect-on-launch running
+- Skip `PathError` handling
+- Call blocking I/O from the main thread — all SDK calls are suspend functions
+- Wrap `terminal.sale()` in a timeout shorter than 30 seconds
+
+**AMOUNTS:** Minor currency units (pence/cents) only as integers.
+- `100` = £1.00 GBP · `1250` = £12.50 GBP · Never pass decimals.
+
+**COROUTINES:** All SDK methods are `suspend`. Always call from `viewModelScope.launch { }` or equivalent.
+
+---
+
+## After making changes
+
+Summarise:
+- Each file modified and the specific change made
+- Confirm Step 1 (adapter injection) was completed
+
+Then give **tailored connect instructions** — the user enters the connection details
+themselves, so tell them exactly where you wired things in:
+- The Settings screen / section name you added the backend switcher to
+- How to connect to the emulator over **Wi-Fi/IP** (the default): which backend to pick,
+  where to type the emulator's IP, which button connects
+- How to also connect over **Bluetooth** if they prefer (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 be able to follow it without reading code.