Reviewing files that changed from the base of the PR and between 72fa446 and b135de7.

• openapi.yaml is excluded by !**/*.yaml
• openapi/v1.yaml is excluded by !**/*.yaml
• openapi/v2.yaml is excluded by !**/*.yaml
• pkg/client/.speakeasy/gen.lock is excluded by !**/*.lock, !**/*.lock
• pkg/client/.speakeasy/gen.yaml is excluded by !**/*.yaml
• pkg/client/go.mod is excluded by !**/*.mod
• pkg/client/go.sum is excluded by !**/*.sum, !**/*.sum
• tools/generator/go.mod is excluded by !**/*.mod
• tools/provisioner/go.mod is excluded by !**/*.mod
• tools/provisioner/go.sum is excluded by !**/*.sum, !**/*.sum

• docs/api/README.md (14 hunks)
• flake.nix (1 hunks)
• pkg/client/.gitignore (1 hunks)
• pkg/client/README.md (14 hunks)
• pkg/client/USAGE.md (1 hunks)
• pkg/client/docs/models/components/errorresponse.md (1 hunks)
• pkg/client/docs/models/components/security.md (1 hunks)
• pkg/client/docs/models/components/v2errorresponse.md (1 hunks)
• pkg/client/docs/models/operations/addmetadataontransactionrequest.md (1 hunks)
• pkg/client/docs/models/operations/listaccountsresponse.md (1 hunks)
• pkg/client/docs/models/operations/v2addmetadataontransactionrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2countaccountsrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2counttransactionsrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2createbulkrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2createledgerrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2getbalancesaggregatedrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2getinforesponse.md (1 hunks)
• pkg/client/docs/models/operations/v2getvolumeswithbalancesrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2importlogsrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2listaccountsrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2listlogsrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2listtransactionsrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2updateledgermetadatarequest.md (1 hunks)
• pkg/client/docs/models/operations/v2updateledgermetadataresponse.md (1 hunks)
• pkg/client/docs/models/sdkerrors/errorresponse.md (0 hunks)
• pkg/client/docs/models/sdkerrors/v2errorresponse.md (0 hunks)
• pkg/client/docs/sdks/formance/README.md (0 hunks)
• pkg/client/docs/sdks/ledger/README.md (5 hunks)
• pkg/client/docs/sdks/v1/README.md (46 hunks)
• pkg/client/docs/sdks/v2/README.md (53 hunks)
• pkg/client/formance.go (2 hunks)
• pkg/client/internal/hooks/clientcredentials.go (8 hunks)
• pkg/client/internal/hooks/hooks.go (1 hunks)
• pkg/client/internal/utils/env.go (1 hunks)
• pkg/client/internal/utils/form.go (1 hunks)
• pkg/client/internal/utils/json.go (2 hunks)
• pkg/client/internal/utils/queryparams.go (5 hunks)
• pkg/client/internal/utils/requestbody.go (7 hunks)
• pkg/client/internal/utils/retries.go (5 hunks)
• pkg/client/internal/utils/security.go (7 hunks)
• pkg/client/internal/utils/utils.go (6 hunks)
• pkg/client/ledger.go (9 hunks)
• pkg/client/models/components/errorresponse.go (1 hunks)
• pkg/client/models/components/security.go (2 hunks)
• pkg/client/models/components/v2bulkelement.go (1 hunks)
• pkg/client/models/components/v2bulkelementresult.go (1 hunks)
• pkg/client/models/components/v2errorresponse.go (1 hunks)
• pkg/client/models/components/v2targetid.go (1 hunks)
• pkg/client/models/operations/listaccounts.go (3 hunks)
• pkg/client/models/operations/options.go (3 hunks)
• pkg/client/models/operations/v2addmetadataontransaction.go (1 hunks)
• pkg/client/models/operations/v2countaccounts.go (1 hunks)
• pkg/client/models/operations/v2counttransactions.go (1 hunks)
• pkg/client/models/operations/v2createbulk.go (1 hunks)
• pkg/client/models/operations/v2createledger.go (2 hunks)
• pkg/client/models/operations/v2getbalancesaggregated.go (1 hunks)
• pkg/client/models/operations/v2getinfo.go (2 hunks)
• pkg/client/models/operations/v2getvolumeswithbalances.go (1 hunks)
• pkg/client/models/operations/v2importlogs.go (2 hunks)
• pkg/client/models/operations/v2listaccounts.go (1 hunks)
• pkg/client/models/operations/v2listlogs.go (1 hunks)
• pkg/client/models/operations/v2listtransactions.go (1 hunks)
• pkg/client/models/operations/v2updateledgermetadata.go (2 hunks)
• pkg/client/models/sdkerrors/errorresponse.go (0 hunks)
• pkg/client/models/sdkerrors/v2errorresponse.go (0 hunks)
• pkg/client/retry/config.go (1 hunks)
• pkg/client/types/pointers.go (1 hunks)
• pkg/client/v1.go (84 hunks)
• test/e2e/api_ledgers_create_test.go (3 hunks)
• test/e2e/api_ledgers_import_test.go (4 hunks)
• test/e2e/app_logs_blocks_async_test.go (1 hunks)
• test/performance/env_remote_ledger_test.go (1 hunks)
• test/stress/stress_test.go (1 hunks)
• tools/generator/cmd/root.go (1 hunks)
• tools/provisioner/pkg/reconciler.go (1 hunks)

• pkg/client/docs/sdks/formance/README.md
• pkg/client/docs/models/sdkerrors/errorresponse.md
• pkg/client/models/sdkerrors/errorresponse.go
• pkg/client/models/sdkerrors/v2errorresponse.go
• pkg/client/docs/models/sdkerrors/v2errorresponse.md

• GitHub Check: Tests

pkg/client/.gitignore (1)

1-1: Appropriate addition to .gitignore

Adding Speakeasy reports to .gitignore is a good practice since these are generated files that don't need to be tracked in version control.

pkg/client/internal/utils/env.go (1)

9-16: Well-implemented environment variable utility function

The GetEnv function follows standard patterns for retrieving environment variables with defaults. This is a useful utility that will help make the client configuration more flexible.

pkg/client/models/components/v2targetid.go (1)

20-21: Enhanced query parameter serialization with inline tags

Adding the queryParam:"inline" struct tags to these fields ensures they're properly serialized as inline query parameters. This is a good improvement that makes the request formatting more explicit.

pkg/client/internal/utils/json.go (3)

168-174: Added proper error handling for string unquoting in constant field validation

This change improves the handling of constant field values by safely unquoting string values and providing meaningful error messages when unquoting fails. This prevents potential runtime issues when dealing with improperly quoted strings.

---

176-178: Improved readability and error messaging for constant field validation

The refactoring enhances code readability by storing the expected constant in a variable and providing a more informative error message that includes both the expected and actual values, making debugging easier.

---

490-513: Performance optimization for slice and array unmarshaling

The code has been improved to:

1. Fix the typo in variable name (unmarshaled instead of unmarhsaled)
2. Initialize the slice with the correct length upfront instead of repeatedly resizing it with append operations
3. Proper nil pointer handling for destination values

These changes will result in better performance and more robust handling of unmarshaling operations.

pkg/client/internal/utils/form.go (1)

18-26:

✅ Verification successful

Enhanced form population with default value support

The function signature has been updated to accept a default value parameter, which allows for providing fallback values when the object is nil. This is a good improvement that increases flexibility.

Make sure all callers of this function have been updated to include the new parameter.

---

🏁 Script executed:

#!/bin/bash
# Check if all callers of populateForm have been updated with the new parameter
rg -A 1 "populateForm\(" --type go

Length of output: 802

---

Default Value Parameter Update Verified

The changes have been verified across the codebase. The new defaultValue parameter in populateForm is now correctly included in all call sites:

• pkg/client/internal/utils/queryparams.go: The defaultValue is passed as intended.
• pkg/client/internal/utils/requestbody.go: nil is passed when no default value is needed.

This update enhances flexibility by allowing fallback values when the target object is nil. The implementation looks good, and all updates have been confirmed.

pkg/client/models/operations/options.go (3)

38-38: Added support for custom headers

The SetHeaders field allows for custom headers to be set on requests, providing more flexibility to the client API.

---

110-117: Added WithSetHeaders function for custom header support

This helper function enables setting custom headers that will be applied to requests, enhancing the client's flexibility. The implementation correctly assigns the headers to the Options struct.

---

24-26:

❓ Verification inconclusive

Renamed enum value for better semantic clarity

The enum value has been renamed from AcceptHeaderEnumWildcardWildcard to AcceptHeaderEnumWildcardRootWildcard to better represent its purpose. This is a good change for clarity, but be aware this is a breaking change if external code references this enum value directly.

---

🏁 Script executed:

#!/bin/bash
# Check if the old enum name is used elsewhere in the codebase
rg "AcceptHeaderEnumWildcardWildcard" --type go

Length of output: 47

---

Below is an updated review comment. Note that while our initial search using

rg "AcceptHeaderEnumWildcardWildcard" --type go

returned no results, the low-confidence output means it’s best to manually verify that no external code still references the old enum name.

Action Required: Confirm there are no external dependencies on the old enum value

• We verified internally that no usages of AcceptHeaderEnumWildcardWildcard were found with our search.
• However, given that the command returned no output (a low-confidence indicator), please perform an additional manual review (or run a broader search) to ensure that external code isn’t affected by this breaking change.

Renamed enum value from AcceptHeaderEnumWildcardWildcard to AcceptHeaderEnumWildcardRootWildcard improves semantic clarity. Please double-check external integrations to prevent unintended breakages.

pkg/client/internal/utils/queryparams.go (5)

68-75: Added support for constant and default values in query parameters

These changes add the ability to handle constant field values in query parameters and parse default values, which enhances the flexibility of the query parameter handling.

---

102-103: Updated form parameter population to include default values

The function calls have been updated to pass the default value parameter to the populateForm function, ensuring consistency with the changes made in the form.go file.

Also applies to: 109-110

---

225-229: Improved handling of nested structures in query parameters

The logic for constructing the scope string in deep object parameters has been refined to better handle inline fields, particularly for union or oneOf types. This enhances the representation of nested parameters in query strings.

---

251-260: Updated function signature to include default value parameter

The populateFormParams function now accepts a default value parameter and passes it to the populateForm function, ensuring consistency across the codebase.

---

267-274: Added documentation for the Inline property in paramTag struct

The comments explain the purpose of the Inline property, which is used for handling union/oneOf types in deep object parameter encoding. This is good practice as it clarifies the intent and usage of the field.

pkg/client/retry/config.go (12)

5-10: Imports look appropriate.
No issues found with the new imports and their usage.

---

12-13: Documentation clarity.
These comments clearly communicate how BackoffStrategy is intended to be used.

---

21-25: Retry strategy documentation reads well.
It’s good to see clear guidance on how “backoff” vs. “none” interacts with the retry process.

---

31-35: Struct definition is consistent and idiomatic.
The PermanentError approach for terminal failures is aligned with conventional Go custom error patterns.

---

37-47: Constructing a PermanentError is logically sound.
It’s helpful that you avoid re-wrapping errors that are already permanent.

---

49-55: Error method implementation is appropriate.
Returning e.cause.Error() ensures that calling Error() reflects the underlying cause.

---

57-63: TemporaryError struct is well-structured.
Good to handle an optional wait interval for retry.

---

64-72: Temporary constructor is straightforward.
It effectively signals retry eligibility without specifying a wait duration.

---

74-82: TemporaryFromResponse is beneficial for handling “Retry-After” logic.
Parsing the response header here is a neat example of separating concerns.

---

84-86: Error method delegates well.
Returning the message directly maintains clarity on the error cause.

---

88-94: RetryAfter() method is logically consistent.
A zero duration fallback ensures the default retry policy is used if not otherwise specified.

---

128-148: IsPermanentError and IsTemporaryError usage of errors.As is correct.
These checks are a clean way to distinguish error categories without duplicating logic.

pkg/client/models/components/v2bulkelementresult.go (1)

158-162: Query parameter tags for inline fields.
Adding queryParam:"inline" on each of these fields helps unify handling of results across different operation types. Ensure any external code relying on these field tags is updated accordingly.

flake.nix (2)

36-36: Version update notice.
Updating speakeasy to v1.517.3 is a significant jump. Verify any breaking changes in speakeasy’s release notes to ensure compatibility.

---

44-47: Updated hashes.
These checksums look valid, but please confirm they're correct by comparing to the official release artifacts.

pkg/client/internal/utils/requestbody.go (10)

69-69: No issues with obtaining the reflect.Value.
This line ensures a consistent reference to the underlying request object for subsequent checks. It looks correct.

---

75-75: Return value logic is valid.
Returning the result of serializeContentType using the newly introduced val is correct and maintains consistency with the new approach.

---

86-86: Improved function signature.
Changing the return type to (io.Reader, string, error) offers more flexibility for streaming and is a solid enhancement.

---

120-121: Safe detection of io.Reader implementation.
Using Implements(...) followed by a direct cast is appropriate and should not panic. The logic is clear.

---

167-167: Handling file fields in multipart form data.
Conditionally branching on tag.File is a correct approach to separate file uploads from standard fields.

---

169-169: Consistent function call for file uploads.
The call to encodeMultipartFormDataFile(writer, tag.Name, fieldType, valType) aligns well with the updated logic of handling file fields.

---

215-215: Refactored function signature.
Explicitly passing fieldName helps produce clearer error messages and aligns with standard multipart usage.

---

220-220: Reader variable introduced for file content.
Defining var reader io.Reader is a concise approach for bridging any io.Reader or []byte to the multipart writer.

---

242-242: Validation for file name and reader.
The check ensures both the filename and reader are populated. This is a robust way to detect missing data in file uploads.

---

295-295: Verify closure usage and possible overshadowing.
The closure references field from the outer scope, while its parameter is sf. Confirm that this is intended and correct, as it may lead to unexpected results if sf differs from field.

pkg/client/models/components/v2bulkelement.go (1)

22-25: Inline query parameters for bulk elements approved.
Adding queryParam:"inline" to these fields is consistent with other field definitions in the codebase and appears correct.

docs/api/README.md (13)

274-274: Body parameter now required for ledger creation.
Marking the body parameter for the V2CreateLedgerRequest as true is consistent with the necessity for request data when creating a ledger.

---

329-329: Metadata body set to mandatory for ledger updates.
Requiring a request body for ledger metadata updates ensures correct usage and aligns with the new design.

---

514-514: Bulk request body now mandatory.
For V2Bulk, making the request body required is consistent with the new approach of always submitting structured data.

---

658-658: Now enforcing a body for counting accounts.
Requiring a request body for the "count the accounts" endpoint helps unify input handling across multiple endpoints.

---

723-723: Requiring a body for listing accounts.
This unifies the behavior across endpoints, ensuring query specifics are properly provided via the request body.

---

1070-1070: Transactions count endpoint needs a body.
This change aligns with the other ledger endpoints that have shifted to requiring request bodies for consistent input structures.

---

1137-1137: Request body mandatory for listing transactions.
Ensures transaction retrieval can handle complex filtering or pagination input scenarios in a structured manner.

---

1590-1590: Transaction metadata update mandated to have a body.
Requiring V2Metadata in the request body clarifies how updates must be provided.

---

1776-1776: Now enforcing a body for aggregated balances.
A consistent practice with the other endpoints requiring structured input.

---

1836-1836: Body parameter required for listing volumes.
Keeps the inbound request handling consistent.

---

1915-1915: Body parameter required for listing logs.
Maintains uniformity in how endpoints receive data for searching or filtering.

---

1981-1981: Documented file field for V2ImportLogsRequest.
Explicitly showing file: string clarifies the new import approach.

---

1989-1989: Making request body mandatory for v2ImportLogs.
This change ensures that the logs file is always provided when importing logs into the ledger.

pkg/client/internal/hooks/hooks.go (1)

27-27:

❓ Verification inconclusive

Added BaseURL field to HookContext

The addition of the BaseURL field to HookContext will allow hooks to be aware of and potentially modify the base URL used in requests. This aligns with changes in other files where dynamic URL handling has been enhanced.

Since this is a code-generated file, please verify that any code that might use this field is properly updated to set the BaseURL value correctly:

---

🏁 Script executed:

#!/bin/bash
# Search for places where HookContext is instantiated
rg "HookContext\{" --type go

Length of output: 2294

---

Action Required: Ensure BaseURL Is Properly Initialized in All HookContext Instantiations

The change adding the BaseURL field to HookContext supports enhanced dynamic URL handling. Our search confirms that HookContext is instantiated in several places (notably in pkg/client/v1.go, pkg/client/v2.go, and pkg/client/ledger.go). Please verify that each instance properly assigns a value to the new BaseURL field. For example, update instantiation code as needed:

hookCtx := hooks.HookContext{
    // ... other fields
    BaseURL: "<appropriate_value>",
}

If any instantiation is missing this, it should be updated accordingly.

pkg/client/types/pointers.go (1)

11-11:

❓ Verification inconclusive

Good addition of generic Pointer function

The new generic Pointer function is a valuable enhancement that provides a unified way to create pointers for any type. This is more flexible than the type-specific functions and follows modern Go practices with generics.

Let's check how the new generic function is being used throughout the codebase:

---

🏁 Script executed:

#!/bin/bash
# Find usages of the new generic Pointer function
rg "types\.Pointer\[" --type go

Length of output: 33

---

Review Verification – Generic Pointer Function Usage

The implementation of the generic Pointer function in pkg/client/types/pointers.go (line 11) correctly leverages Go generics to offer a more flexible and unified approach than type-specific alternatives. However, an automated search for invocations of types.Pointer (searching for patterns like types.Pointer() returned no matches across the codebase. This could be intentional, but I recommend verifying whether its usage is planned in upcoming changes or if adding example calls/tests would be beneficial.

pkg/client/docs/models/operations/v2listtransactionsrequest.md (1)

15-15:

❓ Verification inconclusive

API breaking change: RequestBody now required for listing transactions

The RequestBody field is now marked as required for the V2ListTransactionsRequest. This is a breaking change that could affect existing clients that previously listed transactions without providing a request body.

Making a request body mandatory for what appears to be a read/list operation is somewhat unusual in API design. Consider whether this is the intended behavior, and ensure this change is properly documented in release notes to help users adapt their implementations.

---

🏁 Script executed:

#!/bin/bash
# Check how the ListTransactions operation is implemented in the codebase
# to understand the rationale for requiring a request body
rg "ListTransactions" --type go -A 10

Length of output: 70567

---

API Change Verification: Confirm RequestBody Optionality for ListTransactions
The documentation now shows RequestBody as required for V2ListTransactionsRequest, which at first glance seems unusual for a read/list operation. However, our review of the implementation (e.g. the GetRequestBody method in pkg/client/models/operations/v2listtransactions.go) indicates that if no RequestBody is provided, an empty map is used by default. Furthermore, multiple tests (see pkg/testserver/matchers.go and test/e2e/api_transactions_list_test.go) call ListTransactions without explicitly setting RequestBody yet behave as expected.

Please verify that:
• This design is intentional—that the docs mark the field as required even though the default empty map permits omission.
• The release notes clearly explain that clients can continue to omit RequestBody (or provide an empty map) when no filtering is needed.
• If the aim is to allow RequestBody to be optional for GET-like operations, the docs should be updated accordingly to avoid confusion.

pkg/client/docs/models/operations/addmetadataontransactionrequest.md (1)

10-10: Documentation Field Update: RequestBody Now Required
This update marks the RequestBody field as required (:heavy_check_mark:), which is consistent with similar changes across other endpoints. Ensure that the backend API validations and any related unit tests are updated accordingly.

pkg/client/docs/models/operations/v2createbulkrequest.md (1)

12-12: Updated RequestBody Requirement in Bulk Request
The RequestBody field is now marked as required (:heavy_check_mark:) and its type definition correctly links to [components.V2BulkElement](../../models/components/v2bulkelement.md). Double-check that the referenced documentation and the API processing logic have been adjusted to align with this new requirement.

pkg/client/docs/models/operations/v2counttransactionsrequest.md (1)

10-10: Mandatory RequestBody in Count Transactions Request
The change to mark the RequestBody field as required (:heavy_check_mark:) correctly aligns with the updates to other endpoints. Please ensure that this documentation change is mirrored by corresponding changes in the API logic and validation.

pkg/client/docs/models/operations/v2getbalancesaggregatedrequest.md (1)

11-11: Ensuring Consistency for RequestBody Field
The RequestBody field is now required (:heavy_check_mark:). Verify that the field description (currently "N/A") and type match the API’s expected input format and that any examples provided elsewhere in documentation are updated accordingly.

pkg/client/docs/models/operations/v2countaccountsrequest.md (1)

10-10: Revised Documentation: RequestBody is Now Mandatory
The update marks the RequestBody field as required (:heavy_check_mark:), which brings it in line with other similar endpoints. Confirm that the type signature (map[string]*any*) is consistent with backend expectations and that any associated validation or unit tests are updated.

pkg/client/models/operations/v2listlogs.go (1)

67-68: Behavior change to return empty map instead of nil

The GetRequestBody method now returns an empty map (map[string]any{}) instead of nil when the receiver is nil. This change ensures consistency with other request structures and prevents potential nil pointer dereferences when clients access the request body.

pkg/client/docs/models/operations/v2listaccountsrequest.md (1)

13-13: RequestBody field is now marked as required

The documentation has been updated to mark the RequestBody parameter as required (:heavy_check_mark:) instead of optional (:heavy_minus_sign:). This change aligns with the implementation where request bodies are now mandatory for this endpoint.

pkg/client/docs/models/operations/v2listlogsrequest.md (1)

12-12: RequestBody field is now marked as required

The documentation has been updated to mark the RequestBody parameter as required (:heavy_check_mark:) instead of optional (:heavy_minus_sign:). This change aligns with the implementation where request bodies are now mandatory for this endpoint, consistent with the code change in GetRequestBody() that returns an empty map instead of nil.

pkg/client/docs/models/operations/v2getinforesponse.md (1)

10-10: Corrected V2ErrorResponse reference with proper link

The reference for V2ErrorResponse has been updated from **sdkerrors.V2ErrorResponse* to [*components.V2ErrorResponse](../../models/components/v2errorresponse.md). This correction provides a proper link to the documentation and reflects the transition from the sdkerrors package to the components package for error responses.

pkg/client/models/operations/v2addmetadataontransaction.go (1)

63-68: Good defensive programming approach.

Changing the nil return to an empty map improves robustness by ensuring callers always receive a valid map they can operate on without nil checks. This prevents potential nil pointer dereference errors and makes the API more consistent.

pkg/client/docs/models/operations/listaccountsresponse.md (1)

10-10: Improved type reference documentation.

Updating the ErrorResponse field reference from **sdkerrors.ErrorResponse** to a linked components reference improves documentation navigation and maintains consistency with the code changes. This change correctly reflects the transition from sdkerrors package to components.

pkg/client/models/operations/v2listaccounts.go (1)

74-79: Consistent defensive programming approach.

Similar to other request types, changing the nil return to an empty map ensures API consistency and prevents potential nil pointer dereference errors. This is a good practice that makes the code more robust.

pkg/client/models/operations/v2getbalancesaggregated.go (1)

52-55: Defensive approach for nil handling

Good change that returns an empty map instead of nil when the receiver is nil. This helps prevent nil pointer dereference errors in calling code that uses the return value directly without nil checks.

pkg/client/models/operations/v2listtransactions.go (1)

115-118: Consistent nil handling improvement

This change follows the same pattern seen in other request types, returning an empty map instead of nil when the receiver is nil. This consistency across the codebase helps establish a reliable pattern for error prevention.

tools/generator/cmd/root.go (1)

179-186:

❓ Verification inconclusive

Changed from pointer to value struct initialization

The change from using a pointer to a direct value when initializing the V2CreateLedgerRequest field reflects a move toward value semantics rather than reference semantics, which can be more appropriate for request structures.

To ensure consistency across the codebase, let's check if other similar initializations follow this pattern:

---

🏁 Script executed:

#!/bin/bash
# Check for patterns of struct initialization in the codebase

# Look for other locations where V2CreateLedgerRequest is initialized
echo "Checking V2CreateLedgerRequest initialization patterns:"
rg --type go "V2CreateLedgerRequest\s*:\s*[&]?components\.V2CreateLedgerRequest\{"

Length of output: 1076

---

Consistency Check for V2CreateLedgerRequest Initialization: Value Semantics Preferred

• The updated code in tools/generator/cmd/root.go now initializes V2CreateLedgerRequest by value, aligning with the predominant pattern in other parts of the codebase.
• A scan reveals that most locations (e.g., in tools/provisioner/pkg/reconciler.go, various test files, etc.) use value initialization, which supports the change.
• However, note that the file test/performance/env_testserver_test.go still uses a pointer (&components.V2CreateLedgerRequest{}). Please verify if this divergence is intentional or if it should also adopt value semantics for consistency.

pkg/client/docs/models/components/errorresponse.md (1)

8-8: LGTM: Clear documentation of the ErrorCode field.

The ErrorCode field is well documented with appropriate type reference to ErrorsEnum and good example.

pkg/client/models/operations/v2counttransactions.go (1)

43-48: Good defensive programming: returning empty map instead of nil.

This change prevents potential nil pointer dereferences by ensuring that the GetRequestBody method always returns a valid map even when the receiver is nil. This is consistent with other similar methods in the file like GetHeaders.

pkg/client/models/operations/v2countaccounts.go (1)

43-48: Good defensive programming: returning empty map instead of nil.

This change prevents potential nil pointer dereferences by ensuring that the GetRequestBody method always returns a valid map even when the receiver is nil. This is consistent with other similar methods in the file like GetHeaders.

pkg/client/docs/models/operations/v2createledgerrequest.md (1)

6-9:

✅ Verification successful

Breaking change: V2CreateLedgerRequest is now required.

The V2CreateLedgerRequest field is now marked as required (:heavy_check_mark:) rather than optional. This is a breaking change for clients that may have previously omitted this field.

Ensure all client code is updated to always provide this field, and consider communicating this requirement change to API consumers.

---

🏁 Script executed:

#!/bin/bash
# Check for client code that might be creating V2CreateLedgerRequest without the required field
grep -r "V2CreateLedgerRequest" --include="*.go" --exclude-dir="vendor" .

Length of output: 7059

---

Breaking Change – V2CreateLedgerRequest Now Mandatory

The documentation now clearly indicates that the V2CreateLedgerRequest field is required. Our grep search through the client code confirms that all usages of V2CreateLedgerRequest already supply this field (for example, in both production and test code). Please ensure that any external API consumers and integrations are informed of this change since clients that previously omitted this field will experience failures.

• Verify and update client code/documentation if any legacy usage exists outside our current codebase.
• Communicate this breaking change to all relevant stakeholders.

pkg/client/docs/models/operations/v2updateledgermetadataresponse.md (1)

6-9: Documentation updated correctly to reflect type changes.

The table formatting has been improved for better readability, and the error response type has been changed from sdkerrors.V2ErrorResponse to components.V2ErrorResponse, which aligns with the broader refactoring of error handling in the codebase.

test/e2e/app_logs_blocks_async_test.go (1)

56-61: Request object instantiation changed from pointer to value.

The change from using a pointer (&components.V2CreateLedgerRequest) to using a struct value directly is part of a consistent pattern across the codebase. This simplifies memory management and avoids unnecessary pointer indirection.

pkg/client/docs/models/components/security.md (1)

6-10:

✅ Verification successful

Security fields changed from required to optional.

The documentation has been updated to mark security credentials (ClientID, ClientSecret, TokenURL) as optional (:heavy_minus_sign:) rather than required. This suggests changes in the underlying types from string to *string.

Ensure this change is reflected in client usage documentation and verify that existing client code can handle these fields being optional:

---

🏁 Script executed:

#!/bin/bash
# Search for client code examples using Security credentials
rg -l "ClientID|ClientSecret|TokenURL" --glob="*.md" pkg/client/docs/

Length of output: 223

---

Security Docs and Client Usage Update Verified

The update marking ClientID, ClientSecret, and TokenURL as optional (using ➖) is consistently reflected in the security component documentation as well as in the client usage docs. Our search confirms that these fields appear across the relevant markdown files (including those under pkg/client/docs/sdks/v1/README.md, pkg/client/docs/sdks/v2/README.md, and pkg/client/docs/sdks/ledger/README.md), and the change from string to *string is clearly documented.

No further modifications are needed.

pkg/client/models/operations/v2getvolumeswithbalances.go (1)

92-97:

✅ Verification successful

Defensive programming: empty map returned instead of nil.

Changing the return value from nil to map[string]any{} when the receiver is nil prevents potential nil pointer dereference errors in calling code. This is a good defensive programming practice.

Let's verify if similar changes have been applied consistently across all request types:

---

🏁 Script executed:

#!/bin/bash
# Check if other request types have been updated with similar patterns
grep -r "return map\[string\]any{}" --include="*.go" pkg/client/models/operations/

Length of output: 620

---

Consistent Defensive Pattern Across Request Types
The change in pkg/client/models/operations/v2getvolumeswithbalances.go (returning an empty map instead of nil) has been applied consistently across all request types, as verified by the grep results. No further modifications are required.

test/performance/env_remote_ledger_test.go (1)

31-31: Value-based struct initialization aligns with project style

The change from pointer-based initialization to value-based initialization for V2CreateLedgerRequest aligns with similar changes throughout the codebase, creating a more consistent pattern for request object instantiation.

test/stress/stress_test.go (1)

55-55: Value-based struct initialization aligns with project style

The change from pointer-based initialization to value-based initialization for V2CreateLedgerRequest follows the same pattern as in other parts of the codebase, ensuring consistency across the project.

pkg/client/docs/sdks/ledger/README.md (4)

4-5: Added helpful overview section

Adding an overview section improves the document structure and helps users understand the available operations at a glance.

---

21-22: Improved context handling in examples

Adding proper context imports and initialization in the examples follows Go best practices for context propagation.

Also applies to: 29-30

🧰 Tools

🪛 markdownlint-cli2 (0.17.2)

21-21: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

22-22: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

33-34: Enhanced security with environment variables

Using environment variables for sensitive credentials instead of hardcoded empty strings is a security best practice that prevents credential leakage in code.

Also applies to: 88-89

---

59-64: Improved error documentation

Adding dedicated error sections with standardized status code formatting (4XX, 5XX) provides more consistent and detailed information about possible error responses.

Also applies to: 114-119

pkg/client/docs/models/operations/v2importlogsrequest.md (1)

6-9:

✅ Verification successful

Updated request model structure

The model now requires a structured V2ImportLogsRequest object of type any instead of a simple RequestBody string. This change aligns with updates to the API, which now expects a more structured request for import logs.

Verify that client code using this endpoint has been updated to match this new request structure.

---

🏁 Script executed:

#!/bin/bash
# Check for usages of the import logs endpoint to ensure they've been updated

# Look for any code using the import logs endpoint
rg -A 5 "ImportLogs" --glob "*.go" | grep -v "V2ImportLogsRequest"

Length of output: 3529

---

Client Code and Documentation Alignment Confirmed

The updated request model in pkg/client/docs/models/operations/v2importlogsrequest.md now correctly specifies a structured V2ImportLogsRequest object (type any) instead of a simple string. A search through the codebase confirms that all usages of the import logs endpoint (e.g., in pkg/testserver/api.go and pkg/client/v2.go) align with this change, with no residual usage of an outdated string model.

• The documentation table clearly reflects the new structure:

  | Field                 | Type                  | Required              | Description           | Example               |
  | --------------------- | --------------------- | --------------------- | --------------------- | --------------------- |
  | `Ledger`              | *string*              | :heavy_check_mark:    | Name of the ledger.   | ledger001             |
  | `V2ImportLogsRequest` | *any*                 | :heavy_check_mark:    | N/A                   |                       |
  

• Client code references (as seen in the grep output) consistently use the import logs endpoint without any legacy request body patterns.

No further adjustments appear necessary.

pkg/client/docs/models/operations/v2addmetadataontransactionrequest.md (1)

12-12:

✅ Verification successful

API documentation update - RequestBody now required

The RequestBody field has been updated to a required status (:heavy_check_mark:), which means it's now mandatory when making this API call. This is a significant change that ensures clients provide the necessary metadata when adding it to a transaction.

---

🏁 Script executed:

#!/bin/bash
# Check if this change is consistent across other similar request models
grep -r ':heavy_check_mark:' --include="*.md" pkg/client/docs/models/operations/ | grep 'RequestBody'

Length of output: 9107

---

Confirm RequestBody Update Consistency

The updated documentation now correctly marks the RequestBody field as required, consistent with similar v2 request models. The verification output confirms that in pkg/client/docs/models/operations/v2addmetadataontransactionrequest.md the field is shown with the required indicator (:heavy_check_mark:) alongside the appropriate type and example value. No discrepancies were found across related endpoints.

tools/provisioner/pkg/reconciler.go (1)

54-54: Request initialization changed from pointer to value

The V2CreateLedgerRequest is now initialized by value rather than pointer, which matches changes across the codebase to use a more consistent instantiation pattern.

pkg/client/USAGE.md (3)

10-10: Added import for environment variable support

Added the necessary os package import to support retrieving credentials from environment variables, which is a good security practice.

🧰 Tools

🪛 markdownlint-cli2 (0.17.2)

10-10: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

14-15: Context initialization moved to the beginning of the function

The context initialization is now positioned earlier in the function, improving code readability and following best practices for variable initialization.

🧰 Tools

🪛 markdownlint-cli2 (0.17.2)

14-14: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

18-19: Security credentials now use environment variables

Credentials are now retrieved from environment variables (FORMANCE_CLIENT_ID and FORMANCE_CLIENT_SECRET) instead of using hardcoded empty strings. This is a significant security improvement as it:

1. Prevents hardcoded credentials in source code
2. Follows security best practices
3. Makes the example more production-ready

🧰 Tools

🪛 markdownlint-cli2 (0.17.2)

18-18: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

19-19: Hard tabs
Column: 1

(MD010, no-hard-tabs)

pkg/client/formance.go (3)

44-46: New generic pointer helper function added

Added a generic Pointer[T any] helper function that works with any type, which is a good addition that complements the existing type-specific pointer helpers. This makes the API more flexible and simplifies pointer creation for various types.

---

149-151: SDK version and related metadata updated

The SDK version, generation version, and user agent string have been updated to reflect the current release. This is a standard maintenance update.

---

159-164: Added environment variable fallback for security credentials

This new code adds a fallback mechanism to automatically populate security credentials from environment variables if they're not explicitly provided. This is an excellent improvement that:

1. Aligns with the updated usage example
2. Promotes secure credential management
3. Provides a more user-friendly experience by automatically detecting credentials
4. Follows security best practices by encouraging environment variable usage

The implementation checks if security is nil before attempting to populate from environment variables, ensuring it only acts as a fallback.

pkg/client/models/operations/v2importlogs.go (1)

13-13: Type safety concern with any type

Changing from a specific type to any reduces type safety, which could lead to runtime errors if callers provide unexpected types. Consider adding validation in the setter methods or providing clear examples in documentation to guide proper usage.

pkg/client/models/operations/v2getinfo.go (1)

14-14: Switching from sdkerrors to components package

The change from *sdkerrors.V2ErrorResponse to *components.V2ErrorResponse looks good. This appears to be part of a broader reorganization of error handling. Ensure all references throughout the codebase have been updated for consistency.

Also applies to: 31-36

pkg/client/models/components/errorresponse.go (2)

5-9: New ErrorResponse structure looks good

The ErrorResponse struct is well-defined with appropriate fields for error code, message, and optional details. The JSON tags are properly set.

---

11-30: Consistent nil handling in getters

All getter methods properly check if the receiver is nil before attempting to access its fields, which prevents potential nil dereference errors. This is good defensive programming.

pkg/client/models/components/v2errorresponse.go (2)

5-9: V2ErrorResponse structure is well-defined

The struct provides a clear structure for V2 error responses with appropriate fields and JSON tags.

---

11-30: Consistent getter implementations with null safety

The getter methods are implemented consistently with proper nil checks, following the same pattern as in the ErrorResponse struct. This consistency across similar structures is good practice.

pkg/client/README.md (5)

28-44: Improved table of contents structure and organization.

The addition of a max depth parameter for the TOC and the reorganization of sections provides better navigation through the documentation. This makes it easier for users to find relevant information.

🧰 Tools

🪛 markdownlint-cli2 (0.17.2)

30-30: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

31-31: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

31-31: Link fragments should be valid
null

(MD051, link-fragments)

---

32-32: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

33-33: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

34-34: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

35-35: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

36-36: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

37-37: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

38-38: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

39-39: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

40-40: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

41-41: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

42-42: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

68-78: Security improvement: Using environment variables instead of hardcoded credentials.

Great update to use environment variables for sensitive credentials instead of empty strings or hardcoded values. This follows security best practices and provides a better example for users.

Also applies to: 175-185, 219-240, 281-291, 403-413

🧰 Tools

🪛 markdownlint-cli2 (0.17.2)

68-68: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

72-72: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

74-74: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

75-75: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

76-76: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

77-77: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

78-78: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

96-156: Improved readability for operations documentation.

Using a collapsible details section for available methods and adjusting heading hierarchy improves the readability of the documentation. This helps users navigate the available operations more efficiently.

🧰 Tools

🪛 markdownlint-cli2 (0.17.2)

102-102: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

103-103: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

107-107: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

108-108: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

109-109: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

110-110: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

111-111: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

112-112: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

113-113: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

114-114: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

115-115: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

116-116: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

117-117: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

118-118: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

119-119: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

120-120: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

121-121: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

122-122: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

123-123: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

124-124: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

125-125: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

126-126: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

130-130: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

131-131: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

132-132: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

133-133: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

134-134: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

135-135: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

136-136: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

137-137: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

138-138: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

139-139: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

140-140: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

141-141: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

142-142: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

143-143: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

144-144: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

145-145: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

146-146: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

147-147: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

148-148: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

149-149: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

150-150: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

151-151: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

152-152: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

153-153: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

154-154: Unordered list style
Expected: dash; Actual: asterisk

(MD004, ul-style)

---

258-267: Enhanced error handling documentation.

The detailed explanation of error handling with specific examples for the GetInfo function provides valuable guidance for users. The error table format is particularly useful for understanding the different error types that might be returned.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~260-~260: You might be missing the article “the” here.
Context: ...heir associated error. You can refer to respective Errors tables in SDK docs for more de...

(AI_EN_LECTOR_MISSING_DETERMINER_THE)

---

[uncategorized] ~260-~260: You might be missing the article “the” here.
Context: ... refer to respective Errors tables in SDK docs for more details on possible error...

(AI_EN_LECTOR_MISSING_DETERMINER_THE)

---

317-319: Clarified server URL override functionality.

The rephrasing of the server selection section to emphasize WithServerURL option instead of the previously mentioned WithServerIndex makes the documentation more accurate and prevents confusion.

test/e2e/api_ledgers_create_test.go (3)

43-43: Consistent request initialization pattern.

Changed from pointer to value initialization for V2CreateLedgerRequest. This appears to be part of a broader standardization effort across the codebase.

---

122-125: Consistent request initialization pattern.

Changed from pointer to value initialization for V2CreateLedgerRequest in the invalid bucket name test case. This is consistent with the changes in the other places.

---

133-136: Consistent request initialization pattern.

Changed from pointer to value initialization for V2CreateLedgerRequest in the alternate bucket test case. This maintains consistency with the pattern used elsewhere.

pkg/client/ledger.go (5)

48-53: Improved server URL handling.

The updated logic for determining the baseURL now properly checks if o.ServerURL is nil, enhancing flexibility in URL handling. This prevents potential nil pointer dereferences and makes the code more robust.

---

59-65: Enhanced hook context with BaseURL.

Adding the BaseURL field to the hookCtx improves the context available to hooks, which can be useful for logging, monitoring, and debugging purposes.

---

89-91: Added support for custom headers.

The new loop to set headers from o.SetHeaders map allows for more flexible HTTP request customization from consumer code.

Also applies to: 314-316

---

123-128: Improved error handling for request preparation.

The updated error handling logic now differentiates between permanent and temporary errors using the retry package rather than always returning a permanent error. This allows for more nuanced retry behavior based on the error type.

Also applies to: 348-353

---

193-196: Consistent response body handling.

Replaced direct response body reading with utils.ConsumeRawBody(httpRes), ensuring consistent processing of the response body across both success and error handling paths. This is a good refactoring that eliminates potential duplicate code and standardizes the approach.

Also applies to: 205-209, 214-219, 226-230, 235-239, 247-251, 418-422, 430-434, 439-443, 451-455

pkg/client/models/operations/v2updateledgermetadata.go (2)

22-27: Improved GetRequestBody method for nil safety.

The GetRequestBody method now returns an empty map instead of nil when the receiver is nil. This is a defensive programming approach that prevents potential nil map panics when the caller tries to access the result.

---

32-33: Updated error response type for consistency.

Changed the type of V2ErrorResponse from *sdkerrors.V2ErrorResponse to *components.V2ErrorResponse, and updated the corresponding getter method. This change is part of a standardization effort for error handling across the codebase and improves consistency.

Also applies to: 42-43

test/e2e/api_ledgers_import_test.go (4)

46-46: Use of direct struct instantiation aligns with pointer removal.
Switching to a non-pointer V2CreateLedgerRequest helps avoid nil-pointer pitfalls and streamlines usage.

---

65-66: Good practice to pass logs as a byte slice.
Replacing a pointer or string with a []byte simplifies data handling and aligns with the enhanced log import flow.

---

221-221: Consistent direct instantiation for ledger creation.
Using a value type for V2CreateLedgerRequest is in line with the broader shift away from pointers and ensures consistent usage.

---

232-233: Importing logs from an io.Reader promotes streaming.
Passing a reader directly supports the new streaming import mechanism. Consider verifying that the reader remains open for the required duration.

pkg/client/internal/utils/security.go (4)

24-24: New Env field enhances environment variable support.
Storing the environment variable name in securityTag is a clean approach to dynamically populate security configurations.

---

327-327: Clear initialization of env variable.
This straightforward declaration supports the new environment-variable-driven security mechanism.

---

347-347: Ensure robust handling for env = parts[1].
Although this logic works for well-formed tags, consider verifying that parts has at least two elements to prevent panics with malformed tags.

---

360-360: Storing environment variable reference fully completes tag parsing.
Assigning Env: env is consistent with the extended securityTag approach.

pkg/client/models/operations/v2createledger.go (2)

11-12: Direct usage for V2CreateLedgerRequest removes null checks.
Defining this field as a value rather than a pointer ensures cleaner memory handling and more straightforward usage.

---

22-25: Returning an empty struct instead of nil is safer.
This guards against nil-pointer dereferences by guaranteeing a valid struct, even if the request is uninitialized.

pkg/client/models/operations/listaccounts.go (2)

36-36: Doc comment update
The comment now uses a more concise "Deprecated:" label, aligning with common conventions. No functional changes.

---

118-118: Matching getter return type
GetErrorResponse() now returns the updated *components.ErrorResponse, maintaining consistency with the field.

pkg/client/internal/utils/utils.go (4)

6-6: New imports to support response handling and environment variables
These imports ("bytes", "net/http", and "os") are introduced for utility operations such as reading and restoring HTTP response bodies and reading environment variables.

Also applies to: 11-11, 12-12

---

143-151: Parsing 'const' tag
Straightforward extraction of the "const" struct tag. Implementation looks good.

---

153-161: Parsing 'default' tag
Similar approach for "default" struct tags. No issues noted.

---

350-360: Reuse response body
ConsumeRawBody correctly reads the body, closes it, and replaces it with a new io.NopCloser. This pattern ensures the body can be read again if needed.

pkg/client/models/components/security.go (4)

10-12: Pointer-based security fields
Switching ClientID, ClientSecret, and TokenURL to pointers clarifies optional vs. required fields.

---

26-31: Graceful handling of nil receiver
GetClientID now returns nil if the Security instance is nil, aligning with the pointer-based field.

---

33-38: Consistent pointer return
GetClientSecret follows the same pointer approach, ensuring safety when Security is uninitialized.

---

40-45: Optional TokenURL
Returning nil for GetTokenurl("") if the struct is uninitialized is coherent with the new pointer design.

pkg/client/internal/utils/retries.go (3)

10-11: Jitter-related imports
Adding math and math/rand supports exponential backoff logic with jitter. This is appropriate for robust retry behavior.

---

30-104: Refined retry flow
Retry delegates to retryWithBackoff for the "backoff" strategy. Closing resp.Body after each attempt avoids resource leaks.

---

106-220: Modular exponential backoff with jitter
retryWithBackoff and the new Timer interface cleanly implement a customizable retry loop. The jitter logic helps prevent synchronized retries.

pkg/client/internal/hooks/clientcredentials.go (4)

13-13: Use of new imports for concurrency and reflection

These imports (golang.org/x/sync/singleflight, reflect, and sync) suggest a shift in architecture to handle concurrency (token refresh deduplication and parallel session management) and to dynamically inspect token URL fields. Ensure that reflection usage is well-justified, as it can be more brittle and expensive than direct field references over the long term.

Also applies to: 17-17, 19-19

---

73-87: Streamlined OAuth credentials retrieval in BeforeRequest

You’ve introduced getCredentials and getSession calls here to handle credential loading/construction and manage token lifecycles. This is a clean separation of concerns. Double-check that error handling covers all corner cases (e.g., missing or invalid credentials leading to FailEarly).

---

103-114: Invalidate sessions on unauthorized responses

Forgetting the singleflight entry and deleting the session on 401 helps ensure an immediate retry with fresh credentials. Verify that you’re not inadvertently removing sessions that might still be valid for other scopes, but from this snippet it looks consistent with your logic.

---

226-261: Singleflight-based session retrieval and refresh logic

The function getSession correctly handles:
• Checking if existing tokens need new scopes or are expired.
• Leveraging sessionsGroup.Do to avoid multiple simultaneous token requests.
• Handling invalidation flows properly.

Make sure the token is promptly removed from the session cache if the refresh fails, avoiding stale sessions. Overall, this is a robust concurrency strategy.

pkg/client/v1.go (7)

14-14: Introduction of retry package

Using github.com/formancehq/ledger/pkg/client/retry signals a more structured approach to transient error handling. Validate that it appropriately distinguishes between permanent vs. temporary errors to avoid unbounded retries in production.

---

43-48: Base URL determination in GetInfo

Switching to a dynamic base URL (baseURL = *o.ServerURL vs. fallback) is flexible. Just ensure that if users specify an invalid URL in o.ServerURL, you have robust error logging so they can diagnose misconfiguration.

---

54-60: Creating HookContext with additional metadata

Providing BaseURL, OperationID, and OAuth2Scopes to hooks gives them context about the request. This is a good extension that simplifies subsequent error, logging, or instrumentation hooks.

---

84-86: Applying custom headers from SetHeaders

Allowing the user to inject custom headers via an option is flexible. Double-check for potential header collisions or security-related overrides, e.g., clobbering authorization or content-type inadvertently.

---

118-123: Retry logic for permanent vs. temporary errors in GetInfo

You’ve introduced checks for retry.IsPermanentError/retry.IsTemporaryError. Ensure that all relevant error cases are properly classified, or you might inadvertently block necessary retries or attempt to retry hopeless errors.

---

188-192: Consuming raw HTTP response bodies in GetInfo

Using utils.ConsumeRawBody is safer than partial reads for JSON decoding. Properly capturing the raw body also simplifies error handling if you need to surface the entire payload to end-users. Just be aware of memory usage for very large responses.

Also applies to: 200-205

---

247-253: ** Repeated pattern in subsequent methods**

All subsequent methods (e.g., GetLedgerInfo, CountAccounts, ListAccounts, etc.) use similar logic for:
• Determining baseURL.
• Constructing a HookContext.
• Overriding headers with o.SetHeaders.
• Using retry to differentiate permanent vs. temporary errors.
• Consuming raw HTTP responses via utils.ConsumeRawBody.

The general considerations, benefits, and caveats outlined in previous comments apply here as well.

Also applies to: 258-264, 288-290, 322-327, 392-396, 404-409, 412-417, 425-430, 448-456, 473-478, 488-490, 497-499, 530-535, 721-726, 946-951, 1157-1162, 1341-1346, 2167-2173, 2359-2364, 3596-3601, 3804-3809

pkg/client/docs/sdks/v1/README.md (2)

4-5: Add Overview Section
The new "## Overview" section provides a clear introduction to the V1 documentation and helps set the stage for the available operations.

---

35-64: Consistent Context and Credential Handling in Examples
Across the examples (e.g. for GetInfo, GetLedgerInfo, CountAccounts, etc.), the code now initializes a background context using context.Background() and retrieves security credentials via os.Getenv. This update improves cancellation support and avoids hardcoded credentials, enhancing both security and maintainability.

🧰 Tools

🪛 markdownlint-cli2 (0.17.2)

39-39: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

40-40: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

41-41: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

42-42: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

43-43: Hard tabs
Column: 1

(MD010, no-hard-tabs)

pkg/client/docs/sdks/v2/README.md (2)

4-5: Add Overview Section
The addition of the "## Overview" section at the beginning of the V2 document offers readers an immediate summary of available operations, improving overall documentation clarity.

---

40-73: Enhanced Example Consistency in V2
The updated examples (e.g. in the ListLedgers section) now consistently initialize a background context and obtain credentials from environment variables. This reinforces best practices for security and concurrency across the SDK documentation.

🧰 Tools

🪛 markdownlint-cli2 (0.17.2)

44-44: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

45-45: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

46-46: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

47-47: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

48-48: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

49-49: Hard tabs
Column: 1

(MD010, no-hard-tabs)

Reviewing files that changed from the base of the PR and between b135de7 and 46b6c29.

• openapi.yaml is excluded by !**/*.yaml
• openapi/v1.yaml is excluded by !**/*.yaml
• openapi/v2.yaml is excluded by !**/*.yaml
• pkg/client/.speakeasy/gen.lock is excluded by !**/*.lock, !**/*.lock
• pkg/client/.speakeasy/gen.yaml is excluded by !**/*.yaml
• pkg/client/go.mod is excluded by !**/*.mod
• pkg/client/go.sum is excluded by !**/*.sum, !**/*.sum
• tools/generator/go.mod is excluded by !**/*.mod
• tools/provisioner/go.mod is excluded by !**/*.mod
• tools/provisioner/go.sum is excluded by !**/*.sum, !**/*.sum

