docs: sync documentation with recent OpenAPI schema changes - #851
Open
claude[bot] wants to merge 1 commit into
Open
docs: sync documentation with recent OpenAPI schema changes#851claude[bot] wants to merge 1 commit into
claude[bot] wants to merge 1 commit into
Conversation
- Add COLLECTION_FAILED to incoming payment failure reasons in error handling guide - Document INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED webhook for internal accounts - Add note pointing to recommended client-held-key flow in session refresh docs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 2 Skipped Deployments
|
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
Contributor
Greptile SummaryThis PR synchronizes Mintlify guidance with recent transaction, webhook, and authentication schema changes.
Confidence Score: 4/5The PR needs the client-held-key documentation link corrected before merging; the cache-refresh and wording concerns are non-blocking. The new session guidance points readers to an unregistered snippet route rather than the published client-keys page, while the other changes accurately reflect the schema but would benefit from explicit cache invalidation guidance and clearer active phrasing. Files Needing Attention: mintlify/snippets/global-accounts/managing-sessions.mdx, mintlify/snippets/internal-accounts.mdx, mintlify/snippets/error-handling.mdx
|
| Filename | Overview |
|---|---|
| mintlify/snippets/error-handling.mdx | Adds the schema-backed COLLECTION_FAILED reason, with a minor active-voice violation. |
| mintlify/snippets/global-accounts/managing-sessions.mdx | Correctly describes the client-held-key model but links to a snippet import path instead of the published page. |
| mintlify/snippets/internal-accounts.mdx | Adds the valid funding-instructions webhook but leaves the documented caching lifecycle incomplete and uses passive voice. |
Prompt To Fix All With AI
### Issue 1
mintlify/snippets/global-accounts/managing-sessions.mdx:44
**Broken client-key documentation link**
When a reader follows the new client-held-key recommendation, the link targets the snippet import path rather than the registered public page, causing navigation to a missing route instead of the session-key instructions.
```suggestion
The examples below show the legacy flow with `encryptedSessionSigningKey`. For new integrations, use the recommended [client-held-key flow](/global-accounts/client-keys#client-held-session-key) by sending a compressed `clientPublicKey` (66 hex characters), which avoids the decrypt step entirely.
```
### Issue 2
mintlify/snippets/internal-accounts.mdx:374
**Missing cache invalidation guidance**
The new webhook guidance does not tell readers to refresh cached `fundingPaymentInstructions`; integrations following the same snippet's caching advice can continue displaying withdrawn or outdated deposit coordinates after receiving this event.
```suggestion
You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes. When `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` reports new or withdrawn funding instructions, invalidate any cached `fundingPaymentInstructions` and fetch the account again.
```
### Issue 3
mintlify/snippets/error-handling.mdx:234
**Passive descriptions obscure actors**
The new phrases “funds returned to sender” here and “funding instructions are added or modified” in `internal-accounts.mdx` use passive voice, contrary to the Mintlify writing standard, and obscure who performs these operational actions.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Reviews (1): Last reviewed commit: "docs: sync documentation with recent Ope..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| Session refresh creates a new session signing key from an existing active session. Use this when the customer is still present and the current session is close to expiration. If the session has already expired, reauthenticate with the original credential instead. | ||
|
|
||
| <Note> | ||
| The examples below show the legacy flow with `encryptedSessionSigningKey`. For new integrations, use the recommended [client-held-key flow](/snippets/global-accounts/client-keys#client-held-session-key) by sending a compressed `clientPublicKey` (66 hex characters), which avoids the decrypt step entirely. |
Contributor
There was a problem hiding this comment.
When a reader follows the new client-held-key recommendation, the link targets the snippet import path rather than the registered public page, causing navigation to a missing route instead of the session-key instructions.
Suggested change
| The examples below show the legacy flow with `encryptedSessionSigningKey`. For new integrations, use the recommended [client-held-key flow](/snippets/global-accounts/client-keys#client-held-session-key) by sending a compressed `clientPublicKey` (66 hex characters), which avoids the decrypt step entirely. | |
| The examples below show the legacy flow with `encryptedSessionSigningKey`. For new integrations, use the recommended [client-held-key flow](/global-accounts/client-keys#client-held-session-key) by sending a compressed `clientPublicKey` (66 hex characters), which avoids the decrypt step entirely. |
Knowledge Base Used: Mintlify Documentation Site
Prompt To Fix With AI
This is a comment left during a code review.
Path: mintlify/snippets/global-accounts/managing-sessions.mdx
Line: 44
Comment:
**Broken client-key documentation link**
When a reader follows the new client-held-key recommendation, the link targets the snippet import path rather than the registered public page, causing navigation to a missing route instead of the session-key instructions.
```suggestion
The examples below show the legacy flow with `encryptedSessionSigningKey`. For new integrations, use the recommended [client-held-key flow](/global-accounts/client-keys#client-held-session-key) by sending a compressed `clientPublicKey` (66 hex characters), which avoids the decrypt step entirely.
```
**Knowledge Base Used:** [Mintlify Documentation Site](https://app.greptile.com/lightspark/-/custom-context/knowledge-base/lightsparkdev/grid-api/-/docs/mintlify-docs-site.md)
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.|
|
||
| <Info> | ||
| You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes. | ||
| You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes, and `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` when funding instructions are added or modified. |
Contributor
There was a problem hiding this comment.
The new webhook guidance does not tell readers to refresh cached fundingPaymentInstructions; integrations following the same snippet's caching advice can continue displaying withdrawn or outdated deposit coordinates after receiving this event.
Suggested change
| You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes, and `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` when funding instructions are added or modified. | |
| You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes. When `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` reports new or withdrawn funding instructions, invalidate any cached `fundingPaymentInstructions` and fetch the account again. |
Prompt To Fix With AI
This is a comment left during a code review.
Path: mintlify/snippets/internal-accounts.mdx
Line: 374
Comment:
**Missing cache invalidation guidance**
The new webhook guidance does not tell readers to refresh cached `fundingPaymentInstructions`; integrations following the same snippet's caching advice can continue displaying withdrawn or outdated deposit coordinates after receiving this event.
```suggestion
You'll receive `INTERNAL_ACCOUNT.BALANCE_UPDATED` webhook events when the internal account balance changes. When `INTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATED` reports new or withdrawn funding instructions, invalidate any cached `fundingPaymentInstructions` and fetch the account again.
```
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.| - `PAYMENT_APPROVAL_WEBHOOK_ERROR` - Webhook returned an error | ||
| - `OFFRAMP_FAILED` - Failed to convert and send funds to destination | ||
| - `QUOTE_EXPIRED` - Quote expired during processing | ||
| - `COLLECTION_FAILED` - Inbound bank-rail collection deposit failed after arrival and did not credit; funds returned to sender |
Contributor
There was a problem hiding this comment.
The new phrases “funds returned to sender” here and “funding instructions are added or modified” in internal-accounts.mdx use passive voice, contrary to the Mintlify writing standard, and obscure who performs these operational actions.
Context Used: mintlify/AGENTS.md (source)
Prompt To Fix With AI
This is a comment left during a code review.
Path: mintlify/snippets/error-handling.mdx
Line: 234
Comment:
**Passive descriptions obscure actors**
The new phrases “funds returned to sender” here and “funding instructions are added or modified” in `internal-accounts.mdx` use passive voice, contrary to the Mintlify writing standard, and obscure who performs these operational actions.
**Context Used:** mintlify/AGENTS.md ([source](https://github.com/lightsparkdev/grid-api/blob/main/mintlify/AGENTS.md))
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.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!
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
COLLECTION_FAILEDto incoming payment failure reasons in error handling guideINTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATEDwebhook for internal accountsContext
These updates sync the documentation with recent OpenAPI schema changes from the past 24 hours:
COLLECTION_FAILEDfailure reason and new webhook typeencryptedSessionSigningKeyin favor of client-held-key flowFiles Changed
mintlify/snippets/error-handling.mdxCOLLECTION_FAILEDincoming failure reasonmintlify/snippets/internal-accounts.mdxINTERNAL_ACCOUNT.FUNDING_INSTRUCTIONS_UPDATEDwebhook mentionmintlify/snippets/global-accounts/managing-sessions.mdxTest plan
make mint🤖 Generated with Claude Code