rl-docs-hub

Home · Apps · rl-bank-mvp

---

API specs — card servicing + activity slice

Status: Draft, intended to match the current implementation slice.

GraphQL additions

Card mutations

publicSetMyCardFrozen(input)

Sets the frozen state for a customer-owned card.

Input:

• cardId: String!
• frozen: Boolean!

Output:

• standard result envelope
• data contains updated card object
• debugCorrelationId: String on the payload when available

Behavior:

• when frozen=true, target card status becomes FROZEN
• when frozen=false, target card status becomes ACTIVE
• idempotent if the card is already in the requested state

publicUpdateMyCardSpendingLimit(input)

Updates the customer-visible spending limit for a card.

Input:

• cardId: String!
• spendingLimit: Float!

Output:

• standard result envelope
• data contains updated card object
• debugCorrelationId: String on the payload when available

Validation:

• minimum 500
• maximum 20000
• card must not be CLOSED

Activity query

publicListMyActivity

Returns a reverse-chronological activity feed for the authenticated customer.

Output item fields:

• id
• category — CARD, TRANSFER, NOTIFICATION, ACCOUNT
• title
• description
• createdAt
• readAt nullable
• cardId nullable
• accountId nullable
• transactionId nullable
• notificationId nullable
• debugCorrelationId nullable

Sources:

• card servicing events
• card issuance / activation milestones
• recent transactions/transfers

Notification queries / mutations

publicListMyNotifications

Returns customer-scoped in-app notifications ordered newest-first.

Output item fields:

• id
• title
• body
• level — INFO, SUCCESS, WARNING
• readAt nullable
• createdAt
• relatedCardId nullable
• relatedAccountId nullable
• debugCorrelationId nullable

publicMarkMyNotificationRead(input)

Marks a customer-owned notification as read.

Input:

• notificationId: String!

Output:

• standard result envelope
• updated notification item

Existing objects extended

CardObject

Add fields:

• canFreeze: Boolean!
• canUnfreeze: Boolean!
• canUpdateSpendingLimit: Boolean!

AccountObject

Add fields for account-detail realism:

• recentTransactionCount: Int!
• inflowTotal30d: Float!
• outflowTotal30d: Float!
• balanceGap: Float!

These are derived summary fields, not separate stored source-of-truth balances.

Account history usage

publicListMyAccounts

Existing query remains in use, but account items should now include the derived fields above so the apps can render a believable portfolio view.

publicGetMyAccount(input)

Existing query remains the single-account detail fetch.

publicListMyTransactions

Existing query remains the source for recent account history. Apps may filter transactions client-side by accountId for the selected account in this slice.

Result envelope note

Where the implementation returns debug metadata for servicing operations, prefer a non-breaking optional field:

• debugCorrelationId: String

Staff support servicing additions

adminListAccountsForSupport(input)

Returns a support-oriented list of accounts for staff users with account.read.

Input:

• pagination.pageIndex: Int
• pagination.pageSize: Int
• search: String optional, matched against customer id, account id, account number, and masked account number tail

Output item fields:

• id
• customerId
• accountNumber
• maskedAccountNumber
• accountType
• productName
• currency
• status
• availableBalance
• currentBalance
• lastTransactionAt
• recentTransactionCount

adminGetAccountSupportDetail(input)

Returns a support detail payload for a specific account.

Input:

• accountId: String!

Output fields:

• account — enriched account object
• recentTransactions[]
• recentTransfers[]
• recentNotifications[]
• recentAuditLogs[]
• availableStatusTransitions[]

Behavior:

• requires account.read
• only returns read-only context plus allowed next statuses for the current account state

adminUpdateAccountStatus(input)

Updates an account status from the support workspace.

Input:

• accountId: String!
• targetStatus: AccountStatus!
• reason: String!

Output:

• standard result envelope
• data contains the refreshed support detail payload

Validation:

• requires account.manage
• reason must be non-empty after trim
• allowed transitions only:
  • ACTIVE -> FROZEN
  • FROZEN -> ACTIVE
  • ACTIVE -> CLOSED
  • FROZEN -> CLOSED
• CLOSED cannot transition further in this slice
• idempotent when target status already matches current status

Permissions note

• account.read gates support read access
• account.manage gates support servicing mutations

Error semantics

Common failure cases:

• card not found
• notification not found
• card not eligible for requested state transition
• spending limit outside allowed range
• authenticated user does not own the resource
• account not found for support detail
• staff user lacks account.manage for account servicing
• reason missing for status change
• requested account status transition not allowed

Error messaging goal:

• concise
• safe
• customer-readable for customer flows
• operator-readable for staff flows
• no internal secret leakage