docs: sync card documentation with PENDING_AUTH state by claude[bot] · Pull Request #606 · lightsparkdev/grid-api

claude · 2026-06-19T09:41:48Z

Summary

Updates card lifecycle documentation to include the new PENDING_AUTH state added in docs(openapi): document card pending auth state #591 and add card-scoped /auth/delegated-keys endpoints #574
Cards backed by Embedded Wallet funding sources now enter PENDING_AUTH until delegated key authorization is completed via POST /auth/delegated-keys

Changes

mintlify/snippets/cards/intro.mdx

Added PENDING_AUTH to the card lifecycle table (5 → 6 states)

mintlify/snippets/cards/issuing-cards.mdx

Updated ASCII state diagram to show PENDING_AUTH in the lifecycle flow
Added PENDING_AUTH to the state table with description

mintlify/snippets/cards/webhooks.mdx

Updated CARD.STATE_CHANGE event triggers to include PENDING_AUTH transitions

Test plan

Verify card intro page renders correctly with 6-state table
Verify issuing-cards page shows updated lifecycle diagram
Verify webhooks page accurately describes state change triggers

🤖 Generated with Claude Code

Sync Mintlify card documentation with OpenAPI schema changes from commits 5ebb4e0 and ea40e01. Cards backed by Embedded Wallet funding sources now enter PENDING_AUTH state until delegated key authorization is completed via POST /auth/delegated-keys. Updated: - Card lifecycle table in intro snippet (5 → 6 states) - State diagram and table in issuing-cards snippet - Webhook event trigger list in webhooks snippet Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

vercel · 2026-06-19T09:41:49Z

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored		Jun 19, 2026 9:41am
grid-wallet-demo	Ignored		Jun 19, 2026 9:41am

mintlify · 2026-06-19T09:42:07Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Jun 19, 2026, 9:44 AM

greptile-apps · 2026-06-19T09:45:09Z

Greptile Summary

This PR syncs the card documentation with the PENDING_AUTH state introduced for Embedded Wallet-backed cards. The webhooks page is updated cleanly, but the lifecycle diagram and intro table each have an ordering or completeness issue that could mislead developers.

issuing-cards.mdx: The ASCII diagram now shows PROCESSING → PENDING_AUTH → ACTIVE as the only path, silently dropping the direct PROCESSING → ACTIVE route used by all non-Embedded Wallet cards. The state table below the diagram says PENDING_AUTH "only appears for Embedded Wallet-funded cards," directly contradicting the diagram.
intro.mdx: PENDING_AUTH is inserted before PROCESSING in the lifecycle table, reversing the actual chronological order (a card enters PENDING_AUTH only after leaving PROCESSING).
webhooks.mdx: The CARD.STATE_CHANGE trigger list is correctly extended with PROCESSING → PENDING_AUTH and PENDING_AUTH → ACTIVE; no issues here.

Confidence Score: 3/5

The lifecycle diagram misrepresents the card flow for the common non-Embedded Wallet case, which is worth fixing before publishing.

The ASCII diagram in issuing-cards.mdx drops the direct PROCESSING → ACTIVE path, making PENDING_AUTH appear mandatory for all cards when it is only conditional on Embedded Wallet funding sources. A developer reading the diagram without the fine-print table note would implement unnecessary polling or auth logic for every card issuance. The intro table ordering issue compounds the confusion. Both are straightforward to fix but should be addressed before the docs go live.

mintlify/snippets/cards/issuing-cards.mdx — the ASCII diagram needs a direct PROCESSING → ACTIVE branch for non-Embedded Wallet cards

Important Files Changed

