feat: support name filter on ListStores API

[ewanharris]

Description

Generates the SDK to include the changes to support passing the name filter to the ListStores API

References

Supersedes #195
Partly generated from openfga/sdk-generator#586
Closes #157

Review Checklist

• I have clicked on "allow edits by maintainers".
• I have added documentation for new/changed functionality in this PR or in a PR to openfga.dev [Provide a link to any relevant PRs in the references section above]
• The correct base branch is being used, if not main
• I have added tests to validate that the change in functionality is working as expected

Summary by CodeRabbit

• New Features

  • Added an optional name filter when listing stores to return exact-name matches.
  • Client options now support specifying a name for filtering.

• Documentation

  • Updated API docs and examples to include the new name parameter and usage.

• Tests

  • Added and updated unit and integration tests to cover name-based filtering and updated call signatures.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Walkthrough

Adds an optional exact-name filter to ListStores. Updates Java API signatures, client wiring, options object, docs, and tests to accept and forward a new String name query parameter; request URL construction includes name. Pagination and response semantics unchanged.

Changes

Cohort / File(s)	Summary of edits
Documentation: OpenFgaApi docs/OpenFgaApi.md	Updated method signatures, examples, parameter tables, and descriptions to include optional name for listStores and listStoresWithHttpInfo.
API Implementation: OpenFgaApi src/main/java/dev/openfga/sdk/api/OpenFgaApi.java	Added name parameter to public and private listStores overloads; forwarded it and included "name", name in pathWithParams; updated Javadoc.
Client Wiring src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java	Updated internal calls to pass name (default null or from options) to OpenFgaApi.listStores; public client API unchanged.
Client Options src/main/java/dev/openfga/sdk/api/configuration/ClientListStoresOptions.java	Added name field with fluent setter name(String) and getter getName().
Integration Tests: API src/test-integration/java/dev/openfga/sdk/api/OpenFgaApiIntegrationTest.java	Adapted existing listStores calls to include third name arg; added listStoresWithNameFilter test to assert exact-name filtering.
Integration Tests: Client src/test-integration/java/dev/openfga/sdk/api/client/OpenFgaClientIntegrationTest.java	Added listStoresWithNameFilter integration test using client options to pass name and asserting single-match result.
Unit Tests: API src/test/java/dev/openfga/sdk/api/OpenFgaApiTest.java	Updated tests to exercise new listStores overloads (including config override); adjusted mocks and assertions to cover name filtering and URL construction.
Unit Tests: Client src/test/java/dev/openfga/sdk/api/client/OpenFgaClientTest.java	Added unit tests for name filtering and combined parameters; small import updates.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor Caller
  participant Client as OpenFgaClient
  participant Api as OpenFgaApi
  participant HTTP as HTTP Client
  participant Service as OpenFGA

  Caller->>Client: listStores(options: pageSize?, continuationToken?, name?)
  Client->>Api: listStores(pageSize, continuationToken, name, overrides?)
  Api->>HTTP: GET /stores?page_size&continuation_token&name?
  HTTP->>Service: Request (name query present if provided)
  Service-->>HTTP: 200 OK (ListStoresResponse)
  HTTP-->>Api: ApiResponse<ListStoresResponse>
  Api-->>Client: CompletableFuture<ApiResponse<...>>
  Client-->>Caller: Future resolves with stores (filtered if name provided)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• Support passing name filter to ListStores #157 — Directly implements adding an optional name filter to ListStores in the Java SDK.
• Support passing name filter to ListStores js-sdk#214 — Same feature requested for JS SDK; this PR implements the analogous change for Java.
• Support List Stores name filter sdk-generator#517 — Matches generator-level change to support the List Stores name filter across SDKs.

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 18.52% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title Check	✅ Passed	The title concisely and accurately describes the primary change by indicating that the ListStores API now supports a name filter, using clear and specific wording that directly reflects the pull request’s main purpose.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 36.33%. Comparing base (e45fc26) to head (d860f91).

