✨ server: add card limit update handler

[aguxez]

Summary by CodeRabbit

• New Features

  • Added a card-limit case: approved cases can trigger automatic card limit updates (amount applied in cents, weekly frequency) by resolving related inquiry references and updating active cards.
  • Added a new KYC scope "cardLimit" and inquiry flow to create or resume card-limit inquiries.

• Bug Fixes / Reliability

  • Clear response codes and graceful handling for missing data or lookup failures; errors are captured without breaking the webhook.

• Tests

  • Extensive tests covering card-limit flows, ignored inquiries, edge cases, and failure modes.

• Chores

  • Added patch release metadata.

---

---

This is part 1 of 2 in a stack made with GitButler:

•  2  ✨ app: add card limit kyc flow #903
•  1  ✨ server: add card limit update handler #898 👈

[changeset-bot]

🦋 Changeset detected

Latest commit: 53b9786

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@exactly/server	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new server-side capability to automatically adjust user card limits based on approved cases from the Persona identity verification platform. By integrating a dedicated webhook handler, the system can now process specific Persona events, validate the incoming data, and programmatically update card limits through an external API, streamlining the process of managing user financial controls.

Highlights

• New Persona Webhook Handler: Implemented a new webhook handler for Persona events specifically designed to process 'card limit' cases. This handler will update card limits in the system based on approved Persona cases.
• Card Limit Update Logic: Added logic to extract the new card limit from approved Persona cases, retrieve associated credential and card information from the database, and then call an external service (updateCard in Panda) to apply the new limit.
• Enhanced Validation and Error Handling: Introduced new validation schemas for the 'card limit' case template and inquiry template. The handler includes robust error handling for scenarios like missing card limits, credentials, or active cards, and captures exceptions using Sentry.
• Comprehensive Test Coverage: Added extensive unit tests to cover various scenarios for the new card limit update handler, including successful updates, handling of declined cases, missing data, and API failures.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

Adds a new "cardLimit" Persona case flow: validation and template checks, inquiry fetch to obtain a reference-id, DB lookups for credential and active card, and conditional Panda card limit updates; includes new persona constants, helper, API handling, tests, and a changeset.

Changes

Cohort / File(s)	Summary
Changesets & Release \.changeset/clear-cobras-sip.md	New changeset declaring a patch release for @exactly/server with note "add card limit case update".
Persona Hook server/hooks/persona.ts	Added cardLimit payload schema branch and handler: Sentry op, short-circuit responses for non-Approved statuses, extract inquiry id, call getInquiryById, DB queries for credential and ACTIVE card, conditional panda.updateCard with amount = cardLimitUsd * 100, and error capture. Also updated ignored-template allowlist handling.
Persona Utilities server/utils/persona.ts	Added exports CARD_LIMIT_CASE_TEMPLATE, CARD_LIMIT_TEMPLATE, and getInquiryById(inquiryId) which performs Persona GET /inquiries/:id and validates presence of data.attributes["reference-id"].
KYC API server/api/kyc.ts	Extended POST body validation to accept scope: "cardLimit" and added control flow for creating/resuming/failing card-limit inquiries using CARD_LIMIT_TEMPLATE. GET query validation also allows "cardLimit".
Tests — Persona Hook server/test/hooks/persona.test.ts	Added comprehensive card limit case test suite, extended "with reference" tests, added mocks (e.g., persona.addDocument), updated invalid-payload expectations, and cleaned up cards rows in afterEach. Covers success, no-card, no-limit, no-credential, no-panda, updateCard failure, and ignored-template paths.
Tests — KYC API server/test/api/kyc.test.ts	Added cardLimit scope tests for POST flow: creating new inquiry, resuming valid statuses, rejecting terminal/failed statuses, unknown credential case, and forwarding redirectURI to createInquiry.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Hook as Persona Hook
    participant Persona as Persona API
    participant DB as Database
    participant Panda as Panda Service

    Client->>Hook: POST webhook (data.type="case", template: cardLimit, status: Approved)
    Hook->>Hook: Validate payload & template
    Hook->>Persona: GET /inquiries/{inquiryId}
    Persona-->>Hook: { data.attributes["reference-id"]: referenceId }
    Hook->>DB: Query credentials where credentials.id = referenceId
    DB-->>Hook: credential { pandaId? }
    Hook->>DB: Query cards where cards.credentialId = referenceId AND status = "ACTIVE"
    DB-->>Hook: card { id } or none
    alt card exists
      Hook->>Panda: updateCard(cardId, { limit: { amount, frequency: "per7DayPeriod" } })
      Panda-->>Hook: success / error
    end
    Hook-->>Client: 200 { code: "ok" } or short-circuit codes ("no limit","no inquiry","no credential","no panda") / 500 on update error

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Suggested reviewers

• cruzdanilo
• nfmelendez

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the primary change: adding a card limit update handler to the server.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch kyc-limit

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sentry]

✅ All tests passed.

[devin-ai-integration]

Devin Review found 2 new potential issues.

View 7 additional findings in Devin Review.

[devin-ai-integration]

🚩 GET and POST handlers return different status codes for failed/declined cardLimit inquiries

The GET handler at server/api/kyc.ts:77-79 returns status 200 for failed/declined cardLimit inquiries, while the POST handler at server/api/kyc.ts:201-202 returns 400 via the default case. This differs from non-cardLimit scopes where both GET and POST return 400 for failed/declined. The tests confirm this is intentional (GET tests assert 200, POST tests assert 400), but this asymmetry could confuse API consumers who expect consistent status codes across GET/POST for the same inquiry state.

---

Was this helpful? React with 👍 or 👎 to provide feedback.