Add 200/PROCESSING (WalletOperationProcessing) response to all 6 still-processing Global Accounts endpoints by carsonp6 · Pull Request #850 · lightsparkdev/grid-api

carsonp6 · 2026-08-20T01:15:58Z

Summary

Grid's embedded-wallet auth endpoints forward to Turnkey, whose consensus- or approval-gated activities are only optimistically synchronous. This adds a documented 200/PROCESSING response option so a still-in-flight activity doesn't have to surface as a 5xx:

POST /auth/credentials (add credential): new 200 response, body WalletOperationProcessing (status: "PROCESSING"). Client re-sends the byte-identical stamped retry (same Request-Id) until the credential is added.
POST /auth/credentials/{id}/challenge (re-issue challenge): 200 response widened from a bare AuthCredentialResponseOneOf to a new AuthCredentialChallengeResponse wrapper — anyOf: [AuthCredentialResponseOneOf, WalletOperationProcessing] — so a still-processing OTP send is now representable.

WalletOperationProcessing is placed in components/schemas/common/ (not auth/) because upcoming PRs reuse the identical shape on other Embedded Wallet endpoints (contact update, session refresh, OTP verify) as part of the Turnkey sync-state-machine work (SP-3579).

anyOf rather than oneOf on AuthCredentialChallengeResponse: WalletOperationProcessing's status field isn't a discriminator shared with AuthCredentialResponseOneOf's type field, so a discriminated oneOf doesn't fit — this repo's spectral rules require a discriminator on every oneOf and flag inline (non-$ref) response schemas, both satisfied here.

Test plan

make build — rebundled openapi.yaml + mintlify/openapi.yaml from openapi/ sources, committed
make lint — 0 errors (was 2: no-inline-response-schema, oneOf-must-have-discriminator, both fixed by wrapping in a named $refd anyOf schema instead of an inline oneOf); remaining warnings/infos are pre-existing and unrelated to this change

This is the first step of a grid-api-first rollout: after this merges, the webdev repo's vendored grid-api/ Python client gets regenerated (update_schema.sh) in a separate PR, bumping packageVersion, before any consumer code lands on top.

🤖 Generated with Claude Code

PATCH /customers excised — contact updates move to dedicated contact-changes endpoints (design in progress).

