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)
  ABO  — Aborted

Other code: CMD — legacy code, returned with the label "Unknown" (not listed as terminal)
  CBL  — Hidden (disabled; not listed among terminal states by the server)
```

## Pitfall — one status per call

`list_cards.status` is a **plain string** (not an array). Warning: `list_cards` NEVER returns Lost, Stolen, Damaged, Expired or Cancelled cards — filtering on those statuses returns an empty list, which must not be read as "no such cards". Those cards can only be read by ID with `get_card`. The calls below therefore return an empty list for LOS, STO, EXP and CAN:

```json
// Only these filters can return cards through list_cards
{ "companyId": "<COMPANY_ID>", "status": "Blocked", "pageSize": 100 }
{ "companyId": "<COMPANY_ID>", "status": "Hidden", "pageSize": 100 }
```

→ For a lost, stolen, damaged, expired or cancelled card, you need its ID and a `get_card` call: there is no way to list them. An empty list on those statuses never means "no such card".

## 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 card",
  "status": "Cancelled",
  "lastFourDigits": "1234",
  "expiryDate": "2025-12-31T23:59:59.000Z",
  "owner": { "id": "<userId>", "label": "<name>" },
  "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 — expected behaviour: `list_cards` never returns Lost, Stolen, Damaged, Expired or Cancelled cards; read them by ID with `get_card`
- `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?"