feat(feature-flags): Align rule and target management with API contracts

[stanleyphu]

Why

I hit a 400 while testing rule authoring with the flags app: the SDK sent feature_flag, while the API requires flag_slug. Rule creation, listing, and the convenience helper now accept flagSlug and send the correct field. Target lookup and filtered pagination handle both API contracts: a FlagTarget exposes ruleId; a LegacyFlagTarget exposes value and valueType.

Membership creation sends only rule_id and target_id. The helper retains the created rule and confirmed memberships after a later failure, and existing target aliases remain available.

This stacks on #1717, which removes the v1 polling types, so the API's target object takes the plain FlagTarget name. Retarget to main once #1717 merges.

Release prerequisite: deploy the target membership API contract tested at revision 7a0095af09e7, and enable rule authoring for the affected teams with the legacy target contract off.

Not covered by CI

• Verified the changed contract tests fail against the previous SDK and pass with this update.
• Ran the built SDK directly against the local API at 7a0095af09e7, without request translation: rule CRUD and evaluation-order pagination, membership lookup and combined filters, ascending/descending cursor pagination, duplicate/conflicting targets, helper success, partial failure, recovery, and sibling preservation all passed.
• Checked the flags app with SDK rule authoring: matching user exclusion before organization inclusion produces v1 true and v2 false; reversing the rules changes the live decision to true.
• Restored the legacy compatibility flag and verified target lookup/listing expose value/valueType without ruleId. Membership-only creation returns 400 in this mode, and the helper reports its retained empty rule.
• Removed all disposable fixtures and restored the local compatibility override.

Repeat the successful membership check against the deployed API before release.

Proof

The updated SDK sent this request directly to the local API:

POST /flag_rules
{"flag_slug":"sdk-rule-update-1791399585805","target_type":"user","value":false}

HTTP 201
{"object":"flag_rule","id":"flag_rule_01M4BVRT8FQ3N94ZPEVQX31SFZ","position":0,"value":false}

It then sent POST /flag_targets with {"rule_id":"flag_rule_01M4BVRT8FQ3N94ZPEVQX31SFZ","target_id":"user_01KM490ND31XPKGTYFAC9APFJ4"}. The API returned HTTP 201 with membership flag_target_01M4BVRTACYNBCS05B5N3W7Y6W, the same rule_id, and no value/value_type fields. Lookup and filtered listing returned the same membership.

A later missing organization returned 404: CreateRuleWithTargetsError retained rule flag_rule_01M4BVRZBSC0MCY1ASQTC6230Q and its one confirmed membership; the next target was not attempted. Adding that next target to the retained rule succeeded.

Response excerpts omit unchanged fields. These IDs belonged to disposable local fixtures that have been removed.

Fixes AUTH-7099

[linear-code]

AUTH-7099

AUTH-7214

[greptile-apps]

Confidence Score: 5/5

[Medium impact] The PR appears safe to merge; no actionable new issues remain.

Summary

Adds feature flag rule and membership management using the API’s field names.

• Callers can manage flag rules and their target memberships through the SDK.
• The rule helper keeps confirmed memberships when adding a target fails.
• Target reads keep the response shape returned by the API.

The earlier, unnumbered deployment finding is addressed by stanleyphu’s confirmation that the compatible API is in production. stanleyphu also states that rule authoring requires the legacy target contract to be off. Retaining partial helper progress is intentional so callers can recover.

Review checks covered source code, contract tests, and dependent callers in PR #1721. No tests or live API calls were run during this review.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Create rule] --> B{Rule created?}
  B -->|No| C[Return original error]
  B -->|Yes| D[Add next membership]
  D --> E{Request succeeded?}
  E -->|Yes| F{More targets?}
  F -->|Yes| D
  F -->|No| G[Return rule and targets]
  E -->|No| H[Throw CreateRuleWithTargetsError]
  H --> I[Keep rule and confirmed memberships]

Loading

_{Reviews (4) · Last reviewed commit: "docs: Remove rollout notes from feature ..." · Reviewed by Greptile}

[stanleyphu]

@greptileai review

Updated at 79c70669721269c3d45fdd909c54105bcfbbb02b to match the target contracts from workos/workos#75124. Direct live SDK checks against API revision 7a0095af09e7 now pass for membership creation, lookup/listing under both contracts, partial failure and recovery. The PR description retains the deployed-API prerequisite and compatibility gate requirements.

[workos-shipyard]

⚓ Shipyard review suggestion

Suggested team: dx, based on recent contributors to the changed files (@gjtorikian, @nicknisi).

• Assign @gjtorikian · 2 assignments in the last 7 days
• Assign @nicknisi · 2 assignments in the last 7 days
• Pick for me · balances recent workload

Links open Shipyard for confirmation. Choosing a reviewer overrides availability; “Pick for me” skips known absences.
Comment /tag <team> for a team or /tag to infer one. Tag the same team again to reroll.

Shipyard Analysis

⏳ Generating analysis...

⚓ Explore the analysis in depth in Shipyard · 🔄 Re-run analysis

[workos-shipyard]

⚓ Review requested from @nicknisi for team dx, requested by @stanleyphu.

Shipyard Analysis

⏳ Generating analysis...

⚓ Explore the analysis in depth in Shipyard · 🔄 Re-run analysis

[stanleyphu]

@greptileai review

[stanleyphu]

@greptileai review