❌ Your project status has failed because the head coverage (36.33%) is below the target coverage (80.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@             Coverage Diff              @@
##               main     #237      +/-   ##
============================================
+ Coverage     36.30%   36.33%   +0.03%     
- Complexity     1138     1140       +2     
============================================
  Files           187      187              
  Lines          7170     7174       +4     
  Branches        822      822              
============================================
+ Hits           2603     2607       +4     
  Misses         4462     4462              
  Partials        105      105              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (2)

src/test-integration/java/dev/openfga/sdk/api/client/OpenFgaClientIntegrationTest.java (1)

144-168: Pipeline failure is expected per past review.

The test logic correctly:

1. Creates multiple stores with different names
2. Applies an exact name filter via ClientListStoresOptions
3. Asserts that only the target store is returned

Per the past review comment by ewanharris, this test failure during createStore will be resolved once #234 is merged and the OpenFGA version is updated.

src/test-integration/java/dev/openfga/sdk/api/OpenFgaApiIntegrationTest.java (1)

127-149: Pipeline failure is expected per past review.

The test correctly:

1. Creates multiple stores with different names
2. Filters by exact name using the third parameter
3. Validates that only one store is returned

Per the past review comment by ewanharris (line 128), this test failure during createStore will be resolved once #234 is merged and the OpenFGA version is updated.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e45fc26 and d5fb4a6.

📒 Files selected for processing (8)

• docs/OpenFgaApi.md (6 hunks)
• src/main/java/dev/openfga/sdk/api/OpenFgaApi.java (1 hunks)
• src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java (2 hunks)
• src/main/java/dev/openfga/sdk/api/configuration/ClientListStoresOptions.java (2 hunks)
• src/test-integration/java/dev/openfga/sdk/api/OpenFgaApiIntegrationTest.java (3 hunks)
• src/test-integration/java/dev/openfga/sdk/api/client/OpenFgaClientIntegrationTest.java (1 hunks)
• src/test/java/dev/openfga/sdk/api/OpenFgaApiTest.java (7 hunks)
• src/test/java/dev/openfga/sdk/api/client/OpenFgaClientTest.java (2 hunks)

🧰 Additional context used

🧬 Code graph analysis (1)

src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java (1)

src/main/java/dev/openfga/sdk/api/client/model/ClientListStoresResponse.java (1)

• ClientListStoresResponse (20-45)

🪛 GitHub Actions: Java CI with Gradle

src/test-integration/java/dev/openfga/sdk/api/client/OpenFgaClientIntegrationTest.java

[error] 371-371: FgaApiValidationError: createStore caused integration test failure during listStoresWithNameFilter (OpenFgaApiIntegrationTest).

src/test-integration/java/dev/openfga/sdk/api/OpenFgaApiIntegrationTest.java

[error] 1-1: Task ':integration' failed. Command: './gradlew build test-integration' (or equivalent). Failure: dev.openfga.sdk.errors.FgaApiValidationError: createStore during OpenFgaApiIntegrationTest.listStoresWithNameFilter (integration test)

🔇 Additional comments (7)

src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java (2)

87-87: LGTM!

The addition of the third null parameter for the name filter is correct and maintains backward compatibility.

---

97-98: LGTM!

The implementation correctly passes the name filter from options to the API layer, maintaining consistency with other optional parameters.

src/main/java/dev/openfga/sdk/api/configuration/ClientListStoresOptions.java (1)

21-21: LGTM!

The new name field with its fluent setter and getter follows the established pattern for other optional parameters in this class. The implementation is clean and consistent.

Also applies to: 51-58

src/test/java/dev/openfga/sdk/api/OpenFgaApiTest.java (3)

17-17: LGTM!

The import additions and mock setup changes properly support the new API signature with ArgumentMatchers.any() for flexible stubbing of the ConfigurationOverride parameter.

Also applies to: 35-35, 79-81

---

104-104: LGTM!

Correctly updated the existing test to pass null as the third parameter for the name filter, maintaining backward compatibility testing.

---

116-165: LGTM!

The three new test methods comprehensively cover:

1. Basic name filtering (lines 116-140)
2. Name-only parameter usage (lines 142-165)
3. ConfigurationOverride with name parameter (lines 167-191)

All tests properly verify URL construction with the name query parameter and validate the filtered response.

src/test-integration/java/dev/openfga/sdk/api/OpenFgaApiIntegrationTest.java (1)

87-87: LGTM!

The existing tests correctly updated to pass null as the third parameter for the name filter, maintaining compatibility with the new API signature.

Also applies to: 118-118