Cards in terminal states (lost, stolen, expired, cancelled)

# Instructions

## Use case

Identify cards in a terminal state for security workflows (blocking lost/stolen cards) or cleanup (expired or cancelled cards).

## Full card lifecycle

```
PRE (pre-active)
  ↓
ACT (active) ←→ BLO (blocked)
                    ↓
                  REA (reactivated) → ACT

Terminal states — IRREVERSIBLE:
  LOS  — Lost
  STO  — Stolen
  DAM  — Damaged
  EXP  — Expired (reached expiry date)
  CAN  — Cancelled (manually cancelled)
  CMD  — Compromised
  CBL  — Disabled/hidden (deactivated, does not return to active)
```

## Pitfall — one status per call

`list_cards.status` is a **plain string** (not an array). To cover several terminal states, make multiple calls:

```json
// Call 1 — Lost cards
{ "companyId": "<COMPANY_ID>", "status": "LOS", "pageSize": 100 }

// Call 2 — Stolen cards
{ "companyId": "<COMPANY_ID>", "status": "STO", "pageSize": 100 }

// Call 3 — Expired cards (useful for cleanup)
{ "companyId": "<COMPANY_ID>", "status": "EXP", "pageSize": 100 }

// Call 4 — Cancelled cards
{ "companyId": "<COMPANY_ID>", "status": "CAN", "pageSize": 100 }

// Call 5 — Compromised cards (security alert)
{ "companyId": "<COMPANY_ID>", "status": "CMD", "pageSize": 100 }
```

→ Merge the results client-side for a consolidated view.

## Distinguishing terminal vs non-terminal

| Status | Terminal? | Can return to ACT? | Use case |
|--------|-----------|-------------------|----------|
| ACT | No | — | Current |
| BLO | No | Yes (via REA) | Temporarily blocked |
| REA | No | — | Reactivated after BLO |
| PRE | No | Yes | Awaiting activation |
| LOS | **Yes** | ❌ No | Loss declaration |
| STO | **Yes** | ❌ No | Theft declaration |
| DAM | **Yes** | ❌ No | Physically damaged card |
| EXP | **Yes** | ❌ No | Expiry date reached |
| CAN | **Yes** | ❌ No | Manual cancellation |
| CMD | **Yes** | ❌ No | Compromise detected |
| CBL | **Yes** | ❌ No | Disabled/hidden |

## Data available on a terminal card

Cards in a terminal state return the same fields as ACT cards:
```json
{
  "id": "...",
  "type": "subscription",
  "status": "CAN",
  "lastFourDigits": "1234",
  "expiryDate": "2025-12-31T23:59:59.000Z",
  "ownerId": "<userId>",
  "currency": "EUR",
  "availableBalance": { ... },   // potential residual balance
  "spendingLimit": { ... }
}
```

If `availableBalance > 0` on a cancelled or expired card, a refund may be pending.

## Limitations observed on this account

- `status: "EXP"` → 0 results — no expired card visible (possibly because expired cards are archived or purged from the API after a certain delay)
- `status: "CAN"`, `status: "BLO"`, etc. → not tested on this account due to an MCP connection instability

## PAN and CVV never returned

The full card number (PAN) and the CVV are never returned by the MCP — only the last 4 digits (`lastFourDigits`). This is a security limitation by design.

## Example user prompts

- "Are there any lost or stolen cards active on the account?"
- "Show me all cards cancelled this quarter"
- "Which expired cards still have a positive balance?"