Filename	Overview
mintlify/snippets/cards/issuing-cards.mdx	ASCII lifecycle diagram now routes all cards through PENDING_AUTH, dropping the direct PROCESSING → ACTIVE path used by non-Embedded Wallet cards; state table text is accurate but contradicts the diagram.
mintlify/snippets/cards/intro.mdx	PENDING_AUTH row inserted before PROCESSING in the lifecycle table, breaking the sequential lifecycle order shown in issuing-cards.mdx.
mintlify/snippets/cards/webhooks.mdx	CARD.STATE_CHANGE triggers correctly extended with PROCESSING → PENDING_AUTH and PENDING_AUTH → ACTIVE transitions; no issues found.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[POST /cards] --> B[PROCESSING]
    B -->|"Non-Embedded Wallet card"| D[ACTIVE]
    B -->|"Embedded Wallet card"| C[PENDING_AUTH]
    B -->|"Issuer rejects provisioning"| F[CLOSED]
    C -->|"POST /auth/delegated-keys completed"| D
    C --> F
    D --> E[FROZEN]
    E --> D
    D --> F

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[POST /cards] --> B[PROCESSING]
    B -->|"Non-Embedded Wallet card"| D[ACTIVE]
    B -->|"Embedded Wallet card"| C[PENDING_AUTH]
    B -->|"Issuer rejects provisioning"| F[CLOSED]
    C -->|"POST /auth/delegated-keys completed"| D
    C --> F
    D --> E[FROZEN]
    E --> D
    D --> F

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
mintlify/snippets/cards/issuing-cards.mdx:34-41
**Direct `PROCESSING → ACTIVE` path missing from lifecycle diagram**

The new diagram routes all cards through `PENDING_AUTH`, but the state table directly below (and the webhooks page) confirm that `PENDING_AUTH` _"only appears for Embedded Wallet-funded cards."_ Regular cards still follow `PROCESSING → ACTIVE` directly. Any developer who reads this diagram first will conclude that `PENDING_AUTH` is mandatory for every card, which contradicts the conditional path described in the text.

### Issue 2 of 2
mintlify/snippets/cards/intro.mdx:27-29
The table in `intro.mdx` lists states in lifecycle order (PENDING_KYC → PROCESSING → ACTIVE → FROZEN → CLOSED), but `PENDING_AUTH` has been inserted between `PENDING_KYC` and `PROCESSING`. In the actual lifecycle, `PENDING_AUTH` occurs after `PROCESSING` — as correctly shown in the `issuing-cards.mdx` state table. Placing it before `PROCESSING` here will confuse developers trying to map the sequence.

```suggestion
| `PENDING_KYC` | Cardholder has not finished KYC; the card cannot transact yet. |
| `PROCESSING` | Card has been requested and is being provisioned with the issuer. |
| `PENDING_AUTH` | Card is backed by an Embedded Wallet funding source and the cardholder has not yet completed delegated signing authorization via `POST /auth/delegated-keys`. The card cannot transact. |
```

_{Reviews (1): Last reviewed commit: "docs: add PENDING_AUTH state to card doc..." | Re-trigger Greptile}

greptile-apps · 2026-06-19T09:45:13Z

 ```text
-PROCESSING    ──► ACTIVE ──► FROZEN ──► ACTIVE ──► CLOSED
-       │             │                              ▲
-       │             └──────────────────────────────┘
+PROCESSING    ──► PENDING_AUTH ──► ACTIVE ──► FROZEN ──► ACTIVE ──► CLOSED
+       │               │              │                              ▲
+       │               │              └──────────────────────────────┘
+       │               └──────────────────────────────────────────────┘
       │
       └─► CLOSED (stateReason: ISSUER_REJECTED)
 ```


Direct PROCESSING → ACTIVE path missing from lifecycle diagram

The new diagram routes all cards through PENDING_AUTH, but the state table directly below (and the webhooks page) confirm that PENDING_AUTH "only appears for Embedded Wallet-funded cards." Regular cards still follow PROCESSING → ACTIVE directly. Any developer who reads this diagram first will conclude that PENDING_AUTH is mandatory for every card, which contradicts the conditional path described in the text.

Prompt To Fix With AI

This is a comment left during a code review. Path: mintlify/snippets/cards/issuing-cards.mdx Line: 34-41 Comment: **Direct `PROCESSING → ACTIVE` path missing from lifecycle diagram** The new diagram routes all cards through `PENDING_AUTH`, but the state table directly below (and the webhooks page) confirm that `PENDING_AUTH` _"only appears for Embedded Wallet-funded cards."_ Regular cards still follow `PROCESSING → ACTIVE` directly. Any developer who reads this diagram first will conclude that `PENDING_AUTH` is mandatory for every card, which contradicts the conditional path described in the text. How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