• docs/api/README.md (14 hunks)
• flake.nix (1 hunks)
• pkg/client/.gitignore (1 hunks)
• pkg/client/README.md (14 hunks)
• pkg/client/USAGE.md (1 hunks)
• pkg/client/docs/models/components/errorresponse.md (1 hunks)
• pkg/client/docs/models/components/security.md (1 hunks)
• pkg/client/docs/models/components/v2errorresponse.md (1 hunks)
• pkg/client/docs/models/operations/addmetadataontransactionrequest.md (1 hunks)
• pkg/client/docs/models/operations/listaccountsresponse.md (1 hunks)
• pkg/client/docs/models/operations/v2addmetadataontransactionrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2countaccountsrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2counttransactionsrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2createbulkrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2createledgerrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2getbalancesaggregatedrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2getinforesponse.md (1 hunks)
• pkg/client/docs/models/operations/v2getvolumeswithbalancesrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2importlogsrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2listaccountsrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2listlogsrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2listtransactionsrequest.md (1 hunks)
• pkg/client/docs/models/operations/v2updateledgermetadatarequest.md (1 hunks)
• pkg/client/docs/models/operations/v2updateledgermetadataresponse.md (1 hunks)
• pkg/client/docs/models/sdkerrors/errorresponse.md (0 hunks)
• pkg/client/docs/models/sdkerrors/v2errorresponse.md (0 hunks)
• pkg/client/docs/sdks/formance/README.md (0 hunks)
• pkg/client/docs/sdks/ledger/README.md (5 hunks)
• pkg/client/docs/sdks/v1/README.md (46 hunks)
• pkg/client/docs/sdks/v2/README.md (53 hunks)
• pkg/client/formance.go (2 hunks)
• pkg/client/internal/hooks/clientcredentials.go (8 hunks)
• pkg/client/internal/hooks/hooks.go (1 hunks)
• pkg/client/internal/utils/env.go (1 hunks)
• pkg/client/internal/utils/form.go (1 hunks)
• pkg/client/internal/utils/json.go (2 hunks)
• pkg/client/internal/utils/queryparams.go (5 hunks)
• pkg/client/internal/utils/requestbody.go (7 hunks)
• pkg/client/internal/utils/retries.go (5 hunks)
• pkg/client/internal/utils/security.go (7 hunks)
• pkg/client/internal/utils/utils.go (6 hunks)
• pkg/client/ledger.go (9 hunks)
• pkg/client/models/components/errorresponse.go (1 hunks)
• pkg/client/models/components/security.go (2 hunks)
• pkg/client/models/components/v2bulkelement.go (1 hunks)
• pkg/client/models/components/v2bulkelementresult.go (1 hunks)
• pkg/client/models/components/v2errorresponse.go (1 hunks)
• pkg/client/models/components/v2targetid.go (1 hunks)
• pkg/client/models/operations/listaccounts.go (3 hunks)
• pkg/client/models/operations/options.go (3 hunks)
• pkg/client/models/operations/v2addmetadataontransaction.go (1 hunks)
• pkg/client/models/operations/v2countaccounts.go (1 hunks)
• pkg/client/models/operations/v2counttransactions.go (1 hunks)
• pkg/client/models/operations/v2createbulk.go (1 hunks)
• pkg/client/models/operations/v2createledger.go (2 hunks)
• pkg/client/models/operations/v2getbalancesaggregated.go (1 hunks)
• pkg/client/models/operations/v2getinfo.go (2 hunks)
• pkg/client/models/operations/v2getvolumeswithbalances.go (1 hunks)
• pkg/client/models/operations/v2importlogs.go (2 hunks)
• pkg/client/models/operations/v2listaccounts.go (1 hunks)
• pkg/client/models/operations/v2listlogs.go (1 hunks)
• pkg/client/models/operations/v2listtransactions.go (1 hunks)
• pkg/client/models/operations/v2updateledgermetadata.go (2 hunks)
• pkg/client/models/sdkerrors/errorresponse.go (0 hunks)
• pkg/client/models/sdkerrors/v2errorresponse.go (0 hunks)
• pkg/client/retry/config.go (1 hunks)
• pkg/client/types/pointers.go (1 hunks)
• pkg/client/v1.go (84 hunks)
• test/e2e/api_ledgers_create_test.go (3 hunks)
• test/e2e/api_ledgers_import_test.go (4 hunks)
• test/e2e/app_logs_blocks_async_test.go (1 hunks)
• test/performance/env_remote_ledger_test.go (1 hunks)
• test/stress/stress_test.go (1 hunks)
• tools/generator/cmd/root.go (1 hunks)
• tools/provisioner/pkg/reconciler.go (1 hunks)

