# Humblytics Agent Onboarding API

Sign up for a Humblytics account, choose a plan, and get an API token — all without leaving the terminal.

---

## Overview

The signup flow has two parts:

1. **You (the agent)** call `/api/v1/auth/agent-initiate` to create a session and get a unique URL.
2. **The user** opens that URL in their browser to verify identity and complete payment.
3. **You (the agent)** poll until the session is complete, then receive an `authToken` for all subsequent API calls.

---

## Step 1 — Initiate signup

```
POST https://app.humblytics.com/api/v1/auth/agent-initiate
Content-Type: application/json

{ "email": "user@example.com", "name": "Jane Smith" }
```

**Response:**
```json
{
  "token": "<session-token>",
  "verifyUrl": "https://app.humblytics.com/agent-verify?token=<session-token>",
  "expiresAt": 1234567890000
}
```

- If the email already has an account, returns `{ "error": "user_exists" }` (HTTP 409).
- The session expires in **10 minutes** if the user doesn't open the link.

---

## Step 2 — Ask the user to open the link

Tell the user:

> "Please open this URL in your browser to create your account and choose a plan (takes ~1 minute):"
> `https://app.humblytics.com/agent-verify?token=<session-token>`

The page will:
1. Silently verify the user is human
2. Create their account and set a browser session
3. Ask them to choose **Business Monthly ($79/mo)** or **Business Annual ($65/mo, save $168/yr)**
4. Redirect them to Stripe to complete payment
5. After payment, show a confirmation page

---

## Step 3 — Poll for completion

Poll every 3–5 seconds until `status` is `"complete"` or the session expires:

```
GET https://app.humblytics.com/api/v1/auth/agent-signup-status?token=<session-token>
```

**While waiting:**
```json
{ "status": "pending" }
```

**When done:**
```json
{
  "status": "complete",
  "authToken": "<jwt>"
}
```

**Error responses:**
- `404` — token not found
- `410` — session expired (ask user to start over)

> The `authToken` is delivered **once** — the session is deleted after this response. Store it.

---

## Step 4 — Use the token

All subsequent API calls use the token as a Bearer header:

```
Authorization: Bearer <authToken>
```

---

## Step 5 — Add a website

```
POST https://app.humblytics.com/api/v1/add-custom-site
Authorization: Bearer <authToken>
Content-Type: application/json

{ "domain": "example.com", "name": "My Site" }
```

**Response:**
```json
{
  "propertyId": "<property-id>",
  "scriptId": "<script-id>"
}
```

Install the tracking script on the user's site:

```html
<script async src="https://app.humblytics.com/hmbl.min.js?id=<script-id>"></script>
```

---

## Step 6 — Get the Stripe payment link (if skipped during signup)

If the user skipped payment during signup, send them to:

- **Monthly:** `https://buy.stripe.com/6oU9AS4TVdaQafZ9tS2Nq0k?prefilled_email=<email>`
- **Annual:** `https://buy.stripe.com/8x2cN40DF4EkafZ49y2Nq0j?prefilled_email=<email>`

---

## Quick reference

| Step | Method | Endpoint |
|------|--------|----------|
| Initiate signup | POST | `/api/v1/auth/agent-initiate` |
| Poll for completion | GET | `/api/v1/auth/agent-signup-status?token=<token>` |
| Add a website | POST | `/api/v1/add-custom-site` |
| List websites | GET | `/api/v1/property/all` |
| Billing status | GET | `/api/v1/billing/status` |