# url_shortening_service

Django 6 URL shortener. `monica_site` (and other trusted callers) mint links over
Bearer auth on the **same** public host phones use. SMS recipients hit
`GET /<code>` on `piha.lc` (prod) / `beta.piha.li` (beta) 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` (`piha.lc` / `beta.piha.li`) |
| Anyone | `GET /` | none | landing page on that same host |
| `monica_site` | `/api/links/` | `Authorization: Bearer name:secret` | same host |

`/api/` is 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.

`/admin/` is 404 on the public host. Local compose serves it on `localhost` and
`10.0.0.128` (`http://10.0.0.128:8005/admin/` from another machine on the LAN).
`GET /debug/` is a mint form when `DEBUG=true` and never on the public short host.

## 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)
# LAN: http://10.0.0.128:8005/admin/  (compose publishes 0.0.0.0:8005)
```

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`.
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 (same 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://piha.lc
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 put the Bearer token on `GET /<code>`.

## 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

One NPM host, 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}`, and `/api/` (Bearer). Django 404s `/admin/` and `/debug/`
   on this host. Add it to `DJANGO_ALLOWED_HOSTS`, `SHORT_PUBLIC_HOSTS`, and
   `SHORT_API_HOSTS`.