url_shortening_service/README.md

# url_shortening_service

Django 6 URL shortener. `monica_site` (and other trusted callers) mint links over
Bearer auth on an **API hostname** (may be public DNS). SMS recipients hit
`GET /<code>` on the **short** domain and get a 302 to the long HTTPS URL.

This service is standalone. Do not fold it into `monica_site`.

## Two surfaces

| Who | Path | Auth | Host |
|-----|------|------|------|
| Phone / public internet | `GET /<code>` | none | `SHORT_DOMAIN` (NPM + TLS) |
| Anyone | `GET /` | none | landing page on the short domain |
| `monica_site` | `/api/links/` | `Authorization: Bearer name:secret` | own DNS / NPM host — **not** the short domain |

The API may be on the public internet. It is not open: every `/api/` request needs a
named Bearer token. No token / wrong token → **401**. No tokens configured → **503**.
`GET /<code>` never requires a token.

`/api/` and `/admin/` are 404 on the short domain. `/admin/` is also 404 on the
public API hostname (localhost only). `GET /debug/` is a mint form when
`DEBUG=true` and never on the short domain.

## Local run

```bash
cp .env.example .env
# SHORTENER_API_TOKENS=monica:dev-only-token is already set
docker compose up --build
```

Or without Docker:

```bash
uv sync
cp .env.example .env
cd site && uv run python manage.py migrate
uv run python manage.py runserver
# optional local admin:
# uv run python manage.py createsuperuser
# then http://127.0.0.1:8005/admin/  (compose) or :8000 (runserver)
```

Tests (SQLite, no network):

```bash
cd site && uv run python manage.py test
```

## CI / deploy (Gitea)

Same split as `monica_site`:

| Workflow | When | What |
|----------|------|------|
| `CI` | pull request → `master` | unit tests |
| `Deploy Beta` | push / merge to `master` | unit tests → compose tests → deploy **beta** |
| `Deploy Prod` | **Actions → Run workflow** (button) | unit tests → compose tests → deploy **prod** |

Deploy calls `server-infra/scripts/deploy.sh --app url_shortening_service`. Needs [server-infra#22](https://git.aimloperations.com/ai_ml_operations/server-infra/issues/22) first.

## Use case

1. Your site POSTs to this service with a Bearer token and a long HTTPS URL.
2. Response `201` includes `short_url` built from `PUBLIC_SHORT_URL` (not the API Host).
3. A person on the public internet opens that short URL.
4. This service 302s them to the long URL and increments `click_count`.

Mint (API host / localhost):

```bash
curl -sS -X POST http://127.0.0.1:8005/api/links/ \
  -H "Authorization: Bearer monica:dev-only-token" \
  -H "Content-Type: application/json" \
  -d '{"target_url":"https://mkdrealtor.com/","title":"test"}'
```

Follow (no token — this is the public path):

```bash
curl -sSI http://127.0.0.1:8005/<code>
```

Expect `HTTP/1.1 302 Found` and `Location: https://mkdrealtor.com/`.

Caller integration (onboard + `/api/links/`): **[API.md](API.md)**.

## Caller contract (`monica_site`, other repo)

```text
SHORTENER_BASE_URL=https://shortener.aimloperations.com
SHORTENER_API_TOKEN=monica:<same-secret-as-SHORTENER_API_TOKENS>
```

```http
POST /api/links/
Authorization: Bearer monica:<secret>
Content-Type: application/json

{"target_url":"https://mkdrealtor.com/listings/oak-st?utm_source=monica&utm_medium=sms","title":"Oak St","external_ref":"campaign-uuid"}
```

`target_url` must be `https` and its host must match `SHORT_ALLOWED_HOSTS`
(exact or suffix, e.g. `mkdrealtor.com`). Same `target_url` + `external_ref` +
still-active link returns `200` with the existing row instead of a new code.

Do not call the public short hostname to create links.

## Environment

See `.env.example` and `.env.prod.example`. Prod secrets live in
`~/Documents/secrets/url_shortening_service/` on the control node.

Generate tokens and peppers with:

```bash
python -c "import secrets; print(secrets.token_urlsafe(32))"
```

Never reuse `DJANGO_SECRET_KEY` as an API token. Never put the token in the
short URL, logs, or git.

## Deploy notes

Two NPM hosts, same container `WEB_PORT` (default 8005 prod / 8015 beta):

1. `SHORT_DOMAIN` (`piha.lc` prod / `beta.piha.li` beta) — `/` landing + `GET /[a-z0-9]{4,8}`.
   Drop `/api/`, `/admin/`, `/debug/`.
2. API hostname — proxy `/api/` only. Drop `/admin/`. Add that Host to
   `DJANGO_ALLOWED_HOSTS` and `SHORT_API_HOSTS`.