regenerate-sdk

name	regenerate-sdk
description	Regenerate the Rust SDK from the OpenAPI spec, fix breaking changes, produce a changelog, and run validation

/regenerate-sdk - Regenerate the Rust SDK

Regenerates the SDK from Privy's OpenAPI spec, produces a changelog with breaking change analysis, fixes compilation errors in wrapper code, and validates the result.

Before starting, familiarize yourself with:

• .mise.toml — the pull-openapi and gen-openapi task definitions
• scripts/schema-patches/ — jq patches applied to the raw spec before code generation
• build.rs — orchestrates progenitor code generation and subclient extraction
• allowlist.yml — maps OpenAPI operationIds to Rust method names

Step 1: Regenerate the SDK

Run the mise task to fetch the latest spec, apply patches, and regenerate:

mise run gen-openapi

This runs two sub-tasks:

1. pull-openapi — fetches https://api.privy.io/v1/openapi.json and pipes it through all scripts/schema-patches/*.jq files in order, outputting openapi.json
2. gen-openapi — runs cargo-progenitor (nightly) to regenerate crates/privy-openapi/src/lib.rs

If this fails

Common failure modes:

• jq patch error: The upstream spec structure changed in a way that breaks a patch. Inspect the failing patch and the raw spec to determine what changed. You may need to update or add a new patch.
• Progenitor panic: The spec contains a pattern progenitor can't handle (e.g. multiple response types, missing responses field, unsupported OpenAPI features). You may need to add a new schema patch to work around it.

Surface the error output to the developer and stop if you cannot resolve it.

Step 2: Analyze the diff and produce a changelog

After regeneration, analyze what changed:

1. Run git diff focusing on:

   • crates/privy-openapi/src/lib.rs — the generated types and client code
   • openapi.json — the processed spec (new endpoints, changed schemas)

2. Run git status to check for newly added or deleted files.

3. Create a changelog with these sections:

   Added

   New types, structs, enums, enum variants, fields, endpoints, or methods.

   Changed

   Modified type names, field types, struct fields, enum variants, method signatures.

   Removed

   Deleted types, fields, endpoints, enum variants, or methods.

4. Flag items as BREAKING if they would cause existing code using the SDK to fail compilation:

   • Removed or renamed public structs/enums/types
   • Changed struct field names or types
   • New required fields on structs (fields that don't have a default and aren't Option<T>)
   • Removed or renamed enum variants
   • Changed method signatures (parameter types, return types, parameter count)
   • Renamed newtype wrappers

   Format: - **BREAKING**: Description of what changed

5. Append the changelog to MANUAL_CHANGELOG.md (NOT CHANGELOG.md — that is auto-generated by release-plz). Add a new date-stamped heading: ## YYYY-MM-DD — OpenAPI Regeneration. If the file doesn't exist yet, create it with the standard header comment (see existing file for format).

6. Output the full changelog to the developer for review.

Step 3: Fix breaking changes in wrapper code

Attempt to compile the project:

cargo clippy --all-targets --all-features -- -D warnings

If compilation fails

1. Parse the compiler errors and identify which breaking changes from the changelog caused them.

2. Fix the hand-written wrapper code to match the new generated types. Files that typically need updates:

   • src/ethereum.rs — Ethereum wallet operation helpers and doc examples
   • src/solana.rs — Solana wallet operation helpers and doc examples
   • src/subclients/wallets.rs — Wallet CRUD wrappers
   • src/subclients/policies.rs — Policy operation wrappers
   • src/subclients/key_quorums.rs — Key quorum operation wrappers
   • src/utils.rs — Authorization signature generation
   • src/import.rs — Key import utilities
   • tests/ — Integration test files
   • examples/ — Example files

3. Common fix patterns:

   • Type renames: Update all references to the new name
   • New Option fields: Add field_name: None to struct literals
   • Newtype wrappers for strings: Use .parse().unwrap() or .into() instead of bare string literals
   • Enum variant renames: Update match arms and constructors
   • New required fields: Add the field with an appropriate value
   • Doc example failures: Update code in /// doc comments to use new types

4. Re-run clippy after each round of fixes. Repeat until it passes cleanly.

If compilation succeeds

Proceed to Step 4.

Step 4: Run tests

Run the integration tests:

cargo test --verbose

If compilation fails (before tests run)

Go back to Step 3 — there are remaining type mismatches in test code.

If tests fail at runtime

1. Surface the test failure details (test name, assertion message, error output).
2. Determine if the failure is due to:
   • A code bug introduced during the fix-up (fix it)
   • An upstream API behavior change (inform the developer)
   • A flaky test / network issue (retry)
3. Ask the developer how to proceed if unclear.

If all tests pass

Report success. The regeneration is complete.

Step 5: Update changelog with fixes

If hand-written wrapper code was modified during Step 3:

1. Review what changed with git diff on the non-generated files.
2. Add a Custom Fixes sub-section to the regeneration entry in MANUAL_CHANGELOG.md documenting:
   • Which wrapper files were modified
   • What was fixed and why (e.g. "Updated src/ethereum.rs to use Quantity instead of removed EthereumSign7702AuthorizationRpcInputParamsChainId")
3. Output the updated changelog to the developer.

Notes

• The generated file crates/privy-openapi/src/lib.rs is ~7MB. Focus diff analysis on structural changes (new/removed types, changed fields) rather than line-by-line review.
• build.rs also generates code at compile time ($OUT_DIR/codegen.rs and $OUT_DIR/subclients.rs). If allowlist.yml references operationIds that no longer exist, compilation will fail there.
• Schema patches are numbered and run in order. If you need to add a new patch, use the next available number.
• CHANGELOG.md is fully managed by release-plz — do NOT edit it manually. Use MANUAL_CHANGELOG.md for detailed regeneration notes.