path-terminal-init 0.2.8 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "path-terminal-init",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "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"

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

@@ -151,11 +151,28 @@ returns one synthetic device for the configured host, so "Apply & Connect" conne
 
 #### Step 2b — Emulator over Bluetooth — scan and connect
 
+> **⚠ Runtime permissions are MANDATORY — this is the #1 reason Bluetooth silently
+> fails.** Declaring `BLUETOOTH_SCAN` / `BLUETOOTH_CONNECT` in the manifest is **not
+> enough** on Android 12+ (API 31). You must **request them at runtime** before the
+> first scan, or `discoverDevices()` finds nothing / throws and the user sees an empty
+> list with no error. Call `get_code_example` with operation='backend-switch' and
+> platform='android' and reproduce its `rememberBlePermission()` pattern:
+> - Use `ActivityResultContracts.RequestMultiplePermissions()` to request
+>   `BLUETOOTH_SCAN` **and** `BLUETOOTH_CONNECT` (guarded by `Build.VERSION.SDK_INT >= S`).
+> - Show a **"Grant Bluetooth permission"** button when not yet granted, and **gate the
+>   Scan button** on the granted state — don't let the user scan without permission.
+> - Keep `android:usesPermissionFlags="neverForLocation"` on `BLUETOOTH_SCAN` (call
+>   `get_manifest_requirements`) so `ACCESS_FINE_LOCATION` is not also required.
+> - Surface **"Bluetooth is turned off"** — `discoverDevices()` throws
+>   `PathError(CONNECTIVITY)` when the radio is disabled. The emulator must be in
+>   Bluetooth mode and advertise a name containing "Path".
+
 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