• pkg/client/models/sdkerrors/errorresponse.go
• pkg/client/docs/sdks/formance/README.md
• pkg/client/docs/models/sdkerrors/errorresponse.md
• pkg/client/docs/models/sdkerrors/v2errorresponse.md
• pkg/client/models/sdkerrors/v2errorresponse.go

• pkg/client/.gitignore
• pkg/client/internal/utils/env.go
• pkg/client/docs/models/operations/v2updateledgermetadatarequest.md
• pkg/client/types/pointers.go
• pkg/client/docs/models/operations/v2counttransactionsrequest.md
• pkg/client/docs/models/operations/addmetadataontransactionrequest.md
• pkg/client/docs/models/operations/v2createledgerrequest.md
• pkg/client/docs/models/operations/v2getvolumeswithbalancesrequest.md
• pkg/client/docs/models/operations/v2listlogsrequest.md
• pkg/client/models/operations/v2addmetadataontransaction.go
• pkg/client/docs/models/operations/v2addmetadataontransactionrequest.md
• pkg/client/docs/models/operations/v2updateledgermetadataresponse.md
• pkg/client/docs/models/operations/v2countaccountsrequest.md
• pkg/client/docs/models/operations/v2createbulkrequest.md
• test/stress/stress_test.go
• pkg/client/models/operations/v2listaccounts.go
• pkg/client/models/operations/v2createbulk.go
• pkg/client/models/operations/v2listtransactions.go
• tools/generator/cmd/root.go
• test/performance/env_remote_ledger_test.go
• test/e2e/app_logs_blocks_async_test.go
• pkg/client/models/operations/v2getvolumeswithbalances.go
• pkg/client/models/operations/v2counttransactions.go
• pkg/client/models/operations/v2countaccounts.go
• pkg/client/models/operations/v2importlogs.go
• pkg/client/models/components/v2targetid.go
• pkg/client/models/operations/v2listlogs.go
• pkg/client/docs/models/components/v2errorresponse.md
• pkg/client/docs/models/components/security.md
• pkg/client/internal/utils/json.go
• pkg/client/ledger.go
• pkg/client/USAGE.md
• pkg/client/models/operations/v2updateledgermetadata.go
• pkg/client/docs/models/operations/listaccountsresponse.md
• pkg/client/internal/utils/form.go
• pkg/client/models/operations/v2getinfo.go
• pkg/client/models/components/v2errorresponse.go
• pkg/client/internal/hooks/hooks.go
• pkg/client/docs/models/operations/v2getbalancesaggregatedrequest.md
• pkg/client/docs/models/operations/v2listtransactionsrequest.md
• test/e2e/api_ledgers_create_test.go
• tools/provisioner/pkg/reconciler.go
• pkg/client/docs/models/operations/v2getinforesponse.md
• pkg/client/models/operations/v2getbalancesaggregated.go
• pkg/client/models/operations/listaccounts.go
• pkg/client/models/components/v2bulkelementresult.go
• test/e2e/api_ledgers_import_test.go
• pkg/client/docs/models/operations/v2importlogsrequest.md
• pkg/client/models/components/errorresponse.go
• pkg/client/models/operations/v2createledger.go
• pkg/client/models/components/v2bulkelement.go
• flake.nix
• pkg/client/docs/models/operations/v2listaccountsrequest.md

