# Subito AI Guru — E2E Test Cases

Executable against the locally running stack (core on :9005, console on :3002 — do NOT start/stop servers). Run everything from the repo root. ElevenLabs is simulated with curl.

## Safety rules (binding)

1. READ-ONLY member tools (lookup-member, member-overview, bookings, booking, points) MAY be called with real member references.
2. NEVER confirm/execute a write action (PASSWORD_RESET / SEND_VERIFICATION_EDM / SYNC_PROFILE) against a real member. Scenario 10 stops at: PENDING row exists + unauthenticated confirm is 401 + row still PENDING.
3. ClickUp: at most ONE test task, name starting `[E2E TEST]`, only if `GURU_CLICKUP_LIST_ID` is set; record its id for manual deletion. These scenarios are designed to create none.
4. No Viewpoint writes. Only fake conversation ids go to the post-call webhook so the closed-log step can never fire.
5. Never print secret values. Reference env vars; load them from `apps/core/.env` with the setup block below.

## Setup (run once per shell)

```bash
cd "/Users/shiju/Source Code/karma-subito-and-marketing-admin-panel"
export GURU_TOOL_SHARED_SECRET="$(grep '^GURU_TOOL_SHARED_SECRET=' apps/core/.env | cut -d= -f2-)"
export ELEVENLABS_WEBHOOK_SECRET="$(grep '^ELEVENLABS_WEBHOOK_SECRET=' apps/core/.env | cut -d= -f2-)"
export GURU_AGENT_ID="$(grep '^SUBITO_AI_GURU_ELEVENLABS_AGENT_ID=' apps/core/.env | cut -d= -f2-)"
CORE=http://localhost:9005
PSQL="psql -d karma_core -X -q"   # if this db doesn't exist, use: psql -d "$(grep '^DATABASE_NAME=' apps/core/.env | cut -d= -f2-)"
```

Note: `ELEVENLABS_WEBHOOK_SECRET` is NOT present in `apps/core/.env` at time of writing — if it comes back empty, Scenario 12 must be marked SKIPPED (the route returns 500 "Server configuration error" when the secret is unset in the running core; do not add env vars or restart the server to work around this).

`<MEMBER_REF>` = a real reference supplied by the operator. Suggested: `1199943` (mentioned by the user; it may be a member_number rather than a membership_number — Scenario 4 tests both fields).

---

## 1. Health / boot

```bash
curl -s -o /dev/null -w '%{http_code}\n' $CORE/health          # expect 200
curl -s $CORE/health | jq .status                              # expect "ok" (body also has version/timestamp/git)
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:3002/ # expect 302 (or 200 if console serves a page; any non-5xx = up)
```

Pass: core 200 `{"status":"ok",...}`; console responds (302 expected).

## 2. Tool auth

```bash
# missing secret
curl -s -o /dev/null -w '%{http_code}\n' -X POST $CORE/v1/guru/tools/entitlements \
  -H 'Content-Type: application/json' -d '{"conversation_id":"x"}'          # expect 401
# wrong secret
curl -s -o /dev/null -w '%{http_code}\n' -X POST $CORE/v1/guru/tools/entitlements \
  -H 'X-Guru-Secret: wrong' -H 'Content-Type: application/json' -d '{"conversation_id":"x"}'  # expect 401
# valid secret, unbound conversation
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/guru/tools/entitlements \
  -H "X-Guru-Secret: $GURU_TOOL_SHARED_SECRET" -H 'Content-Type: application/json' \
  -d '{"conversation_id":"no-such-conv"}'
```

Pass: 401 / 401 (body "Unauthorized"); then 403 with `{"status":"error","message":"This conversation is not linked to a Console ticket. ..."}`.

## 3. Seed ticket (setup)

```bash
$PSQL -c "SELECT id, email FROM console_users WHERE is_active = true LIMIT 1;"   # pick a real user
$PSQL -c "INSERT INTO guru_tickets (console_user_id, concierge_email, member_ref, category, summary, conversation_ids)
SELECT id, email, 'e2e', 'other', 'E2E seed ticket', ARRAY['e2e-conv-1']
FROM console_users WHERE is_active = true LIMIT 1
RETURNING id, reference;"
```

Pass: one row returned; record `id` as `<TICKET_ID>` and `reference` (GRU-xxxx). All subsequent tool calls use `"conversation_id":"e2e-conv-1"`.

## 4. lookup-member

```bash
# by membership_number
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/guru/tools/lookup-member \
  -H "X-Guru-Secret: $GURU_TOOL_SHARED_SECRET" -H 'Content-Type: application/json' \
  -d '{"conversation_id":"e2e-conv-1","membership_number":"<MEMBER_REF>"}'
# by member_number (1199943 may be this, not a membership_number)
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/guru/tools/lookup-member \
  -H "X-Guru-Secret: $GURU_TOOL_SHARED_SECRET" -H 'Content-Type: application/json' \
  -d '{"conversation_id":"e2e-conv-1","member_number":"<MEMBER_REF>"}'
# by email (operator-supplied real member email, read-only)
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/guru/tools/lookup-member \
  -H "X-Guru-Secret: $GURU_TOOL_SHARED_SECRET" -H 'Content-Type: application/json' \
  -d '{"conversation_id":"e2e-conv-1","email":"<MEMBER_EMAIL>"}'
```