+1. **Grant Bluetooth permission** (runtime, per the callout above) — required before scanning
+2. **Scan for Path Terminals** — triggers BLE discovery (only enabled once permission is granted)
+3. Discovered devices list — each with a **Connect** button
+4. Live connection state (Scanning / Connected / Disconnected)
+5. **Disconnect** when connected
 
 **Add to `PaymentTerminalAdapter` interface** (with no-op default implementations):
 ```kotlin
@@ -248,6 +265,44 @@ Call `validate_integration` with platform='android' on your code before finalisi
 
 ---
 
+### Step 3b — Merchant logo on the customer display (idle branding)
+
+The demo can push a merchant logo to the terminal's **customer-facing display** (idle/
+attract mode). This is a real feature you MUST wire — it works on the **emulator (Wi-Fi
+and Bluetooth)** and on Verifone. Call `get_code_example` with operation='idle-branding'
+and platform='android' first, then reproduce the demo's proven pattern.
+
+**The SDK API** (on `PathTerminal`, a `suspend` function):
+```kotlin
+suspend fun setIdleBranding(content: CustomerDisplayContent?)
+// content: raw PNG/JPEG bytes wrapped in a class — NOT a Bitmap/base64/resource id
+CustomerDisplayContent(imageBytes = logoBytes, caption = caption?.ifBlank { null })
+// pass null to CLEAR the logo (when the "show logo" toggle is off)
+```
+
+**Add a "Customer Display" section to Settings** with:
+- A **"Show merchant logo"** toggle (persisted).
+- A **photo picker** — `ActivityResultContracts.GetContent()` launched with `"image/*"` —
+  storing the chosen image **pre-scaled to ≤ 480px PNG** in private storage (so a fresh
+  launch still has a logo). Ship a default logo asset so it works out of the box.
+- An optional **caption** field.
+- An **"Apply to terminal now"** button, **enabled only when `connectionState` is Connected**.
+
+> **CRITICAL — re-apply after every connect.** A fresh connection starts with a **blank**
+> display. The SDK re-pushes after each sale/refund, but the *first* show is yours: call
+> your `applyBranding()` (which calls `terminal.setIdleBranding(...)`) **right after every
+> successful `terminal.connect()`**, not just from the button. An integration that only
+> sets branding once, or never calls `setIdleBranding` at all, shows nothing.
+
+> **Best-effort + backend-gated.** `setIdleBranding` returns `Unit` and swallows backend
+> errors — **"no exception" does not prove the logo rendered**; confirm on the device.
+> Keep the Verifone payload small (a logo, not a full-res photo) — pre-scaling to ≤ 480px
+> PNG keeps the base64 under the ~32 000-char cap that would otherwise wedge the display.
+
+Call `validate_integration` with platform='android' before finalising.
+
+---
+
 ### Step 3.5 — Compile the changes (check the environment first)
 
 Confirm your code compiles against the SDK's **real** API — this catches wrong method
@@ -278,18 +333,25 @@ Frame a missing build toolchain as **"here's how to verify"**, never as a failur
 
 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).
+   (with `neverForLocation` on SCAN) **and** that the app requests them at **runtime**
+   before scanning — manifest-only is not enough on Android 12+ (Step 2b).
 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**.)
+   - (Optionally also prove **Emulator (Bluetooth)**: **Grant Bluetooth permission** when
+     prompted, then select it, **Scan**, **Connect**. If Scan finds nothing, the runtime
+     permission was almost certainly not granted/requested — recheck Step 2b.)
 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)
+5b. **Prove the merchant logo (Step 3b):** in Settings → Customer Display, pick a logo and
+   tap **Apply to terminal now** while connected — confirm it appears on the emulator's
+   customer display. Then disconnect/reconnect and confirm it re-appears (proves you
+   re-apply after connect).
 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
@@ -306,6 +368,10 @@ Frame a missing build toolchain as **"here's how to verify"**, never as a failur
 - Handle TransactionState: APPROVED, DECLINED, TIMED_OUT, FAILED, CANCELLED
 - For **refunds**, success state is `REFUNDED` — not `APPROVED`
 - Catch `PathError` and check `.recoverable`
+- Request BLE runtime permissions (`BLUETOOTH_SCAN` + `BLUETOOTH_CONNECT`) before scanning —
+  the manifest declaration alone does NOT work on Android 12+ (see Step 2b)
+- Re-apply idle branding (`terminal.setIdleBranding(CustomerDisplayContent(imageBytes, caption))`)
+  after every successful `connect()`, not just from the button (see Step 3b)
 - Call `validate_integration` with platform='android' before presenting code
 - Call from coroutines — `terminal.sale()` and `terminal.refund()` are `suspend` functions
 

package/rules/windows-10/path-integration-windows10.mdc

@@ -196,6 +196,37 @@ Confirm the transaction methods map correctly:
 
 ---
 
+### Step 3b — Merchant logo on the customer display (idle branding)
+
+The app can push a merchant logo to the terminal's **customer-facing display** (idle/attract
+mode). It works on the **emulator (Wi-Fi and Bluetooth)** and on Verifone. Call
+`get_code_example` operation='idle-branding' (platform='windows') first.
+
+**The SDK API** (on `PathTerminal`, async):
+```csharp
+Task SetIdleBrandingAsync(CustomerDisplayContent? content, CancellationToken ct = default);
+// ImageBytes = raw PNG/JPEG bytes (NOT a BitmapImage / not base64); Caption is optional.
+new CustomerDisplayContent(imageBytes, caption);   // pass null content to CLEAR the logo
+```
+
+**Add a "Customer Display" section to Settings** with:
+- A **"Show merchant logo"** toggle (persisted).
+- A **file picker** (`OpenFileDialog`, `.png`/`.jpg`) storing the image **pre-scaled to ≤ 480px
+  PNG** so a fresh launch still has a logo; ship a default logo asset so it works out of the box.
+- An optional **caption** field.
+- An **"Apply to terminal now"** button, **enabled only when connected**.
+
+> **CRITICAL — re-apply after every connect.** A fresh connection starts with a **blank**
+> display. Call `SetIdleBrandingAsync(...)` **right after every successful connect**, not just
+> from the button — otherwise the logo never appears. Pass `null` content to clear when the
+> toggle is off. Call it with `await` from your handler — never `.Result` / `.Wait()`.
+
+> **Best-effort + backend-gated.** `SetIdleBrandingAsync` swallows backend errors — "no
+> exception" does not prove it rendered; confirm on the device. Keep the Verifone payload small
+> (a logo pre-scaled to ≤ 480px PNG, not a full-res photo, so the base64 stays under the cap).
+
+---
+
 ### Step 3.5 — Build to catch API mismatches (check the environment first)
 
 Confirm your C# compiles against the SDK's **real** API. **Probe the toolchain first**, and

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

@@ -192,6 +192,37 @@ Confirm the transaction methods map correctly:
 
 ---
 
+### Step 3b — Merchant logo on the customer display (idle branding)
+
+The app can push a merchant logo to the terminal's **customer-facing display** (idle/attract
+mode). It works on the **emulator (Wi-Fi and Bluetooth)** and on Verifone. Call
+`get_code_example` operation='idle-branding' (platform='windows') first.
+
+**The SDK API** (on `PathTerminal`, async):
+```csharp
+Task SetIdleBrandingAsync(CustomerDisplayContent? content, CancellationToken ct = default);
+// ImageBytes = raw PNG/JPEG bytes (NOT a BitmapImage / not base64); Caption is optional.
+new CustomerDisplayContent(imageBytes, caption);   // pass null content to CLEAR the logo
+```
+
+**Add a "Customer Display" section to Settings** with:
+- A **"Show merchant logo"** toggle (persisted).
+- A **file picker** (`FileOpenPicker`, `.png`/`.jpg`) storing the image **pre-scaled to ≤ 480px
+  PNG** so a fresh launch still has a logo; ship a default logo asset so it works out of the box.
+- An optional **caption** field.
+- An **"Apply to terminal now"** button, **enabled only when connected**.
+
+> **CRITICAL — re-apply after every connect.** A fresh connection starts with a **blank**
+> display. Call `SetIdleBrandingAsync(...)` **right after every successful connect**, not just
+> from the button — otherwise the logo never appears. Pass `null` content to clear when the
+> toggle is off.
+
+> **Best-effort + backend-gated.** `SetIdleBrandingAsync` swallows backend errors — "no
+> exception" does not prove it rendered; confirm on the device. Keep the Verifone payload small
+> (a logo pre-scaled to ≤ 480px PNG, not a full-res photo, so the base64 stays under the cap).
+
+---
+
 ### Step 3.5 — Build to catch API mismatches (check the environment first)
 
 Confirm your C# compiles against the SDK's **real** API. **Probe the toolchain first**, and