✨ server: add wallet provisioning endpoint

[aguxez]

Closes #440

---

Summary by CodeRabbit

• New Features

  • Added a wallet provisioning endpoint allowing authenticated users to retrieve provisioning details (card ID and time-based secret) for an eligible card.

• Tests

  • Added comprehensive tests for successful provisioning, processor error mappings, deleted/missing card, missing external association, and missing credential scenarios.

• Chores

  • Added a changeset declaring a patch release documenting the new wallet provisioning endpoint.

[changeset-bot]

🦋 Changeset detected

Latest commit: e5b5193

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

[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 authenticated GET /wallet endpoint that loads a credential's ACTIVE|FROZEN card, calls Panda for processor details, returns processorCardId/timeBasedSecret, adds a Panda utility, tests covering success and error mappings, and adds a changeset for a patch release.

Changes

Cohort / File(s)	Summary
Wallet Endpoint server/api/card.ts	New authenticated GET /wallet route: reads credentialId from cookie, loads credential (pandaId + first `ACTIVE
Panda Utility server/utils/panda.ts	Added exported getProcessorDetails(cardId: string) which GETs /issuing/cards/${cardId}/processorDetails and validates/returns { processorCardId, timeBasedSecret }.
Tests server/test/api/card.test.ts	Added wallet test suite seeding credentials/cards and asserting: success for active/frozen cards (200 with processor details and stub verification), Panda error mappings (404→404 { code: "no card" }, 5xx→500), and credential/panda/card absence responses (500/403/404 as appropriate).
Release Metadata .changeset/chilly-suns-dress.md	New changeset declaring a patch release for @exactly/server referencing the wallet provisioning endpoint.

Sequence Diagram(s)

sequenceDiagram
    autonumber
    participant Client
    participant API as GET /wallet
    participant DB as Database
    participant Panda as Panda API

    Client->>API: GET /wallet (credentialId cookie)
    API->>DB: Load credential (pandaId, first ACTIVE|FROZEN card)
    alt no credential
        DB-->>API: not found
        API-->>Client: 500 { code: "no credential" }
    else credential missing pandaId
        DB-->>API: credential (no pandaId)
        API-->>Client: 403 { code: "no panda" }
    else no eligible card
        DB-->>API: credential (no eligible card)
        API-->>Client: 404 { code: "no card" }
    else credential + card found
        DB-->>API: credential + cardId
        API->>Panda: GET /issuing/cards/{cardId}/processorDetails
        alt processor details found
            Panda-->>API: { processorCardId, timeBasedSecret }
            API-->>Client: 200 { cardId, cardSecret }
        else processor 404
            Panda-->>API: 404
            API-->>Client: 404 { code: "no card" }
        else other error
            Panda-->>API: error
            API-->>Client: 500 (error)
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• 🔖 release: server@0.2.68 #793 — Related: also adds GET /wallet and the panda.getProcessorDetails helper.
• 🥅 server: handle no panda user on card create #791 — Related: adjusts server/api/card.ts error handling for missing panda/user and card cases.

Suggested reviewers

• cruzdanilo
• nfmelendez

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'add wallet provisioning endpoint' accurately and directly describes the main change: a new authenticated GET /wallet endpoint for wallet provisioning. It is specific, clear, and concise without unnecessary details.
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 server-provisioning

---

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]

Codecov Report

❌ Patch coverage is 91.83673% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 73.75%. Comparing base (adf8f7d) to head (e5b5193).
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
server/api/card.ts	91.83%	2 Missing and 2 partials ⚠️

Additional details and impacted files

@@              Coverage Diff              @@
##           signature     #949      +/-   ##
=============================================
+ Coverage      71.32%   73.75%   +2.42%     
=============================================
  Files            228      229       +1     
  Lines           8447     9284     +837     
  Branches        2716     3097     +381     
=============================================
+ Hits            6025     6847     +822     
+ Misses          2188     2174      -14     
- Partials         234      263      +29     

Flag	Coverage Δ
e2e	73.75% <91.83%> (+22.99%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

♻️ Duplicate comments (1)

server/test/api/card.test.ts (1)

867-869: ⚠️ Potential issue | 🟡 Minor

Use Panda in the mocked ServiceError for consistency.

"Rain" works, but using the real provider label keeps test fixtures closer to production behavior.

Suggested fix

-      vi.spyOn(panda, "getProcessorDetails").mockRejectedValueOnce(new ServiceError("Rain", 500, "internal error"));
+      vi.spyOn(panda, "getProcessorDetails").mockRejectedValueOnce(new ServiceError("Panda", 500, "internal error"));

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 7e528c82-bb28-42c9-8cd9-b0f075ed5b87

📥 Commits

Reviewing files that changed from the base of the PR and between 0ed88f7 and ba4376c.

📒 Files selected for processing (4)

• .changeset/chilly-suns-dress.md
• server/api/card.ts
• server/test/api/card.test.ts
• server/utils/panda.ts

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4fafee0c5e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Guard stale PAN lookup in provisioning path

The new stale-card mapping only wraps getProcessorDetails(), but getSecrets() in the same Promise.all is still unhandled. When Panda has already removed a card, getSecrets() can return 404 first, which rejects the whole request and bypasses the intended { code: "no card" } response for scope=provisioning, producing an unexpected server error instead. This makes stale-card behavior timing-dependent in the new provisioning flow.

Useful? React with 👍 / 👎.

[aguxez]

this is uncertain right now. on purpose, the only provisioning-specific call that maps these failures to 404 { code: "no card" } is getProcessorDetails().

so i’m leaving this thread open as the current design boundary rather than resolving it as addressed.