SDK: Unified GraphQL Query Management with Fragment Merging

[rjvelazco]

Parent Issue

#30943

Overview of the Issue:

To enable a unified and flexible GraphQL querying system, we need to implement a method client.gql that:

1. Merges a base query with user-defined custom queries using GraphQL fragments.
2. Ensures the base query includes all required fields for the Universal Visual Editor (UVE) to function correctly.
3. Provides flexibility by supporting optional properties for page, content, and nav, requiring at least one.
4. Processes the _map fields in the response to remove them from the output while maintaining their parsed values.

This method will be critical for both developers using the SDK and for internal UVE operations, ensuring consistent and optimized GraphQL usage.

Task

1. Define the Base Query:

   • Create a base query constant that includes all required fields for UVE functionality.
   • Ensure it covers required params like url and optional fields like language and depth.

2. Implement the client.gql Method:

   • Accept input for page, content, and nav queries.
   • Validate that at least one of page, content, or nav, is provided.
   • Merge the base query with user-provided custom queries using GraphQL fragments.

3. Parse _map Fields:

• Remove _map fields from the GraphQL response.
• Parse and include _map values in the output data structure.

4. Test the Method:

   • Write unit tests to validate the following:
   • Query merging works as expected.
   • The method handles input where only page or content is provided.
   • _map fields are correctly parsed and removed from the response.
   • Error handling for invalid input (e.g., missing page and content).

5. Document the Method:

• Add detailed documentation in the README.md:
• Example usage with a base query and custom query.
• Explanation of required vs. optional properties.
• Description of _map parsing behavior.

Proposed Objective

Technical User Experience

Proposed Priority

Priority 2 - Important

Acceptance Criteria

• The client.gql method correctly merges the base query with custom queries using GraphQL fragments.
• The method validates input to ensure at least one of page, content, or nav` is provided.
• _map fields are parsed and removed from the response.
• The method returns the expected structure: { data, params }.
• Comprehensive unit tests are implemented for all use cases and edge cases.
• Documentation in README.md provides clear guidance for usage and integration.

Sub-Tasks & Estimates

1. Define the base GraphQL query constant.
2. Implement the client.gql method.
3. Add validation for required inputs (page, content, or nav).
4. Parse _map fields in the response.
5. Write unit tests for the method.
6. Update the README.md with usage examples and details.

External Links... Slack Conversations, Support Tickets, Figma Designs, etc.

POC: #30814