Pass: each call is 200 with either `{"status":"ok","data":...}` or `{"status":"not_found","message":"No ... found ..."}`. In any ok payload, `email_masked` must be masked (pattern `xx***...@domain` — the local part before `@` must contain `*`; no raw address). At least one of membership_number/member_number should resolve for 1199943; record which.

## 5. member-overview

```bash
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/guru/tools/member-overview \
  -H "X-Guru-Secret: $GURU_TOOL_SHARED_SECRET" -H 'Content-Type: application/json' \
  -d '{"conversation_id":"e2e-conv-1","membership_number":"<MEMBER_REF>"}'
```

Pass: 200. Either `status:"ok"` with `data.last_session` = `{at,app,app_version,os,device}` or `{note:"No app sessions recorded — the member may never have logged in."}` plus `booking_counts`; or `status:"not_found"` ("No account found for that membership number.").

## 6. bookings (Viewpoint DB)

```bash
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/guru/tools/bookings \
  -H "X-Guru-Secret: $GURU_TOOL_SHARED_SECRET" -H 'Content-Type: application/json' \
  -d '{"conversation_id":"e2e-conv-1","membership_number":"<MEMBER_REF>"}'
```

Pass: 200 `status:"ok"` with rows `{booking_no,status,resort,room_type,arrival,departure,source,confirmed}` OR 200 `status:"not_found"`. Acceptable-with-note: 500 `{"status":"error","message":"The lookup failed..."}` or the 15s-timeout error JSON if VIEWPOINT_DATABASE_* is unreachable locally — note it, no crash.

## 7. points

```bash
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/guru/tools/points \
  -H "X-Guru-Secret: $GURU_TOOL_SHARED_SECRET" -H 'Content-Type: application/json' \
  -d '{"conversation_id":"e2e-conv-1","membership_number":"<MEMBER_REF>"}'
```

Pass: 200 `{"status":"ok","data":{"balance":...,"entitlement_lines":N}}` or `status:"not_found"` ("No points data found for that account.").

## 8. entitlements

```bash
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/guru/tools/entitlements \
  -H "X-Guru-Secret: $GURU_TOOL_SHARED_SECRET" -H 'Content-Type: application/json' \
  -d '{"conversation_id":"e2e-conv-1"}'
```

Pass: 200 `{"status":"escalate","message":"Entitlement details cannot be checked automatically yet. ..."}`.

## 9. update-ticket + email redaction

```bash
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/guru/tools/update-ticket \
  -H "X-Guru-Secret: $GURU_TOOL_SHARED_SECRET" -H 'Content-Type: application/json' \
  -d '{"conversation_id":"e2e-conv-1","category":"login","summary":"Member fake.person@example.com cannot log in (E2E)"}'
$PSQL -c "SELECT category, summary FROM guru_tickets WHERE id = '<TICKET_ID>';"
$PSQL -c "SELECT action, metadata FROM guru_audit_log WHERE ticket_id = '<TICKET_ID>' AND action = 'ticket.updated_by_agent';"
```

Pass: 200 `{"status":"ok","data":{"reference":"GRU-...","updated":["category","summary"]}}`; DB row: category = `login`, summary contains `[email redacted]` and NOT `fake.person@example.com`; one `ticket.updated_by_agent` audit row.

## 10. propose-action (never confirmed)

```bash
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/guru/tools/propose-action \
  -H "X-Guru-Secret: $GURU_TOOL_SHARED_SECRET" -H 'Content-Type: application/json' \
  -d '{"conversation_id":"e2e-conv-1","action_type":"PASSWORD_RESET","member_ref":"e2e","summary":"E2E test proposal","member_record_id":"00000000-0000-4000-8000-000000000001"}'
# -> note data.action_id as <ACTION_ID>
$PSQL -c "SELECT id, action_type, status FROM guru_pending_actions WHERE ticket_id = '<TICKET_ID>';"
# unauthenticated confirm must be rejected
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/admin-console/guru/actions/<ACTION_ID>/confirm
# row must be untouched
$PSQL -c "SELECT status, confirmed_by FROM guru_pending_actions WHERE id = '<ACTION_ID>';"
```

Pass: propose = 200 `status:"ok"` with `data.action_id` and the "Nothing has been changed yet" note; SQL shows status `PENDING`; confirm without cookie = 401 ("Unauthorized Access"); final SQL: status STILL `PENDING`, confirmed_by NULL. DO NOT confirm with any session.

## 11. ticket-history

```bash
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/guru/tools/ticket-history \
  -H "X-Guru-Secret: $GURU_TOOL_SHARED_SECRET" -H 'Content-Type: application/json' \
  -d '{"conversation_id":"e2e-conv-1"}'
```