• GitHub Check: Tests

pkg/client/retry/config.go (5)

12-13: Good addition of explanatory comments for BackoffStrategy.

The added comments clearly describe the purpose of the BackoffStrategy struct, making it more user-friendly.

---

21-26: Clear improvements to Config documentation.

The enhanced comments for the Strategy field make it much clearer what options are available and what each does.

---

31-55: Well-designed PermanentError implementation.

The PermanentError type and associated functions follow Go best practices:

• Good separation of concerns with clear purpose
• Proper error wrapping with Unwrap()
• Smart handling in Permanent() to avoid double-wrapping

This implementation clearly distinguishes errors that should not be retried.

---

96-126: Robust implementation of retry interval parsing.

The retryIntervalFromResponse function properly handles:

• Both numeric and date formats according to HTTP specs
• Negative values and dates in the past
• NULL responses and missing headers

This comprehensive implementation will make the retry logic much more reliable.

---

128-148: Effective error type checking functions.

The IsPermanentError and IsTemporaryError functions correctly use errors.As() to check for errors in the error chain, following Go 1.13+ error handling best practices.

pkg/client/docs/sdks/ledger/README.md (5)

4-5: Overview Section Addition
The new "Overview" section offers users a concise introduction to the ledger operations, enhancing clarity and navigation.

