feat: Add resource and role_slug filter params to list role assignments

[atainter]

Description

Adds optional query filters to the authorization role-assignment listing endpoints, matching the new backend support:

• listRoleAssignments (membership-scoped) gains resourceId, resourceExternalId, and resourceTypeSlug filters.
• listRoleAssignmentsForResource and listResourceRoleAssignments (resource-scoped, by ID and by external ID respectively) gain a roleSlug filter.

Summary by CodeRabbit

• New Features

  • Role-assignment listing APIs now support filtering by resource internal ID, resource external ID, resource type slug, and role slug.

• Tests

  • Added test coverage validating the new filtering options for role-assignment listing endpoints.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 0f55965f-f15a-475f-80ef-9bc4bf1e061c

📥 Commits

Reviewing files that changed from the base of the PR and between 1d62fd6 and cbf4114.

📒 Files selected for processing (2)

• src/authorization/interfaces/list-role-assignments-for-resource-by-external-id-options.interface.ts
• src/authorization/interfaces/list-role-assignments-for-resource-options.interface.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• src/authorization/interfaces/list-role-assignments-for-resource-options.interface.ts

---

📝 Walkthrough

Walkthrough

This PR adds filter options to role-assignment listing APIs, implements serializers to convert those options to snake_case, integrates serializers into Authorization listing methods, and adds Jest tests asserting serialized query parameters.

Changes

Role-assignment listing filter options

Layer / File(s)	Summary
Filter option contracts and serialized forms src/authorization/interfaces/list-role-assignments-options.interface.ts, src/authorization/interfaces/list-role-assignments-for-resource-options.interface.ts, src/authorization/interfaces/list-role-assignments-for-resource-by-external-id-options.interface.ts	ListRoleAssignmentsOptions adds optional resourceId, resourceExternalId, resourceTypeSlug; ListRoleAssignmentsForResourceOptions and ListRoleAssignmentsForResourceByExternalIdOptions add optional roleSlug. New serialized interfaces expose snake_case fields.
Serializer functions src/authorization/serializers/list-role-assignments-options.serializer.ts, src/authorization/serializers/list-role-assignments-for-resource-options.serializer.ts	New serializeListRoleAssignmentsOptions and serializeListRoleAssignmentsForResourceOptions map camelCase filters to snake_case and merge pagination serialization.
Serializer module exports src/authorization/serializers/index.ts	Re-exports the new serializer modules.
Authorization method integration src/authorization/authorization.ts	listRoleAssignments, listRoleAssignmentsForResource, and listResourceRoleAssignments now compute serializedOptions and pass them to both initial and paginated fetchAndDeserialize calls.
Filter option test coverage src/authorization/authorization.spec.ts	Adds tests asserting serialized query parameters for listRoleAssignments (resource ID, external ID + type slug, type slug), listRoleAssignmentsForResource (role slug), and listResourceRoleAssignments (role slug).

Possibly related PRs

• workos/workos-node#1580: Updates the same Authorization listing methods (listRoleAssignmentsForResource, listResourceRoleAssignments) by serializing query/filter options before fetching.
• workos/workos-node#1553: Modifies listRoleAssignments in authorization.ts by altering how query parameters and options are serialized and passed into paginated fetch logic.

Suggested reviewers

• nicknisi
• cmatheson

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description covers the core changes and specifies which endpoints gain which filters, but the template requires a documentation section that is missing.	Complete the Documentation section by indicating whether docs updates are needed and, if yes, linking the related docs PR.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding resource and role_slug filter parameters to list role assignments APIs.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch at-list-assignments-filter-params

---

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

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

src/authorization/authorization.spec.ts (1)

1756-1769: ⚡ Quick win

Add a standalone resourceExternalId filter test case.

Line 1756 through Line 1769 cover combo filtering, but there’s no test for resourceExternalId alone even though the options contract allows it independently. Adding that case will lock in the intended behavior.

Suggested test addition

+    it('filters by resource external id only', async () => {
+      fetchOnce(listRoleAssignmentsFixture);
+
+      await workos.authorization.listRoleAssignments({
+        organizationMembershipId: testOrgMembershipId,
+        resourceExternalId: 'doc-456',
+      });
+
+      expect(fetchSearchParams()).toMatchObject({
+        resource_external_id: 'doc-456',
+      });
+    });

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 7f6b6763-8b6b-40c4-bb09-90781c45c7af

📥 Commits

Reviewing files that changed from the base of the PR and between 2f48914 and 1d62fd6.

📒 Files selected for processing (8)

• src/authorization/authorization.spec.ts
• src/authorization/authorization.ts
• src/authorization/interfaces/list-role-assignments-for-resource-by-external-id-options.interface.ts
• src/authorization/interfaces/list-role-assignments-for-resource-options.interface.ts
• src/authorization/interfaces/list-role-assignments-options.interface.ts
• src/authorization/serializers/index.ts
• src/authorization/serializers/list-role-assignments-for-resource-options.serializer.ts
• src/authorization/serializers/list-role-assignments-options.serializer.ts