greptile-apps · 2026-06-19T09:45:14Z

 | `PENDING_KYC` | Cardholder has not finished KYC; the card cannot transact yet. |
+| `PENDING_AUTH` | Card is backed by an Embedded Wallet funding source and the cardholder has not yet completed delegated signing authorization via `POST /auth/delegated-keys`. The card cannot transact. |
 | `PROCESSING` | Card has been requested and is being provisioned with the issuer. |


The table in intro.mdx lists states in lifecycle order (PENDING_KYC → PROCESSING → ACTIVE → FROZEN → CLOSED), but PENDING_AUTH has been inserted between PENDING_KYC and PROCESSING. In the actual lifecycle, PENDING_AUTH occurs after PROCESSING — as correctly shown in the issuing-cards.mdx state table. Placing it before PROCESSING here will confuse developers trying to map the sequence.

Suggested change

| `PENDING_KYC` | Cardholder has not finished KYC; the card cannot transact yet. |

| `PENDING_AUTH` | Card is backed by an Embedded Wallet funding source and the cardholder has not yet completed delegated signing authorization via `POST /auth/delegated-keys`. The card cannot transact. |

| `PROCESSING` | Card has been requested and is being provisioned with the issuer. |

| `PENDING_KYC` | Cardholder has not finished KYC; the card cannot transact yet. |

| `PROCESSING` | Card has been requested and is being provisioned with the issuer. |

| `PENDING_AUTH` | Card is backed by an Embedded Wallet funding source and the cardholder has not yet completed delegated signing authorization via `POST /auth/delegated-keys`. The card cannot transact. |

Prompt To Fix With AI

This is a comment left during a code review. Path: mintlify/snippets/cards/intro.mdx Line: 27-29 Comment: The table in `intro.mdx` lists states in lifecycle order (PENDING_KYC → PROCESSING → ACTIVE → FROZEN → CLOSED), but `PENDING_AUTH` has been inserted between `PENDING_KYC` and `PROCESSING`. In the actual lifecycle, `PENDING_AUTH` occurs after `PROCESSING` — as correctly shown in the `issuing-cards.mdx` state table. Placing it before `PROCESSING` here will confuse developers trying to map the sequence. ```suggestion | `PENDING_KYC` | Cardholder has not finished KYC; the card cannot transact yet. | | `PROCESSING` | Card has been requested and is being provisioned with the issuer. | | `PENDING_AUTH` | Card is backed by an Embedded Wallet funding source and the cardholder has not yet completed delegated signing authorization via `POST /auth/delegated-keys`. The card cannot transact. | ``` How can I resolve this? If you propose a fix, please make it concise.

claude Bot requested review from pengying and shreyav June 19, 2026 09:41

mintlify Bot deployed to staging - mintlify June 19, 2026 09:44 View deployment

greptile-apps Bot reviewed Jun 19, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: sync card documentation with PENDING_AUTH state#606

docs: sync card documentation with PENDING_AUTH state#606
claude[bot] wants to merge 1 commit into
mainfrom
docs/sync-20260619

claude Bot commented Jun 19, 2026

Uh oh!

vercel Bot commented Jun 19, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Jun 19, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Jun 19, 2026

Important Files Changed

Flowchart

Uh oh!

greptile-apps Bot Jun 19, 2026

Uh oh!

greptile-apps Bot Jun 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

Conversation

claude Bot commented Jun 19, 2026

Summary

Changes

Test plan

Uh oh!

vercel Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mintlify Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps Bot commented Jun 19, 2026

Greptile Summary

Confidence Score: 3/5

Important Files Changed

Flowchart

Uh oh!

greptile-apps Bot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Jun 19, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

vercel Bot commented Jun 19, 2026 •

edited

Loading

mintlify Bot commented Jun 19, 2026 •

edited

Loading