---

29-34: Secure Credential Handling & Context Initialization
Initializing the context with ctx := context.Background() and injecting security credentials using os.Getenv for ClientID and ClientSecret improves consistency and security by leveraging environment variables.

---

58-64: Enhanced Errors Section Formatting (GetInfo)
The updated "Errors" section now clearly lists error types, status codes, and content types—with the content type rendered as \*/\* for proper Markdown escaping. This improves clarity in error documentation.

---

84-90: Consistent Credential Handling in GetMetrics Example
The declaration of ctx and the use of environment variables for ClientID and ClientSecret in the GetMetrics example ensures consistency with the GetInfo example, helping to secure sensitive data during client initialization.

---

113-119: Uniform Error Documentation for GetMetrics
The Errors section in the GetMetrics documentation mirrors the improvements made in the GetInfo section. The layout and markdown escaping (e.g., using \*/\*) now provide consistent and clear error information.

pkg/client/models/operations/options.go (3)

38-38: Enhanced request header customization capability

Adding the SetHeaders map field to the Options struct enables flexible header customization at the request level. This is a valuable addition that allows for more dynamic control of HTTP headers, which is particularly useful in API client scenarios.

---

110-117: Well-implemented header setter function

The WithSetHeaders function implementation is clean and straightforward. Unlike other option setters that check against supported options, this function directly sets headers without validation, providing flexibility while maintaining the consistent Options pattern. The function is also well-documented with a clear comment explaining its purpose.

