# hlpd quickstart for coding agents

hlpd adds a help centre with walkthroughs, an on-device support chat agent and bug
reports with ticket threads to iOS, Android and web apps. Full guide: https://hlpd.uk/docs/agents

## 1. Create the account and first app

```sh
curl -s -X POST https://api.hlpd.uk/api/signup \
  -H 'content-type: application/json' \
  -d '{"email": "ada@example.com", "password": "a-long-password", "project": "My app"}'
```

Use the user's own email address and a password of 8 to 1024 characters; `project` names
the first app (default "My app"). hlpd emails a verification link: the account works at once,
but a paid plan needs a verified address (`POST /api/verify/resend` resends it). Response `201`:

```json
{"token": "<owner session token, valid 30 days>",
 "owner": {"email": "ada@example.com", "email_verified": false, "plan": "free"},
 "project": {"id": "brp_…", "name": "My app", "sdk_key": "hk_…",
             "report_url": "https://api.hlpd.uk/report/brp_…", "api_url": "https://api.hlpd.uk"},
 "docs": "https://hlpd.uk/docs/agents", "verification": "sent"}
```

Errors are `{"error": {"code", "message", "field"}}`: `409 email_taken`, `422 invalid_request`
(`field` names the bad field), `429 rate_limited` (5 sign-ups per IP per hour), `403 signup_disabled`.

- `sdk_key` (`hk_…`) and `id` (`brp_…`) ship inside the app: put them in its config.
- `token` is the owner's secret. Never put it in app code or commit it; keep it in an
  environment variable such as `HLPD_TOKEN` and send it as `Authorization: Bearer <token>`
  to `https://api.hlpd.uk/admin/api/*`. When it expires, `POST /admin/api/session` with
  `{"email", "password"}` issues another; `POST /api/password/forgot` `{"email"}` resets a lost password.
- `report_url` is a hosted bug-report form you can link to without any SDK.
- Check the key: `curl -H 'Authorization: Bearer hk_…' https://api.hlpd.uk/v1/order` returns `200`.

## 2. Add the SDK

The help centre reads a generated help bundle shipped with the app (step 3).
Bug reports and ticket threads need only the `brp_` id.

iOS (SwiftUI, iOS 17): add the Swift package `sdk/ios/Hlpd` and the bundle
directory as a folder reference named `HlpdBundle`.

```swift
import Hlpd
let hlpd = HlpdConfiguration(
    apiKey: "hk_…",
    baseURL: URL(string: "https://api.hlpd.uk")!,
    tickets: HlpdTickets(serverURL: URL(string: "https://api.hlpd.uk")!, projectID: "brp_…"),
    context: { ["screen_name": "Settings"] }
)
HelpCenterView(configuration: hlpd)   // help centre, search, chat, contact support
HelpSupportView(configuration: hlpd)  // ticket inbox, report composer, threads
```

Reports only: `.bugReportSupportSheet(isPresented:reporter:)` with
`BugReporter(serverURL: URL(string: "https://api.hlpd.uk")!, projectID: "brp_…")`.

Android (Compose, minSdk 28): `implementation(project(":hlpd-sdk"))`, copy the
bundle to `src/main/assets/hlpd_bundle/`, and in the app module set
`android { androidResources { noCompress += "bin" } }`.

```kotlin
import uk.hlpd.sdk.*
val configuration = HlpdConfiguration(
    apiKey = "hk_…",
    baseUrl = "https://api.hlpd.uk",
    bundle = HlpdBundleSource.Assets("hlpd_bundle"),
    tickets = HlpdTickets(serverUrl = "https://api.hlpd.uk", projectId = "brp_…"),
    context = { mapOf("screen_name" to "Settings") },
)
HelpCenter(configuration)    // inside Compose
HelpSupport(configuration)
```

Reports only, from `uk.hlpd.sdk.bugreports`:
`BugReportSupportScreen(reporter = BugReporter("https://api.hlpd.uk", "brp_…", applicationContext), onClose = { … })`.

Web (ES modules, no build step): serve `sdk/web/src` and the bundle from your site.

```js
import { Hlpd } from "/hlpd/src/index.js";
const hlpd = await Hlpd.load({
  apiKey: "hk_…",
  baseURL: "https://api.hlpd.uk",
  bundleURL: "/hlpd-bundle/",
  tickets: { serverURL: "https://api.hlpd.uk", projectID: "brp_…" },
  context: () => ({ screen_name: "Settings" }),
});
hlpd.mountHelpCenter(document.querySelector("#help"));
hlpd.mountSupport(document.querySelector("#support"));
```

Reports only: `mountBugReportForm(form, { serverUrl: "https://api.hlpd.uk", projectId: "brp_…" })`
from `sdk/web/src/bug-reporter.js` (example: `sdk/web/widget/index.html`).

## 3. Generate and publish the help bundle

The generator in the hlpd repository (`generator/`, currently for iOS sources)
writes help topics, walkthroughs and a search index; ship `<out>/bundle` as above.

```sh
python -m hlpd_generator generate path/to/app --platform ios --out /tmp/hlpd/myapp
```

To update installed apps over the air, set the app's bundle id to the
manifest's `bundleId` once, then publish:

```sh
export HLPD_TOKEN=<token>
curl -s -X PATCH https://api.hlpd.uk/admin/api/projects/brp_… \
  -H "Authorization: Bearer $HLPD_TOKEN" -H 'content-type: application/json' \
  -d '{"bundle_id": "<manifest.json bundleId>"}'
python -m hlpd_generator publish /tmp/hlpd/myapp/bundle --project brp_… --api https://api.hlpd.uk
```

More owner calls (bearer token): `GET /admin/api/projects`, `POST /admin/api/projects`
`{"name"}` (another app), `POST /admin/api/projects/{id}/keys` (new SDK key).