Pass: 200 `status:"ok"`, data has `reference,status,category,member_ref,summary,opened_at`, `history: []`, `note: "No ClickUp history yet."` (seeded ticket has no clickup_task_id — no ClickUp call made).

## 12. Webhook HMAC (SKIP if ELEVENLABS_WEBHOOK_SECRET is empty — see Setup note)

```bash
[ -n "$ELEVENLABS_WEBHOOK_SECRET" ] || echo "SKIP scenario 12: secret not configured"

# bad signature
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/kevo/webhooks/post-call \
  -H 'ElevenLabs-Signature: t=1,v0=deadbeef' -H 'Content-Type: application/json' \
  -d '{"type":"post_call_transcription","data":{"conversation_id":"x","agent_id":"x"}}'
# expect 401 "Invalid signature" (stale t also fails; if secret unset, 500 "Server configuration error" instead — record as SKIP)

# valid signature, guru agent, fake conversation
BODY=$(printf '{"type":"post_call_transcription","data":{"conversation_id":"e2e-conv-1","agent_id":"%s"}}' "$GURU_AGENT_ID")
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac "$ELEVENLABS_WEBHOOK_SECRET" -r | cut -d' ' -f1)
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/kevo/webhooks/post-call \
  -H "ElevenLabs-Signature: t=$T,v0=$SIG" -H 'Content-Type: application/json' --data-binary "$BODY"
# expect 200 {"received":true}

# unknown agent is acked too
BODY2='{"type":"post_call_transcription","data":{"conversation_id":"e2e-conv-x","agent_id":"agent_unknown_e2e"}}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY2" | openssl dgst -sha256 -hmac "$ELEVENLABS_WEBHOOK_SECRET" -r | cut -d' ' -f1)
curl -s -w '\n%{http_code}\n' -X POST $CORE/v1/kevo/webhooks/post-call \
  -H "ElevenLabs-Signature: t=$T,v0=$SIG" -H 'Content-Type: application/json' --data-binary "$BODY2"
# expect 200 {"received":true} (and a core log line "[Kevo] post-call from unknown agent agent_unknown_e2e ignored")

# verify enqueue + graceful failure on the fake conversation:
redis-cli keys 'bull:guru-postcall:*' | head        # job id guru-postcall-e2e-conv-1 appears
# then core log must show: "[GuruPostCallWorker] job guru-postcall-e2e-conv-1 failed ..." (ElevenLabs 404 -> UnrecoverableError, no retry storm, process still up)
curl -s -o /dev/null -w '%{http_code}\n' $CORE/health   # expect 200 (no crash)
```

Pass: bad sig 401; valid guru event 200 `{"received":true}`; job enqueued on queue `guru-postcall` and fails gracefully (UnrecoverableError logged, no crash); unknown agent 200.

## 13. Rate limit (OPTIONAL — hammers the endpoint; 120 req/60s fixed window per IP, keyed by X-Forwarded-For)

```bash
for i in $(seq 1 125); do
  curl -s -o /dev/null -w '%{http_code}\n' -X POST $CORE/v1/guru/tools/entitlements \
    -H "X-Guru-Secret: $GURU_TOOL_SHARED_SECRET" -H 'X-Forwarded-For: 10.99.99.99' \
    -H 'Content-Type: application/json' -d '{"conversation_id":"e2e-conv-1"}'
done | sort | uniq -c
```

Pass: first ~120 are 200, remainder 429 ("Too many requests"). Note: if Redis is down the limiter fails open (all 200) — record as acceptable-with-note. Wait 60s before any further tool scenarios.

## 14. Cleanup

```bash
$PSQL -c "DELETE FROM guru_audit_log WHERE ticket_id = '<TICKET_ID>';
DELETE FROM guru_pending_actions WHERE ticket_id = '<TICKET_ID>';
DELETE FROM guru_tickets WHERE id = '<TICKET_ID>';"
$PSQL -c "SELECT count(*) FROM guru_tickets WHERE id = '<TICKET_ID>';"   # expect 0
redis-cli del "bull:guru-postcall:guru-postcall-e2e-conv-1"   # optional: only the e2e job — never delete the queue meta keys
```

Pass: all three deletes succeed (FKs cascade/set-null anyway; explicit order avoids surprises); count 0. If a `[E2E TEST]` ClickUp task was created (shouldn't be), report its id for manual deletion.

## 15. Admin guard spot-checks (no cookie)

```bash
curl -s -w '\n%{http_code}\n' $CORE/v1/admin-console/guru/allowlist     # expect 401
curl -s -w '\n%{http_code}\n' $CORE/v1/admin-console/guru/analytics    # expect 401
curl -s -o /dev/null -w '%{http_code}\n' -X POST $CORE/v1/admin-console/guru/tickets -H 'Content-Type: application/json' -d '{}'  # expect 401
```

Pass: all 401 ("Unauthorized Access"). Interactive (cookied) admin flows are tested in the browser by a human, not here.