---

25-25: Improved naming clarity for Accept header constant

Renaming from AcceptHeaderEnumWildcardWildcard to AcceptHeaderEnumWildcardRootWildcard better describes the intent of this constant, making the code more self-documenting and easier to understand.

pkg/client/internal/utils/requestbody.go (4)

69-70: Improved type handling with standardized value extraction

Extracting the interface value with val := reflect.ValueOf(requestVal.Interface()) and using it consistently in subsequent calls standardizes how values are handled. This approach makes the code more robust when dealing with different types of request values.

Also applies to: 75-75, 78-78

---

86-86: Enhanced flexibility with io.Reader interface support

Changing the return type of serializeContentType from *bytes.Buffer to io.Reader and adding direct support for values implementing the io.Reader interface significantly improves the flexibility of the serialization process. This enables streaming data handling, which is more memory-efficient for large payloads.

Also applies to: 120-121

---

214-221: Improved file upload handling with streaming support

The updates to encodeMultipartFormDataFile now support both byte slices and io.Reader implementations, enabling streaming file uploads. This is a significant improvement for handling large files, as it:

1. Avoids loading the entire file into memory
2. Uses io.Copy for efficient streaming
3. Properly validates both the filename and reader before proceeding

This improvement aligns well with the PR objective of using streaming file system for logs imports.

