# Barr Cyber Updater — AI Integration Guide

**Read this if you are an AI agent asked to "add update checking" or "wire up the updater" to a project.** It tells you exactly what to do. A human can follow it too.

The updater lets a shipped app **check for a newer version**, **download it (verified)**, and now **apply it in one call** — download → verify → install → relaunch. It talks to one public endpoint: `GET /api/update-check`. No build step, no package install — the client is a single file, standard library only.

---

## Step 0 — One config for both kits (recommended)

If the project also uses the **Installer Factory**, drop a single **`bcship.json`** at the project root and both kits read it — you configure once. Copy the template from either kit and set `product`, `name`, `versionFile`, `channel`. When `bcship.json` is present, the updater ignores its own CONFIG block. If you're only adding the updater, you can skip this and use the CONFIG block instead.

## Step 1 — Pick the client file for the project's language

| Language | File | Notes |
|---|---|---|
| Python | `bcupdate.py` | full self-update (`update_self`) |
| PowerShell | `bcupdate.ps1` | full self-update (`Update-BCSelf`) |
| Node / JavaScript | `bcupdate.js` | check + download (self-apply is app-specific) |

## Step 2 — Config

With `bcship.json`: nothing to edit in the client. Without it, set the four CONFIG values (`product`, `current`, `apiBase`, `channel`). Either way, **wire `current`/`versionFile` to the project's real version marker** — the clients read a `VERSION` file automatically if you point `versionFile` at it, so a build never reports a stale number.

## Step 3 — Check for updates (non-blocking, fail-quiet)

**Python**
```python
from bcupdate import check
info = check()
if info.update_available and not info.error:
    print(f"Update available: v{info.latest} — {info.notes}")
```
**PowerShell**
```powershell
. "$PSScriptRoot\bcupdate.ps1"
$u = Get-BCUpdate
if ($u.updateAvailable -and -not $u.error) { "v$($u.latest) is out" }
```

## Step 4 — Apply the update (the closed loop)

This is the part that used to be manual and now isn't. One call downloads the artifact, **verifies its SHA-256**, runs the bundled installer into the app's own folder (backing up the old one), and relaunches:

**Python**
```python
from bcupdate import update_self
result = update_self(license_key=user_key)   # {} on free products
# -> {"updated": True, "from": "1.5", "to": "1.6", "relaunched": True}
```
**PowerShell**
```powershell
Update-BCSelf -LicenseKey $userKey
```
**CLI**
```
python bcupdate.py --update --key BC-XXXX-XXXX-XXXX
powershell -File bcupdate.ps1 -Update -Key BC-XXXX-XXXX-XXXX
```

`update_self` is **safe to call on startup**: if the app is current, or the check fails, it does nothing and returns a reason. It never applies a download whose hash doesn't match — a tampered or corrupt file is rejected and the install is left untouched. Pass `relaunch=False` / `-NoRelaunch` if your app manages its own restart.

For **Node**, `check()` and `downloadLatest()` are provided; applying an update is left to the app because JS runtimes vary too much to relaunch safely in a generic way.

## Step 5 — API contract (reference / other languages)

```
GET https://barr-cyber.com/api/update-check?product=<id>&current=<version>&channel=<stable|beta>
-> { product, name, current, latest, updateAvailable, upToDate, channel,
     notes, date, sha256, size, mandatory, downloadUrl, releaseUrl }

POST https://barr-cyber.com/api/get-installer
{ "key": "BC-XXXX-XXXX-XXXX", "product": "<id>" }   -> streams the installer (verify the sha256)
```

## Rules that keep this safe

- **Only `stable` reaches normal users.** Betas surface only when the client sets `channel=beta`; drafts never.
- **Server-side version comparison is canonical** — `1.10 > 1.9`, a final release beats its own beta.
- **A failed check is not an error state** — clients return `upToDate=true` with `error` set, so update logic degrades to "assume fine."
- **Every applied update is hash-verified.** A mismatch aborts before anything is written.

## Done — report back

Tell the operator: which file you added, whether you used `bcship.json` or the CONFIG block, what you set `product`/`current`/`channel` to, where the check runs, and whether you enabled self-update. If the product id didn't exist in the admin Software tab, say so.