…d challenge endpoints Grid's embedded-wallet auth endpoints forward to Turnkey, whose consensus- or approval-gated activities are only optimistically synchronous. When the underlying activity is still in flight, POST /auth/credentials and POST /auth/credentials/{id}/challenge now document a 200 response carrying a WalletOperationProcessing body (status: "PROCESSING") instead of forcing a 5xx or blocking — the client re-sends the byte-identical request until the operation settles, and the backend reconciles it to terminal on its own. WalletOperationProcessing lives in components/schemas/common since follow-on endpoints (contact update, session refresh, OTP verify) will reuse the same shape. The challenge endpoint's prior single-schema 200 response becomes an anyOf-wrapped AuthCredentialChallengeResponse (not a discriminated oneOf — WalletOperationProcessing has no shared discriminator field with AuthCredentialResponseOneOf's `type`). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

mintlify · 2026-08-20T01:16:01Z

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

Project	Status	Preview	Updated (UTC)
Grid	🟢 Ready	View Preview	Aug 20, 2026, 1:17 AM

vercel · 2026-08-20T01:16:04Z

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

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
grid-flow-builder	Ignored	Preview	Aug 21, 2026 1:02am
grid-wallet-demo	Ignored	Preview	Aug 21, 2026 1:02am

github-actions · 2026-08-20T01:16:39Z

✱ Stainless preview builds for grid

This PR will update the grid SDKs with the following commit messages.

cli

chore(internal): regenerate SDK with no functional changes

go

fix(types): correct return types for auth credentials new and challenge methods

kotlin

fix(types): update credential create and challenge return types

openapi

feat(api): add processing status responses to auth credentials create/challenge

php

feat(api): add WalletOperationProcessing, CredentialNewResponse to credentials methods

python

fix(types): update create and challenge return types in auth credentials

ruby

feat(api): add CredentialCreateResponse/CredentialChallengeResponse to auth credentials

typescript

fix(api): correct create/challenge return types in credentials

Edit this comment to update them. They will appear in their respective SDK's changelogs.

✅ grid-typescript studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → build ✅ → lint ❗ → test ✅
npm install https://pkg.stainless.com/s/grid-typescript/31fabb680bfab0d910f21e00430a67fff8a5f769/dist.tar.gz
New diagnostics (1 note)

💡 Model/Recommended: We recommend you use a model for `#/components/schemas/WalletOperationProcessing`

✅ grid-openapi studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️

New diagnostics (1 note)

💡 Model/Recommended: We recommend you use a model for `#/components/schemas/WalletOperationProcessing`

✅ grid-ruby studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → build ✅ → lint ✅ → test ✅

New diagnostics (1 note)

💡 Model/Recommended: We recommend you use a model for `#/components/schemas/WalletOperationProcessing`

✅ grid-go studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → build ✅ → lint ❗ → test ❗
go get github.com/stainless-sdks/grid-go@ac52e1d17236d248168993c5c824379fd34af792
New diagnostics (9 note)

💡 Model/Recommended: We recommend you use a model for `#/components/schemas/WalletOperationProcessing`

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

✅ grid-kotlin studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → build ✅ → lint ✅ → test ❗

New diagnostics (7 note)

💡 Model/Recommended: We recommend you use a model for `#/components/schemas/WalletOperationProcessing`

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

✅ grid-python studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → build ✅ → lint ❗ → test ❗
pip install https://pkg.stainless.com/s/grid-python/996ca58f71051fd185fd80b148a2285c36dbc05d/grid-0.0.1-py3-none-any.whl
New diagnostics (1 note)

💡 Model/Recommended: We recommend you use a model for `#/components/schemas/WalletOperationProcessing`

✅ grid-php studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → lint ✅ → test ✅

New diagnostics (7 note)

💡 Model/Recommended: We recommend you use a model for `#/components/schemas/WalletOperationProcessing`

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

💡 Schema/EnumHasOneMember: Confirm intentional use of `enum` with single member.

✅ grid-cli studio · code · diff

Your SDK build had at least one new note diagnostic, which is a regression from the base state.
generate ⚠️ → build ❗ → lint ❗ → test ❗

New diagnostics (1 note)

💡 Model/Recommended: We recommend you use a model for `#/components/schemas/WalletOperationProcessing`

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-08-21 01:07:47 UTC

greptile-apps · 2026-08-20T01:18:44Z

Greptile Summary

The PR extends two embedded-wallet authentication contracts so provider activities that remain in flight can return a documented 200 processing response instead of surfacing as server errors.

Adds the reusable WalletOperationProcessing schema with a required PROCESSING status.
Adds a processing response to credential creation.
Widens the credential-challenge response to include normal challenge results or a processing result.
Regenerates the root and Mintlify OpenAPI bundles.

Confidence Score: 5/5

The PR appears safe to merge with no concrete blocking or independently actionable non-blocking issues identified.

The new response branches are structurally distinguishable, references resolve, endpoint-specific retry guidance remains compatible with the documented flows, and both generated bundles consistently reflect the modular source changes.

Important Files Changed

Filename	Overview
openapi/components/schemas/common/WalletOperationProcessing.yaml	Defines a reusable, structurally distinct processing response with required `status: PROCESSING`.
openapi/components/schemas/auth/AuthCredentialChallengeResponse.yaml	Wraps the existing credential challenge response and processing response in an `anyOf` union.
openapi/paths/auth/auth_credentials.yaml	Documents the new processing response and preserves the stamped-retry requirements for credential creation.
openapi/paths/auth/auth_credentials_{id}_challenge.yaml	Widens the successful challenge response contract to represent an in-flight OTP send.
openapi.yaml	Regenerated bundle consistently incorporates the new source schemas and endpoint responses.
mintlify/openapi.yaml	Regenerated documentation bundle remains aligned with the root OpenAPI bundle.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Grid
    participant WalletProvider
    Client->>Grid: POST credential operation
    Grid->>WalletProvider: Submit activity
    alt Activity settled
        WalletProvider-->>Grid: Terminal result
        Grid-->>Client: Success response
    else Activity still in flight
        WalletProvider-->>Grid: Processing
        Grid-->>Client: 200 WalletOperationProcessing
        Client->>Grid: Retry operation
        Grid-->>Client: Terminal result when settled
    end

_{Reviews (1): Last reviewed commit: "feat: add WalletOperationProcessing 200 ..." | Re-trigger Greptile}

…d contact-update Rounds out the 200/PROCESSING contract to the remaining Turnkey sync-SM endpoints (SP-3579), matching the reshape stack's actual return sites: - POST /auth/credentials/{id}/verify (VERIFY_OTP/OTP_LOGIN/OAUTH_LOGIN/ STAMP_LOGIN): 200 widened to a new AuthCredentialVerifyResponse wrapper — anyOf: [AuthSession, WalletOperationProcessing]. - POST /auth/sessions/{id}/refresh (CREATE_READ_WRITE_SESSION): new 200 sibling to the existing 201, single $ref to WalletOperationProcessing (no union needed — 201 is a distinct success code, same shape as the add-credential endpoint from the prior commit). - PATCH /customers/{customerId} (contact-update: email/phone + tied OTP credentials): 200 widened to a new CustomerUpdateResponse wrapper — anyOf: [CustomerOneOf, WalletOperationProcessing]. CustomerOneOf keeps its own discriminator untouched; get/delete on this resource still return CustomerOneOf directly, unaffected. Same anyOf-over-oneOf reasoning as the challenge endpoint: none of AuthSession or CustomerOneOf share a discriminator field with WalletOperationProcessing's `status`, so a discriminated oneOf doesn't fit and this repo's spectral rules require one on every oneOf. Existing 202 responses on these endpoints are untouched — they signal a different state (client must sign and resubmit a challenge), not "still settling." No inconsistency found across the reshape stack's five endpoint groups (this commit's three plus the prior commit's add-credential and challenge): all uniformly answer still-in-flight activity with 200/PROCESSING, never 202. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

DELETE /auth/credentials/{id} (revokeAuthCredential, DELETE_AUTHENTICATORS / DELETE_OAUTH_PROVIDERS) and DELETE /auth/sessions/{id} (revokeAuthSession, DELETE_API_KEYS) are moving off the older SP-3611 async 202+operationId shape onto the same sync-SM 200/PROCESSING contract as the other 5 reshape endpoints (Carson-approved unification; sparkcore side lands in parallel). Both get a new 200 sibling response, single $ref to common/WalletOperationProcessing — no union needed, matching the add-credential and session-refresh pattern (200 sits alongside a separate terminal code, here 204, not competing with it). The existing 202 (AuthSignedRequestChallenge, the sign-and-resubmit challenge leg) is untouched — that's a different state in the flow and stays as-is. The old still-processing 202+operationId shape was never documented in this spec, so there's nothing to remove. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Grid's Embedded Wallet auth endpoints forward to a wallet provider that is only optimistically synchronous, so the signed-retry step can settle non-terminal instead of completing inline. Document this as the normal case to build for, not a rare edge — it surfaces most when integrators have the most traffic, since provider-side consensus delay under load is exactly when a "rare" response becomes routine. Extends the canonical "signed-retry pattern" section (authentication.mdx, linked from managing-sessions.mdx for session refresh/revoke) with: - the WalletOperationProcessing body shape and what it means - the full list of the 7 endpoints that can return it - how to handle it: re-send the identical original request (not a fresh one), show a pending UI state, and rely on Grid's own reconciliation as a backstop - a callout that verify/challenge/customer-update share their terminal status code (200) with the still-processing response, so those three need a body check where the other four (201/204 terminal) don't Also drops a one-line pointer at each of the 7 endpoints' existing worked examples (add-credential, revoke-credential, verify, challenge, email-change, session refresh, session revoke) so a reader following just one flow still finds it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Tying "still processing" to traffic spikes could read as advice to throttle integrator traffic to avoid triggering it. Keep the "this is the normal path, build for it" framing without linking it to load. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…icated endpoints Removes the WalletOperationProcessing additions from PATCH /customers/{customerId} (the new CustomerUpdateResponse schema, the 200-response description, and the three supporting mentions in the auth guide) so this PR only covers the six auth-credential and auth-session endpoints.

shreyav · 2026-08-21T16:35:07Z

+      content:
+        application/json:
+          schema:
+            $ref: ../../components/schemas/common/WalletOperationProcessing.yaml


should we also send webhooks here so clients dont have to poll? im not sure which resource / id we would send the webhook on tho since theres no id here yet

Good question. Worth splitting by endpoint: for the other 5 of the 6 touched here (challenge/verify, session revoke/refresh), a credential or session id already exists at the point PROCESSING is returned, so a resource-keyed webhook is possible later if we want one. This create-credential endpoint is the one case where there's genuinely no id yet — the credential doesn't exist until the activity settles, so any notification here would have to key off the client's Request-Id rather than a resource id.

Adding webhooks alongside polling for these auth operations is a bigger scope call than this PR (webhook coverage for this surface is being staged separately), so I don't want to fold it in here. Flagging for Carson to weigh in on whether/when to add it rather than deciding unilaterally.

Decision (Carson): staging webhooks separately — we'll likely want them for these ops eventually (the webhook infra already exists), but not in this PR. Polling via the 200/PROCESSING re-send stays the contract here.

ls-bolt · 2026-08-21T16:35:29Z

🦣 Congratulations @shreyav - your substantive review earned a Neosclerocalyptus! (common)

Inflated nasal spaces may have helped this small glyptodont condition cold, dry air.

View your Frost-dex: https://zeus.dev.dev.sparkinfra.net/#/dinodex/shreyav?section=ice-age

mintlify Bot deployed to staging - mintlify August 20, 2026 01:17 View deployment

mintlify Bot deployed to staging - mintlify August 20, 2026 06:36 View deployment

mintlify Bot deployed to staging - mintlify August 20, 2026 07:09 View deployment

mintlify Bot deployed to staging - mintlify August 20, 2026 07:43 View deployment

mintlify Bot deployed to staging - mintlify August 20, 2026 07:50 View deployment

carsonp6 changed the title ~~feat: add WalletOperationProcessing 200 response to add-credential and challenge endpoints~~ Add 200/PROCESSING (WalletOperationProcessing) response to all 7 still-processing Global Accounts endpoints Aug 20, 2026

carsonp6 changed the title ~~Add 200/PROCESSING (WalletOperationProcessing) response to all 7 still-processing Global Accounts endpoints~~ Add 200/PROCESSING (WalletOperationProcessing) response to all 6 still-processing Global Accounts endpoints Aug 21, 2026

mintlify Bot deployed to staging - mintlify August 21, 2026 01:03 View deployment

shreyav reviewed Aug 21, 2026

View reviewed changes

carsonp6 mentioned this pull request Aug 21, 2026

Add contact-changes endpoints for customer email/phone updates #853

Draft

Navigation Menu

Uh oh!

Add 200/PROCESSING (WalletOperationProcessing) response to all 6 still-processing Global Accounts endpoints - #850

Add 200/PROCESSING (WalletOperationProcessing) response to all 6 still-processing Global Accounts endpoints#850
carsonp6 wants to merge 6 commits into
mainfrom
sp3579-wallet-operation-processing

carsonp6 commented Aug 20, 2026 •

edited

Loading

Uh oh!

mintlify Bot commented Aug 20, 2026 •

edited

Loading

Uh oh!

vercel Bot commented Aug 20, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Aug 20, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Aug 20, 2026

Important Files Changed

Sequence Diagram

Uh oh!

shreyav Aug 21, 2026

Uh oh!

carsonp6 Aug 21, 2026

Uh oh!

carsonp6 Aug 21, 2026

Uh oh!

ls-bolt Bot commented Aug 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

carsonp6 commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

github-actions Bot commented Aug 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✱ Stainless preview builds for grid

Uh oh!

greptile-apps Bot commented Aug 20, 2026

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

shreyav Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

carsonp6 Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

carsonp6 Aug 21, 2026

Choose a reason for hiding this comment

Uh oh!

ls-bolt Bot commented Aug 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

carsonp6 commented Aug 20, 2026 •

edited

Loading

mintlify Bot commented Aug 20, 2026 •

edited

Loading

vercel Bot commented Aug 20, 2026 •

edited

Loading

github-actions Bot commented Aug 20, 2026 •

edited

Loading