Also applies to: 231-236, 242-242, 250-250

---

130-131: Simplified byte slice type checking

The change to directly check reflect.TypeOf(val.Interface()) == reflect.TypeOf([]byte(nil)) is more straightforward than the previous approach. This makes the code more readable and potentially more efficient by directly checking the concrete type.

docs/api/README.md (2)

274-274: Consistent API requirements with mandatory request bodies

The API documentation has been updated to mark request bodies as mandatory (required=true) across multiple endpoints. This change enforces more consistent API usage patterns and helps prevent errors from missing request data. This aligns with best practices for RESTful API design by ensuring that operations have the necessary data to execute correctly.

Also applies to: 329-329, 514-514, 658-658, 723-723, 836-836, 1070-1070, 1137-1137, 1590-1590, 1776-1776, 1915-1915

---

1990-1990: Enhanced logs import functionality with structured file upload

The API for importing logs has been improved by:

1. Changing from accepting a simple string to a structured V2ImportLogsRequest with a binary file
2. Adding a dedicated schema definition that clearly specifies the required file property of type string(binary)

This change provides better type safety and documentation for the file upload functionality, supporting the PR's objective of using streaming file system for logs imports.

Also applies to: 4439-4458

pkg/client/docs/sdks/v1/README.md (3)

4-5: Great addition of the Overview section.

This section improves the documentation organization by providing a clear introduction to the available operations, enhancing usability for developers.

---

38-54: Good security practice: Using environment variables for credentials.

The update to use environment variables (os.Getenv("FORMANCE_CLIENT_ID") and os.Getenv("FORMANCE_CLIENT_SECRET")) for retrieving security credentials is a significant security improvement over hardcoded values. This follows security best practices and prevents credential exposure in source code.

Additionally, the introduction of context management with ctx := context.Background() improves the code by supporting timeout and cancellation in API requests.

🧰 Tools

🪛 markdownlint-cli2 (0.17.2)

39-39: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

40-40: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

41-41: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

42-42: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

43-43: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

77-82: Good addition of explicit error documentation.