[greptile-apps]

Greptile Summary

This PR extends three role-assignment listing endpoints with new optional filter query parameters (resourceId, resourceExternalId, resourceTypeSlug, and roleSlug) by adding dedicated serializers that convert camelCase option keys to the snake_case names the backend expects.

• New serializers (serializeListRoleAssignmentsOptions, serializeListRoleAssignmentsForResourceOptions) follow existing codebase patterns and correctly gate each field on truthiness before spreading.
• authorization.ts now routes all three listing methods through the appropriate serializer instead of passing raw queryOptions directly, fixing what would have been silently no-op camelCase params on the new fields.
• Tests cover the primary filter combinations, though a test for resourceExternalId used alone (as described in the JSDoc) is missing.

Confidence Score: 4/5

Safe to merge; changes are additive and the serialization logic is well-aligned with existing patterns.

The implementation is straightforward and follows established codebase conventions. The only gap is a missing test for resourceExternalId used without resourceTypeSlug, which the JSDoc explicitly permits but no test exercises.

src/authorization/authorization.spec.ts — the resourceExternalId-only filter path is untested.

Important Files Changed

Filename	Overview
src/authorization/authorization.ts	Correctly wires the two new serializers into all three role-assignment listing methods, replacing raw camelCase queryOptions with properly snake_cased serializedOptions.
src/authorization/serializers/list-role-assignments-options.serializer.ts	New serializer converting camelCase filter options (resourceId, resourceExternalId, resourceTypeSlug) to snake_case; consistent with existing serializer patterns in the codebase.
src/authorization/serializers/list-role-assignments-for-resource-options.serializer.ts	New serializer converting roleSlug to role_slug; shared between listRoleAssignmentsForResource and listResourceRoleAssignments, which is clean since both expose only roleSlug as the new filter.
src/authorization/interfaces/list-role-assignments-options.interface.ts	Adds resourceId, resourceExternalId, and resourceTypeSlug optional fields plus the SerializedListRoleAssignmentsOptions interface; well-documented with JSDoc.
src/authorization/interfaces/list-role-assignments-for-resource-options.interface.ts	Adds roleSlug optional field and SerializedListRoleAssignmentsForResourceOptions interface; also re-used by the by-external-id flow.
src/authorization/interfaces/list-role-assignments-for-resource-by-external-id-options.interface.ts	Adds roleSlug optional field with JSDoc; minimal, clean change.
src/authorization/authorization.spec.ts	Adds test coverage for new filter params across all three methods; missing a test for resourceExternalId used in isolation (the JSDoc notes it can be used alone).
src/authorization/serializers/index.ts	Exports the two new serializers; ordering is consistent with surrounding exports.

Sequence Diagram

sequenceDiagram
    participant Caller
    participant Authorization
    participant Serializer
    participant API

    Caller->>Authorization: "listRoleAssignments({ organizationMembershipId, resourceId?, resourceExternalId?, resourceTypeSlug?, ...pagination })"
    Authorization->>Serializer: serializeListRoleAssignmentsOptions(queryOptions)
    Serializer-->>Authorization: "{ resource_id?, resource_external_id?, resource_type_slug?, ...paginationKeys }"
    Authorization->>API: "GET /organization_memberships/:id/role_assignments?resource_id=..."

    Caller->>Authorization: "listRoleAssignmentsForResource({ resourceId, roleSlug?, ...pagination })"
    Authorization->>Serializer: serializeListRoleAssignmentsForResourceOptions(queryOptions)
    Serializer-->>Authorization: "{ role_slug?, ...paginationKeys }"
    Authorization->>API: "GET /resources/:id/role_assignments?role_slug=..."

    Caller->>Authorization: "listResourceRoleAssignments({ organizationId, resourceTypeSlug, externalId, roleSlug?, ...pagination })"
    Authorization->>Serializer: serializeListRoleAssignmentsForResourceOptions(queryOptions)
    Serializer-->>Authorization: "{ role_slug?, ...paginationKeys }"
    Authorization->>API: "GET /organizations/:orgId/resources/:type/:extId/role_assignments?role_slug=..."

Loading

Comments Outside Diff (1)

1. src/authorization/authorization.spec.ts, line 1770-1786 (link)

   Missing test for resourceExternalId used in isolation

   The JSDoc on resourceExternalId states it "Can be used on its own or combined with resourceTypeSlug", but there is no test exercising it without resourceTypeSlug. The existing test only covers the combined case, so if the serializer ever dropped the key when resourceTypeSlug is absent, that path would go undetected.

_{Reviews (1): Last reviewed commit: "Prettier" | Re-trigger Greptile}