Brand Region Client

Brand / Region Client Builder

Builds or fixes a BetterBlueKit API client for one (Brand, Region) pair. The hard part isn't Swift, it's figuring out the region's undocumented API — so every step is anchored to either an open-source reference or user-captured proxy logs.

Before starting, read docs/AddingNewRegion.md end-to-end. That guide is the rulebook; this skill is the execution playbook.

Phase 0 — Confirm scope

Ask the user (via AskUserQuestion):

1. Brand and region — e.g. "Kia Canada".
2. New client or fix? — greenfield implementation vs. patching an existing one. If patching, ask which bbcli command is failing and with what error.
3. Test credentials — do they have an account they can log in with? Tests against live accounts are how we validate each step.

Do NOT proceed past this phase without explicit answers. Guessing the brand or region silently rewires the factory.

Phase 1 — Find an authoritative reference

A wrong reference wastes hours. Check in this order:

1. hyundai_kia_connect_api (Python) — the broadest coverage, especially for non-USA regions. Fetch the region's module and the shared vehicle.py / api_impl.py with WebFetch:
   • https://raw.githubusercontent.com/Hyundai-Kia-Connect/hyundai_kia_connect_api/master/hyundai_kia_connect_api/
2. bluelinky (TypeScript)
3. scriptable-egmp (TypeScript)

For each reference, record:

• Base URL / host
• Login endpoint + body shape
• Auth token header name (Authorization vs. accessToken vs. Access-Token — these differ per region)
• Vehicle list endpoint
• Vehicle status endpoint (and whether cached/real-time live at the same URL or different URLs)
• Command endpoints for: lock, unlock, start climate, stop climate, start charge, stop charge

If NO reference covers this region (e.g. Kia Australia), skip to Phase 1b.

Phase 1b — User-captured proxy logs

Ask the user to capture traffic from the official app using Proxyman / mitmproxy / Charles. The AddingNewRegion guide has the step-by-step. Request, at minimum:

• Login (one request)
• Vehicle list (one request)
• Vehicle status (refreshed once so both endpoints hit if they differ)
• Lock + unlock (one each)
• Start climate with a known temperature

Have them export to a file and share the path. Then use Read on each to study request/response pairs. Treat every token and cookie as sensitive — never paste raw captures into code or commit them.

Phase 2 — Pick the reference client to copy

Match the new region against an existing BetterBlueKit client with the closest auth model. The right starting point saves the most work:

Use Read to open the chosen client plus its +Commands.swift and +Parsing.swift extensions. Note the file naming convention — every client follows the same three-file split.

Phase 3 — Scaffold the client

Create three files under BetterBlueKit/Sources/BetterBlueKit/API/<Brand><Region>/:

<Brand><Region>APIClient.swift            // login, fetchVehicles, fetchVehicleStatus, sendCommand
<Brand><Region>APIClient+Commands.swift   // commandURL, commandBody, method helpers
<Brand><Region>APIClient+Parsing.swift    // response → VehicleStatus / Vehicle mappers

The class MUST subclass APIClientBase and conform to APIClientProtocol. Start every method that isn't yet implemented by throwing APIError.regionNotSupported("not yet implemented") — a failing bbcli run is more actionable than a compile error.

Then register in APIClientFactory.swift:

1. Add a case in the brand-appropriate private createXClient function.
2. Add the region to supportedRegions(for:) (or betaRegions(for:) if you want a visible "beta" marker).

Phase 4 — Iterate with bbcli

This is the core loop. Run from the package root so Swift Package Manager resolves:

cd BetterBlueKit
swift build 2>&1 | tail -20   # compile first; fix any Swift errors
swift run bbcli -b <brand> -r <region> -u <user> -p <pass> [--pin <pin>]

Inside bbcli, work through the menu in this order:

1. Fetch Vehicles (menu 1) — validates login + token plumbing. Usually the first thing that breaks.
2. Fetch Vehicle Status (menu 2) — validates per-vehicle auth and the status parser.
3. Lock / Unlock (menu 3 / 4) — simplest commands, minimal payloads.
4. Start / Stop Climate (menu 5 / 6) — largest command bodies; temperature encoding often differs per region.
5. Start / Stop Charge (menu 7 / 8), Charge Limits (menu 9), EV Trip Details (menu 10).