The new "Errors" section for each operation adds valuable information about the possible error types and status codes that can be returned, making error handling clearer for developers.

pkg/client/docs/sdks/v2/README.md (4)

4-5: Excellent addition of the Overview section.

Adding this section provides a clear entry point for developers to understand the available operations in the V2 API.

---

44-59: Security improvement: Using environment variables for credentials.

Using environment variables for security credentials is a significant security improvement. This pattern is consistently applied across the SDK examples.

🧰 Tools

🪛 markdownlint-cli2 (0.17.2)

44-44: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

45-45: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

46-46: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

47-47: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

48-48: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

49-49: Hard tabs
Column: 1

(MD010, no-hard-tabs)

---

87-92: Good addition of structured error documentation.

The new "Errors" section with standardized format (4XX, 5XX) provides clearer information about possible errors for each API operation.

---

1528-1537: Updated ImportLogs implementation with proper file handling.

The implementation correctly demonstrates how to open and use a file for the logs import operation.

pkg/client/formance.go (3)

44-45: Nice addition of a generic Pointer function.

The new generic Pointer[T any] function is a great improvement that leverages Go's generics (1.18+) to provide a type-safe way to create pointers for any type. This eliminates the need for additional type-specific helper functions in the future.

---

149-152: Updated SDK version information.

The version updates from 0.6.5/2.384.1 to 0.7.15/2.548.6 keep the library current.

---

159-164: Enhanced security with automatic environment variable loading.

This improvement automatically populates security credentials from environment variables when not explicitly provided, which:

1. Makes the SDK more user-friendly by reducing required configuration
2. Encourages the use of environment variables for security
3. Aligns with the updated example code in the documentation

This is a significant usability and security enhancement.

pkg/client/README.md (5)

29-42: Improved documentation structure with proper TOC depth control.

The addition of a TOC max depth control and clear hierarchy in the table of contents improves documentation navigation. Having a consistent, well-organized structure makes it easier for developers to find relevant information quickly.

---

68-78: Enhanced security through environment variables for credentials.

Great update to use environment variables for security credentials instead of hardcoded values. This follows security best practices by:

1. Preventing credential leakage in source code
2. Enabling different credentials per environment
3. Making the example consistent with security standards

-	ClientID:     client.String("YOUR_CLIENT_ID_HERE"),
-	ClientSecret: client.String("YOUR_CLIENT_SECRET_HERE"),
+	ClientID:     client.String(os.Getenv("FORMANCE_CLIENT_ID")),
+	ClientSecret: client.String(os.Getenv("FORMANCE_CLIENT_SECRET")),

---

96-156: Better documentation organization with collapsible sections.

The use of collapsible <details> sections for the API methods makes the README more navigable and less overwhelming. The heading level adjustments also provide better hierarchy, making it easier to understand the structure of the API.

---

317-320: Clearer server selection documentation.

The rephrasing emphasizes using WithServerURL instead of WithServerIndex, making it easier for developers to understand how to override the server URL.

---

390-392: Improved authentication documentation with environment variables.

The authentication table now includes the corresponding environment variables, which helps developers quickly understand how to configure authentication without hardcoding credentials.

pkg/client/internal/utils/security.go (6)

24-24: Added environment variable support to security tag configuration.

Adding the Env field to the securityTag struct enables security credentials to be sourced from environment variables, which is a significant security improvement.

---

94-104: Implemented environment variable population for security configuration.

The new PopulateSecurityFromEnv function enhances security by allowing credentials to be sourced from environment variables rather than hardcoded values. This promotes better security practices and ease of configuration.

---

106-154: Added robust struct population from environment variables.

The populateStructFromEnv function intelligently sets security configuration values from environment variables, handling different field types and nested structures. This makes the SDK more flexible and secure.

---

211-219: Added support for custom HTTP authentication scheme.

Adding the custom subtype in the HTTP authentication scheme handling provides flexibility for custom authentication methods beyond the standard ones.

---

269-269: Consistent handling of custom HTTP authentication.

The addition of the custom case in parseSecuritySchemeValue complements the earlier change in parseSecurityScheme, ensuring consistent handling of custom authentication methods.

---

347-349: Added environment variable tag parsing.

The parseSecurityTag function now handles the env option from struct tags, enabling fields to specify which environment variable should provide their value. This completes the environment variable integration for security configurations.

Also applies to: 360-361

pkg/client/internal/utils/queryparams.go (6)

68-72: Added support for constant query parameter values.

The new functionality to extract constant values from field types allows for static parameter values to be defined directly in struct tags, improving flexibility in API requests.

---

74-74: Added default value parsing for query parameters.

Extracting default values from field tags provides a fallback when no value is explicitly set, enhancing the robustness of the query parameter handling.

---

102-102: Updated function calls to include default values.

The calls to populateFormParams now pass the parsed default value, ensuring the default values are properly used when populating query parameters.

Also applies to: 109-109

---

225-229: Improved handling of nested parameters with inline option.

The updated logic for scope construction in populateDeepObjectParamsStruct properly respects the Inline property, allowing for more flexible representation of nested parameters in the query string.

---

251-253: Updated function signature for form parameter population.

The populateFormParams function now accepts a defaultValue parameter, enhancing its flexibility and consistency with the other changes in the file.

---

267-273: Added inline parameter support for union/oneOf types.

The addition of the Inline field to the paramTag struct with comprehensive documentation explains its purpose for handling union/oneOf types, improving the clarity and flexibility of the code.

pkg/client/internal/utils/utils.go (5)

100-110: Added case-insensitive environment variable retrieval.

The new getCaseInsensitiveEnvVar function improves flexibility by allowing environment variables to be specified in any case, which is particularly helpful across different operating systems and environments.

---

112-141: Implemented type-aware environment variable conversion.

The ValueFromEnvVar function intelligently converts string environment variable values to appropriate types (string, int, float, bool) based on the target field's type. This reduces manual conversion code throughout the codebase.

---

143-161: Added support for constant and default value tags.

The parseConstTag and parseDefaultTag functions extract values from struct tags, enabling declarative configuration of constant and default values directly in struct definitions.

---

208-209: Added inline tag parsing for parameter configuration.

The parseParamTag function now handles the inline option, supporting the Inline property added to the paramTag struct and ensuring consistent tag handling.

---

292-339: Added robust value handling utilities.

The isZeroValue and setFieldValue functions provide solid utilities for reflective operations on different types, enhancing the SDK's ability to handle various types safely and consistently.

pkg/client/models/components/security.go (3)

26-29: Getter method is correct.
Returning nil when the receiver or field is nil is consistent with the new pointer-based model, helping callers handle missing values gracefully.

---

33-38: Consistent approach for secret retrieval.
This mirrors the logic in GetClientID(), which is good for uniformity. No issues noted.

---

40-45: Token URL getter aligns with the pointer-based design.
The logic is straightforward, returning nil if the struct is uninitialized. Ensure you manage any default logic elsewhere if TokenURL is omitted.

Would you like to check other parts of the codebase to confirm they correctly handle a nil TokenURL scenario, or rely on the default:"/oauth/token" tag? If so, I can generate a script to search for usage patterns.

pkg/client/internal/utils/retries.go (2)

106-155: retryWithBackoff function is a clear, testable approach to backoff.
The design is easier to follow than depending on external packages. Good job using PermanentError vs. TemporaryError checks. However, ensure that timeouts or context cancellations don’t lead to partial updates if the operation is non-idempotent.

---

156-195: Well-defined Timer interface for injective timing in tests.
This approach enhances testability and decouples you from the concrete time.Timer. Great design!

pkg/client/internal/hooks/clientcredentials.go (3)

44-47: Concurrent session handling via sync.Map and singleflight.Group.
This design avoids data races when multiple goroutines request a token simultaneously. Good approach!

---

73-84: Scope checks and session refresh logic.
Your logic to discard sessions missing required scopes or with an expired token is correct. Ensure partial overlap of scopes is handled as expected (some use-cases might accept a superset of scopes).

Would you like to confirm if partial-superset is ever needed? Let me know if you’d like a quick code scan script to verify usage patterns.

---

226-261: getSession method nicely centralizes session logic.
Combining singleflight with session caching is a solid concurrency approach. The additional check to combine new scopes with the cached session’s scopes is also well-structured.

pkg/client/v1.go (6)

14-15: Reference to removed backoff and new retry usage.
The import line still references github.com/formancehq/ledger/pkg/client/retry, which is correct for the new logic; just ensure no stale references remain to the old backoff library.

Could you confirm no leftover references to the old backoff package exist? I can generate a script to grep for it across the codebase if needed.

---

84-86: Headers from o.SetHeaders.
Setting custom headers is a nice design. Validate no collisions with standard headers or frameworks that might rename them.

---

108-122: Check for permanent or temporary errors before returning.
You handle typical cases for retry.IsPermanentError(err) or retry.IsTemporaryError(err). This is a big improvement in clarity!

---

138-146: After retry response, calling Hooks.AfterSuccess.
Ensure the success hook is well tested, especially if further hooks can alter the response object. No issues spotted.

---

188-192: De-duplicated approach to fallback on global retry config.
This block consolidates logic, though watch for any edge cases if the local config is not set and the global config is also nil.

---

2687-2687: End of file updates.
No major concerns beyond ensuring consistent hooking of the new retry logic. Great job on standardizing the pattern across so many endpoints!